> ## 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 Events

> Returns a paginated list of published events, with optional filtering by category, keyword, date range, and featured status.

# List Events

Returns a paginated list of published calendar events for the current location. Supports filtering by past/upcoming, category, keyword search, and featured flag. Used to power the public-facing events catalogue and homepage event grids.

<Note>
  An **event** is a scheduled activity (workshop, networking session, etc.) published by the space operator. Events may have one or more **ticket
  products** with their own prices and availability windows.
</Note>

## Authentication

No authentication required. The response is scoped to the current business location.

## Query Parameters

<ParamField query="pastEvents" type="boolean" required>
  `true` — return events whose end date is in the past. `false` — return upcoming and active events.
</ParamField>

<ParamField query="page" type="number">
  1-based page number. **Default**: `1`
</ParamField>

<ParamField query="top" type="number">
  Number of events per page. **Default**: `25`
</ParamField>

<ParamField query="categoryId" type="number">
  Filter to events belonging to a specific category. Omit to return events across all categories.
</ParamField>

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

<ParamField query="featured" type="boolean">
  When `true`, returns only events marked as featured by the operator.
</ParamField>

<ParamField query="onlyHomePage" type="boolean">
  When `true`, returns only events that the operator has flagged to appear on the home page. Used by the `upcomingEvents` shortcut endpoint.
</ParamField>

<ParamField query="_shape" type="string">
  Comma-separated dot-notated field paths to include in the response. When provided, only the
  specified fields are returned — useful for reducing payload size. **Example**:
  `_shape=CalendarEvents.Records.Id,CalendarEvents.Records.Name`
</ParamField>

## Response

Returns an `EventList` object containing pagination metadata and the paginated event records.

### Core Fields

<ResponseField name="PastEvents" type="boolean" required>
  Mirrors the `pastEvents` query parameter, confirming which slice of events was returned.
</ResponseField>

<ResponseField name="Categories" type="EventCategory[]">
  All available event categories for the current location — useful for building a category filter UI without a separate request.
</ResponseField>

<ResponseField name="Category" type="EventCategory | null">
  The currently active category filter, if `categoryId` was supplied.
</ResponseField>

<ResponseField name="CalendarEvents" type="ApiListResult<CalendarEvent>">
  Paginated wrapper containing the matching events. See [API Overview](/api/overview) for pagination fields (`CurrentPage`, `TotalItems`, etc.).
</ResponseField>

### CalendarEvent Fields

<ResponseField name="CalendarEvents.Records[].Id" type="number" required>
  Unique integer identifier for the event. Use this as `{id}` in detail, product, and waiting-list endpoints.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].UniqueId" type="string">
  UUID for the event — stable across edits and suitable as a cache key.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].Name" type="string" required>
  Display name of the event.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].ShortDescription" type="string">
  Brief summary shown in list cards.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].LongDescription" type="string">
  Full event description. May contain HTML.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].HostFullName" type="string | null">
  Full name of the event host.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].Location" type="string | null">
  Venue name or room identifier.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].VenueAddress" type="string | null">
  Full postal address of the event venue.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].WebAddress" type="string | null">
  External event URL (e.g., a Zoom or Eventbrite link).
</ResponseField>

<ResponseField name="CalendarEvents.Records[].FacebookPage" type="string | null">
  Facebook event page URL.
</ResponseField>

### Dates

<ResponseField name="CalendarEvents.Records[].StartDate" type="string">
  Event start datetime in the location's local timezone (ISO 8601).
</ResponseField>

<ResponseField name="CalendarEvents.Records[].EndDate" type="string">
  Event end datetime in the location's local timezone (ISO 8601).
</ResponseField>

<ResponseField name="CalendarEvents.Records[].StartDateUtc" type="string">
  Event start datetime in UTC (ISO 8601).
</ResponseField>

<ResponseField name="CalendarEvents.Records[].EndDateUtc" type="string">
  Event end datetime in UTC (ISO 8601).
</ResponseField>

<ResponseField name="CalendarEvents.Records[].MultipleDays" type="boolean">
  When `true`, the event spans more than one calendar day.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].PublishDate" type="string">
  Local datetime from which the event becomes visible to customers.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].PublishDateUtc" type="string">
  UTC equivalent of `PublishDate`.
</ResponseField>

### Tickets & Pricing

