> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Courses

> Returns a paginated list of published courses, with optional filtering by category, keyword, and home page flag.

# List Courses

Returns a paginated list of published courses for the current location. Supports filtering by category name, keyword search, and a flag to only return courses marked for the home page.

<Note>
  A **course** is a structured learning programme created by the space operator, consisting of multiple lessons. Members can enrol, track progress,
  and complete lessons through the portal.
</Note>

## Authentication

No authentication required.

## Query Parameters

<ParamField query="page" type="number" required>
  1-based page number.
</ParamField>

<ParamField query="top" type="number" required>
  Number of courses per page.
</ParamField>

<ParamField query="category" type="string">
  Filter by category name. Omit to return courses across all categories.
</ParamField>

<ParamField query="search" type="string">
  Keyword filter applied to course name and description. URL-encoded.
</ParamField>

<ParamField query="onlyHomePage" type="boolean">
  When `true`, returns only courses flagged to appear on the portal home page.
</ParamField>

<ParamField query="_shape" type="string">
  Comma-separated list of field paths to include in the response. When provided, only the
  specified fields are returned — useful for reducing payload size. Supports nested paths
  using dot notation. Example: `_shape=Courses.Records.Name,Courses.Records.Description,Categories`.
</ParamField>

## Response

Returns a `CourseList` object containing available categories and a paginated list of course summaries.

<ResponseField name="Categories" type="string[]">
  Array of all available course category names for filtering.
</ResponseField>

<ResponseField name="Courses" type="ApiListResult<CourseStatus>">
  Paginated wrapper containing course records.
</ResponseField>

<ResponseField name="Courses.Records" type="CourseStatus[]">
  Array of course summaries for the current page.
</ResponseField>

<ResponseField name="Courses.CurrentPage" type="number">
  Current page number.
</ResponseField>

<ResponseField name="Courses.TotalItems" type="number">
  Total number of matching courses.
</ResponseField>

<ResponseField name="Courses.TotalPages" type="number">
  Total number of pages.
</ResponseField>

<ResponseField name="Courses.HasNextPage" type="boolean">
  Whether there are more pages after the current one.
</ResponseField>

## Examples

### Fetch first page of courses

```http theme={null}
GET /api/public/courses/v2?page=1&top=10
```

## TypeScript Integration

```typescript theme={null}
import endpoints from '@/api/endpoints'

const { resource: courses } = useTypedData(
  httpClient,
  endpoints.courses.list({
    page: 1,
    top: 10,
    categoryName: 'Marketing',
  }),
)
```