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

# API Reference

> Base URL, authentication, versioning, pagination, errors, rate limits, idempotency and the shared response conventions for the Fanvue API.

The Fanvue API is a REST API that speaks JSON over HTTPS. All requests are made to:

```
https://api.fanvue.com
```

This page documents the conventions that apply across every endpoint: how to authenticate, how to pin an API version, how paginated responses are shaped, what error bodies look like, how rate limiting is signalled, and how idempotency, timestamps and agency scoping work. Use the navigation to browse endpoints by resource, or try requests directly from each endpoint page.

<Tip>Prefer the machine-readable spec? The full OpenAPI 3.1 document is served at [`/openapi.json`](/docs/openapi.json), ready to feed to a coding agent, client generator, or Postman.</Tip>

## Authentication

All endpoints require a Bearer access token obtained via the OAuth 2.0 flow. See the
[Authentication guide](/docs/authentication/overview) to set up an OAuth application and obtain
tokens.

```http theme={null}
Authorization: Bearer <access_token>
```

Missing, expired or insufficiently scoped credentials return `401` or `403`. See [Error responses](#error-responses) below.

## API versioning

Every request must send the `X-Fanvue-API-Version` header. The version is a date string, and the current version is `2025-06-26`.

```http theme={null}
X-Fanvue-API-Version: 2025-06-26
```

<Warning>
  This header is **required** on every endpoint. A request with no version, or a version the server does not recognise, returns `400` with an [`UnsupportedVersionError`](#error-responses). A version that has been retired returns `410` with a `SunsetVersionResponse` body that includes a `nextVersion` field telling you which version to move to.
</Warning>

## Pagination

List endpoints return results in pages. The API uses two pagination styles depending on the endpoint. Both wrap results in a top-level `data` array, so you always read items from `data`.

<Tabs>
  <Tab title="Cursor-based">
    Used by high-volume and append-only collections (chat media, insights earnings, spending and subscribers, tracking links). You pass an opaque `cursor` and a page-size parameter, and the response returns a `nextCursor` to fetch the following page.

    | Query parameter     | Type   | Notes                                                                                                                                                                                              |
    | ------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `cursor`            | string | Opaque cursor. Omit on the first request. Pass the `nextCursor` from the previous response to get the next page.                                                                                   |
    | `limit` *or* `size` | number | Items per page. Range `1-50`. Default varies by endpoint (for example `20`). The page-size parameter is named `limit` on chat-media and tracking-link endpoints, and `size` on insights endpoints. |

    The response envelope returns `data` plus a `nextCursor`. When `nextCursor` is `null`, you have reached the end of the collection.

    <CodeGroup>
      ```bash Request theme={null}
      curl https://api.fanvue.com/insights/earnings?size=2 \
        -H "Authorization: Bearer <access_token>" \
        -H "X-Fanvue-API-Version: 2025-06-26"
      ```

      ```json Response theme={null}
      {
        "data": [
          {
            "date": "2025-05-29T14:02:10Z",
            "gross": 1999,
            "net": 1599,
            "currency": "USD",
            "source": "subscription"
          },
          {
            "date": "2025-05-29T09:41:55Z",
            "gross": 500,
            "net": 400,
            "currency": "USD",
            "source": "tip"
          }
        ],
        "nextCursor": "eyJpZCI6IjEyMyJ9"
      }
      ```
    </CodeGroup>

    To page through the full set, repeat the request with `cursor` set to the previous `nextCursor` until `nextCursor` is `null`:

    ```bash theme={null}
    curl "https://api.fanvue.com/insights/earnings?size=2&cursor=eyJpZCI6IjEyMyJ9" \
      -H "Authorization: Bearer <access_token>" \
      -H "X-Fanvue-API-Version: 2025-06-26"
    ```
  </Tab>

  <Tab title="Page-based">
    Used by most list endpoints (chats, lists, mass messages, agency endpoints and others). You pass a 1-based `page` number and a `size`, and the response returns a `pagination` object describing the current page.

    | Query parameter | Type   | Notes                                       |
    | --------------- | ------ | ------------------------------------------- |
    | `page`          | number | Page number, starts at `1`. Default `1`.    |
    | `size`          | number | Items per page. Range `1-50`. Default `15`. |

    The response envelope returns `data` plus a `pagination` object with `page`, `size` and `hasMore`. Keep incrementing `page` while `hasMore` is `true`.

    <CodeGroup>
      ```bash Request theme={null}
      curl "https://api.fanvue.com/chats?page=1&size=2" \
        -H "Authorization: Bearer <access_token>" \
        -H "X-Fanvue-API-Version: 2025-06-26"
      ```

      ```json Response theme={null}
      {
        "data": [
          { "isRead": false, "unreadMessagesCount": 3 },
          { "isRead": true, "unreadMessagesCount": 0 }
        ],
        "pagination": {
          "page": 1,
          "size": 2,
          "hasMore": true
        }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Error responses

Errors use standard HTTP status codes. The response body is JSON, but its exact shape depends on the kind of error. There is no single global error envelope: validation errors return an `errors` array, while most other errors return a single `error` or `message` string.

| Status        | Meaning                                                                                                             | Body shape                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `400`         | Bad request. Either the API version is not supported, or request validation failed.                                 | `oneOf` an `UnsupportedVersionError` (`{ "error", "message" }`) or a `ValidationError` (`{ "errors": ["..."] }`). |
| `401`         | Unauthorized. Missing, invalid or expired access token.                                                             | `{ "error": "..." }`                                                                                              |
| `403`         | Forbidden. The token is valid but lacks the scope or permission for this resource.                                  | `{ "error": "..." }`                                                                                              |
| `404`         | Not found. The resource (or a referenced UUID) does not exist.                                                      | `{ "message": "..." }`                                                                                            |
| `409`         | Conflict. A uniquely named resource already exists (for example a list, collection or vault folder with that name). | `{ "message": "..." }`                                                                                            |
| `410`         | Gone. The requested API version has been sunset.                                                                    | `{ "error", "message", "nextVersion" }`                                                                           |
| `429`         | Too many requests. The rate limit was exceeded. See [Rate limit headers](#rate-limit-headers).                      | `{ "error": "..." }`                                                                                              |
| `502` / `503` | Upstream or service unavailable. Transient; retry with backoff.                                                     | No defined body; treat as transient and retry.                                                                    |

Some endpoints define additional, more specific `400` variants documented on the endpoint page itself:

<Accordion title="Endpoint-specific 400 variants">
  * **`ValidationError`** (`{ "errors": ["..."] }`): one or more request fields failed validation.
  * **`InvalidUuidError`** (`{ "message": "..." }`): a UUID path or body parameter is not a valid UUID.
  * **`ContactabilityError`** (`{ "message": "..." }`): the target user cannot be contacted (for example messaging restrictions).
  * **`MessageValidationError`** (`{ "message": "..." }`): message-specific validation failed, such as media ownership or content checks.
</Accordion>

<Note>
  Batch endpoints return `200` even when some items fail. Inside the `200` body, individual keys that could not be resolved carry a `PerKeyError` with `error` set to `forbidden`, `not_found` or `internal`, so a batch keeps its partial results instead of failing the whole request.
</Note>

## Rate limit headers

By default each user can make **100 requests per 60 seconds**. See [Rate Limits](/docs/authentication/rate-limits) for the full policy.

Rate-limited responses (`429`) include the following headers, defined in the spec's `RateLimitResponse`:

| Header                  | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| `X-RateLimit-Limit`     | The maximum number of requests allowed in the current window.      |
| `X-RateLimit-Remaining` | The number of requests remaining in the current window.            |
| `X-RateLimit-Reset`     | The Unix timestamp, in seconds, when the rate limit window resets. |
| `Retry-After`           | The number of seconds to wait before retrying the request.         |

When you receive a `429`, wait `Retry-After` seconds (or until `X-RateLimit-Reset`) before sending the next request.

<Note>
  The spec defines these four headers on the `429` response.
</Note>

## Idempotency

The grant endpoint, `POST /media/{uuid}/grant`, is idempotent by design. It grants a consumer access to a media item, and repeated calls with the same parameters return the existing entitlement rather than creating a duplicate.

Idempotency is keyed on the `source` and `sourceRef` fields you supply in the request body:

| Field        | Type          | Purpose                                                                                                                                                         |
| ------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consumerId` | string (uuid) | The consumer to grant access to.                                                                                                                                |
| `source`     | string        | Identifier for the granting application or reason. Lowercase, digits and underscores only (`^[a-z0-9_]+$`), max 100 chars. For example `spin_the_wheel_reward`. |
| `sourceRef`  | string        | A unique identifier within the `source`, used for the idempotency key. Max 255 chars. For example a spin-attempt UUID.                                          |

The same `source` + `sourceRef` pair always resolves to the same entitlement, so you can safely retry a grant after a network failure without double-granting.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://api.fanvue.com/media/3f1c.../grant \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Fanvue-API-Version: 2025-06-26" \
    -H "Content-Type: application/json" \
    -d '{
      "consumerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "source": "spin_the_wheel_reward",
      "sourceRef": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }'
  ```

  ```json Response theme={null}
  {
    "entitlementId": "9c8b7a65-4321-fedc-ba98-76543210abcd",
    "status": "granted"
  }
  ```
</CodeGroup>

The response returns the same `entitlementId` and `status: "granted"` whether the entitlement was just created or already existed, so a retry is indistinguishable from the first successful call. Granting media requires the `write:media` scope.

## Timestamps

All timestamps are UTC and formatted as ISO 8601 datetime strings. Date-range query parameters (such as `startDate` and `endDate` on insights endpoints) accept an ISO 8601 datetime, with or without a timezone offset, and stats are aggregated by UTC day.

```
2025-05-29T14:02:10Z
2024-10-20T00:00:00+01:00
```

<Note>
  Some response fields use a date-only format (`date`) and others a full datetime (`date-time`); each field documents its own format on the endpoint page. Regardless of format, the underlying instant is UTC.
</Note>

## Agency creator scoping

Agency-scoped list endpoints under `/agencies/*` cover every creator an agency manages in a single response. So that consumers can group rows by creator without a second lookup, every row is tagged with the creator it belongs to via a `creatorUuid` field.

This applies across the agency endpoints, for example:

* `GET /agencies/earnings`: each earnings row carries `creatorUuid` (the agency-managed creator the earnings row belongs to).
* `GET /agencies/subscribers`: each subscriber carries `creatorUuid` (the creator they are subscribed to).
* `GET /agencies/chats`: each chat carries `creatorUuid` (the creator that owns the chat).
* `GET /agencies/subscribers-history`: each history row carries `creatorUuid`.

To narrow results to a subset of managed creators, pass the `creatorUuids` query parameter, a comma-separated list of creator UUIDs (max 50):

```bash theme={null}
curl "https://api.fanvue.com/agencies/earnings?creatorUuids=<uuid1>,<uuid2>" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Fanvue-API-Version: 2025-06-26"
```

Because each row already includes `creatorUuid`, consumers can group or attribute results client-side without joining against a separate creators list.