<ResponseField name="CalendarEvents.Records[].HasTickets" type="boolean">
  When `true`, the event has at least one purchasable ticket product.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].SoldOut" type="boolean">
  When `true`, all ticket products are sold out or past their sale window.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].ChepeastPrice" type="number">
  Lowest ticket price across all ticket products. Note the typo in the field name (`Chepeast`) — it is preserved as-is in the API.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].MostExpensivePrice" type="number">
  Highest ticket price across all ticket products.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].ChepeastProduct" type="EventProduct | null">
  Full `EventProduct` object for the cheapest ticket option.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].MostExpensiveProduct" type="EventProduct | null">
  Full `EventProduct` object for the most expensive ticket option.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].EventProducts" type="EventProduct[]">
  All ticket products for this event.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].TicketsPage" type="string | null">
  External URL for purchasing tickets when `HasCustomTicketsPage` is `true`.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].HasCustomTicketsPage" type="boolean">
  When `true`, ticket purchase is handled on an external page (`TicketsPage`) rather than the portal checkout.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].Allocation" type="number | null">
  Total number of available spots. `null` means unlimited.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].Sales" type="number | null">
  Number of tickets sold so far.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].EnableWaitList" type="boolean">
  When `true`, customers can join a waiting list when the event is sold out.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].TicketNotes" type="string | null">
  Additional notes displayed to customers during ticket purchase.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].AskBuyerAddress" type="boolean">
  When `true`, the checkout form collects the buyer's postal address.
</ResponseField>

### Categorisation & Display

<ResponseField name="CalendarEvents.Records[].EventCategories" type="EventCategory[]">
  Categories this event belongs to.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].ShowInHomePage" type="boolean">
  When `true`, the event appears on the portal home page.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].ShowInHomeBanner" type="boolean">
  When `true`, the event is promoted in the home page banner carousel.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].AllowComments" type="boolean">
  When `true`, authenticated customers can post and view comments on the event detail page.
</ResponseField>

### Media & Resource

<ResponseField name="CalendarEvents.Records[].HasSmallImage" type="boolean">
  When `true`, a small thumbnail image is available.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].HasLargeImage" type="boolean">
  When `true`, a full-size banner image is available.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].HasAddress" type="boolean">
  Convenience flag — `true` when either `Location` or `VenueAddress` is set.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].Resource" type="Resource | null">
  The bookable resource associated with this event, if the event is tied to a room or desk.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].HasResource" type="boolean">
  When `true`, a resource is linked to this event (`Resource` is non-null).
</ResponseField>

<ResponseField name="CalendarEvents.Records[].Business" type="Business">
  The coworking location that published the event.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].Recent10Attendees" type="{ Id: number; UpdatedOn: string }[] | null">
  Lightweight list of up to 10 recent attendees, used for social proof display.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].Comments" type="EventComment[]">
  Published comments on the event.
</ResponseField>

### Timestamps

All datetime fields are ISO 8601 strings. `*On` fields are in the location's local timezone; `*OnUtc` fields are UTC.

<ResponseField name="CalendarEvents.Records[].CreatedOn" type="string">
  Local datetime the event record was created.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].CreatedOnUtc" type="string">
  UTC datetime the event record was created.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].UpdatedOn" type="string">
  Local datetime of the last update.
</ResponseField>

<ResponseField name="CalendarEvents.Records[].UpdatedOnUtc" type="string">
  UTC datetime of the last update.
</ResponseField>

## Examples

### Fetch upcoming events (full payload)

```http theme={null}
GET /api/public/events?pastEvents=false&page=1&top=9
```

