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

# Introduction

Learn the conventions the Zenamu API uses across every endpoint: how you
authenticate, how responses are shaped, and how dates, filters, and errors work.

## Conventions

The base URL is `https://api.zenamu.com`. The API follows REST conventions:
resources are read with `GET`, filtered by query parameters, and modified with
`POST` and a JSON body. Requests and responses are JSON.

* HTTPS only
* Paths are versioned: `/v1/classes`, `/v1/clients`
* Resource paths use plural nouns

## Two tiers of access

Endpoints split into two groups by the key they accept.

| Tier    | Key          | Endpoints                                                           | Browser |
| ------- | ------------ | ------------------------------------------------------------------- | ------- |
| Public  | `zen_pub_…`  | `/v1/classes`, `/v1/workshops`, `/v1/lecturers`, `/v1/places`       | Yes     |
| Private | `zen_live_…` | `/v1/clients`, `/v1/pass-groups`, and the credit and pass endpoints | No      |

[Read the authentication guide](/api/authentication).

## Response envelope

Every successful response has the same three keys. The payload is always under
`data` — an array for list endpoints, an object for the credit and pass
endpoints.

```json theme={null}
{
  "statusCode": 200,
  "message": "Success",
  "data": []
}
```

Errors replace `data` with `error` and a human-readable `message`.
[Read the errors guide](/api/errors).

## IDs

Two kinds of ID appear in responses, and they are not interchangeable.

`_id` is an **opaque string**. Classes, workshops, lecturers, and places are
identified this way. Treat it as a string, store it as given, and never parse or
increment it.

`id` is a **sequential integer**. Clients, pass groups, and tags use it, and it
is the value the write endpoints and the filter parameters expect.

<Note>
  A class carries `_id` only; a client carries both `id` and `_id`. When granting
  credits or passes, always send the client's numeric `id`.
</Note>

## Dates and time zones

[Read the dates guide](/api/dates).

Date-only fields use `YYYY-MM-DD`. Events carry their start and end three times
over — in UTC, in the studio's local time with an offset, and as an IANA
`timezone` name — so you never have to guess which zone a timestamp is in.

## Pagination

[Read the pagination guide](/api/pagination).

The schedule endpoints accept `limit` and `offset`. Omit them and you get every
event in the requested date range.

## Filtering

[Read the filtering guide](/api/filtering).

Filters take comma-separated numeric IDs, for example
`lecturerIds=5,10`. Each endpoint documents the filters it supports.

## Plans and access

| Plan          | Public endpoints | Private endpoints |
| ------------- | ---------------- | ----------------- |
| Free          | No               | No                |
| Any paid plan | Yes              | No                |
| Ultimate      | Yes              | Yes               |
| Trial         | Yes              | Yes               |

The check runs on **every request**, so a downgrade takes effect immediately
even though the keys keep working, and restoring the plan restores access
without regenerating anything. If Zenamu cannot determine a studio's plan, the
request is denied with `403` rather than allowed.

## Rate limits

[Read the rate limits guide](/api/rate-limits).

100 requests per minute, per endpoint.

## Errors

[Read the errors guide](/api/errors) and the
[status codes](/api/status-codes).

## Objects

<Columns cols={2}>
  <Card title="Class" icon="calendar-days" href="/api/objects/class">
    A class or one session of a course.
  </Card>

  <Card title="Workshop" icon="sparkles" href="/api/objects/workshop">
    A standalone event with its own address.
  </Card>

  <Card title="Lecturer" icon="user" href="/api/objects/lecturer">
    A lecturer profile.
  </Card>

  <Card title="Place" icon="map-pin" href="/api/objects/place">
    A physical location.
  </Card>

  <Card title="Client" icon="users" href="/api/objects/client">
    A studio client with balances and history.
  </Card>

  <Card title="Pass group" icon="ticket" href="/api/objects/pass-group">
    A category of entry passes.
  </Card>

  <Card title="Pricing option" icon="tag" href="/api/objects/pricing-option">
    One way to pay for an event.
  </Card>
</Columns>