> ## Documentation Index
> Fetch the complete documentation index at: https://www.help.creatora.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API conventions

> Authentication, access mode, variables, pagination, errors, and mutation retries.

## Requests and access mode

Send JSON GraphQL requests to `POST https://api.creatora.io/graphql`. Put the named operation in `query` and its variable values in `variables`. The Queries, Mutations and Types sections of this API Reference define the supported public surface. The [production SDL](https://api.creatora.io/sdl) contains additional exposed implementation operations.

The Administrator JWT is available in **Admin Panel → Platform → API → Developer**. See [Authentication](/en/api/authentication) for its handling. Send it as:

```http theme={null}
Authorization: Bearer <JWT>
X-CREATORA-ACCESS-MODE: administrator
Content-Type: application/json
```

Authentication identifies the account. Access mode selects the request context. Without `X-CREATORA-ACCESS-MODE: administrator`, the request uses Student mode even with an Administrator JWT. A valid JWT with the wrong mode can therefore return Student-context data or an authorization error. Check this header first when an Administrator operation appears to have insufficient access.

Treat the copied JWT as a secret. Signing out of the browser does not revoke a copied token.

## Values in variables

| Scalar     | Format to use                                                               |
| ---------- | --------------------------------------------------------------------------- |
| `UUID`     | A UUID string. Use the ID returned by the preceding operation.              |
| `DateTime` | Unix time in milliseconds, as an integer.                                   |
| `Long`     | A JSON integer.                                                             |
| `Map`      | A JSON object on output; the current scalar does not accept an input value. |
| `Unit`     | `"OK"` on output. This is not a receipt for downstream integrations.        |

## Lists and pagination

Pagination depends on the operation. `courses` accepts `limit` but no continuation cursor. `students`, `customOffers` and `orders` accept `pagination` with `limit` and `beforeMillis`. For the latter collections, `beforeMillis` filters records with a `createdOn` value strictly earlier than the supplied Unix-millisecond timestamp.

Use `limit` to keep a request bounded. Do not treat repeated pages as a guaranteed complete export. Records sharing a timestamp can be skipped by a strict timestamp cursor, and Order sorting does not follow the `createdOn` cursor alone. The recipes below use bounded reads; they do not promise a lossless traversal of every record.

## Errors and mutation retries

An executed GraphQL request can return HTTP `200` with partial `data` and an `errors` array. Check `errors` even when the HTTP request succeeded. Some authorization errors use `errors[].extensions.name`, including `ENTITY_PERMISSION.UNAUTHORIZED`; not every error has the same extension or a single Creatora error code.

For example, a request that selected `thisFieldDoesNotExist` from `me` returned this **GraphQL validation error**:

```json theme={null}
{
  "errors": [
    {
      "message": "Validation error (FieldUndefined@[me/thisFieldDoesNotExist]) : Field 'thisFieldDoesNotExist' in type 'Student' is undefined",
      "locations": [
        {
          "line": 1,
          "column": 37
        }
      ],
      "extensions": {}
    }
  ]
}
```

This means the requested field is absent from the current schema. Check the field name in the [SDL](https://api.creatora.io/sdl). The example does not indicate an authentication or access-mode failure; `locations` points to the invalid selection in that request.

If an Administrator request returns an authorization error, check the `Authorization` value and `X-CREATORA-ACCESS-MODE: administrator` before changing the GraphQL operation.

A timeout or partial response does not prove that a mutation was rolled back. Before repeating `createCourse` or a direct Course grant, inspect the current Course or Student access state as described in its recipe. Do not retry either mutation blindly.