```json theme={null}
{
  "PastEvents": false,
  "Categories": [
    {
      "Id": 3,
      "Title": "Workshops",
      "UniqueId": "a1b2c3d4-...",
      "CreatedOn": "2024-01-10T10:00:00",
      "UpdatedOn": "2024-01-10T10:00:00",
      "CreatedOnUtc": "2024-01-10T10:00:00Z",
      "UpdatedOnUtc": "2024-01-10T10:00:00Z",
      "IdString": "3",
      "IsNull": false
    }
  ],
  "Category": null,
  "CalendarEvents": {
    "Records": [
      {
        "Id": 412,
        "Name": "Morning Yoga & Mindfulness",
        "ShortDescription": "Start your week with a guided yoga session open to all levels.",
        "LongDescription": "<p>Join us every Monday for a 45-minute yoga session...</p>",
        "HostFullName": "Sarah Chen",
        "Location": "Studio Room B",
        "VenueAddress": null,
        "StartDate": "2026-03-23T07:30:00",
        "EndDate": "2026-03-23T08:15:00",
        "StartDateUtc": "2026-03-23T07:30:00Z",
        "EndDateUtc": "2026-03-23T08:15:00Z",
        "MultipleDays": false,
        "HasTickets": true,
        "SoldOut": false,
        "ChepeastPrice": 0,
        "MostExpensivePrice": 12.0,
        "HasCustomTicketsPage": false,
        "TicketsPage": null,
        "Allocation": 20,
        "Sales": 7,
        "EnableWaitList": false,
        "AllowComments": true,
        "ShowInHomePage": true,
        "ShowInHomeBanner": false,
        "HasSmallImage": true,
        "HasLargeImage": true,
        "HasAddress": true,
        "HasResource": false,
        "Resource": null,
        "EventCategories": [{ "Id": 3, "Title": "Workshops" }],
        "EventProducts": [{ "Id": 88, "Name": "Free Entry", "Price": 0, "TicketsLeft": 13, "SoldOut": false, "IsAvailableNow": true }],
        "Business": { "Id": 5, "Name": "Downtown Coworking Hub" },
        "Comments": [],
        "UniqueId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "IdString": "412",
        "CreatedOn": "2025-11-01T09:00:00",
        "UpdatedOn": "2026-03-01T12:00:00",
        "CreatedOnUtc": "2025-11-01T09:00:00Z",
        "UpdatedOnUtc": "2026-03-01T12:00:00Z",
        "IsNull": false
      }
    ],
    "CurrentPage": 1,
    "CurrentPageSize": 9,
    "TotalItems": 1,
    "TotalPages": 1,
    "HasNextPage": false,
    "HasPreviousPage": false
  }
}
```

### Fetch events with a minimal field set

Use `_shape` to return only the data your UI needs, reducing payload size.

```http theme={null}
GET /api/public/events?pastEvents=false&page=1&top=9&_shape=CalendarEvents.Records.Id,CalendarEvents.Records.Name,CalendarEvents.Records.StartDateUtc,CalendarEvents.Records.HasLargeImage
```

```json theme={null}
{
  "CalendarEvents": {
    "Records": [{ "Id": 412, "Name": "Morning Yoga & Mindfulness", "StartDateUtc": "2026-03-23T07:30:00Z", "HasLargeImage": true }],
    "CurrentPage": 1,
    "CurrentPageSize": 9,
    "TotalItems": 1,
    "TotalPages": 1,
    "HasNextPage": false,
    "HasPreviousPage": false
  }
}
```

## TypeScript Integration

```typescript theme={null}
import endpoints from '@/api/endpoints'
import { EventList } from '@/types/endpoints/EventList'
import { useData } from '@/api/fetchData'

const endpoint = endpoints.events.events({
  pastEvents: false,
  page: 1,
  top: 9,
  categoryId: undefined,
  search: undefined,
  featured: false,
})

const { resource: eventList } = useData<EventList>(httpClient, endpoint.url, {
  shape: {
    fields: [
      'CalendarEvents.Records.Id',
      'CalendarEvents.Records.Name',
      'CalendarEvents.Records.StartDateUtc',
      'CalendarEvents.Records.HasLargeImage',
      'CalendarEvents.Records.ChepeastPrice',
      'CalendarEvents.Records.SoldOut',
    ],
  },
})
```

## Usage in Portal

| Context                                 | Source file                                                      |
| --------------------------------------- | ---------------------------------------------------------------- |
| Events catalogue (`/events`)            | `src/views/events/list/useEventsData.ts`                         |
| Homepage events grid (public home page) | `src/views/public/home-business/components/SimpleEventsGrid.tsx` |

## Error Responses

<ResponseField name="400 Bad Request" type="error">
  A query parameter value is invalid — for example, a non-boolean `pastEvents` or a negative `page`.
</ResponseField>

## Related Endpoints

| Method | Endpoint                                           | Description                                       |
| ------ | -------------------------------------------------- | ------------------------------------------------- |
| `GET`  | `/api/public/events/{id}`                          | Full detail for a single event                    |
| `GET`  | `/api/public/events?onlyHomePage=true`             | Upcoming home-page events (no auth required)      |
| `GET`  | `/api/public/events/my`                            | Events the authenticated customer has tickets for |
| `GET`  | `/api/public/events/{eventId}/product/{productId}` | Ticket product detail                             |
| `POST` | `/api/public/events/{id}/joinWaitingList`          | Join the waiting list for a sold-out event        |