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

# API reference overview

> Base URL, authentication, conventions and the shape of every response — read this before the endpoint pages.

- Source: https://www.dropfans.io/developers/reference/overview
- Section: API reference
- OpenAPI: https://www.dropfans.io/developers/openapi.json

```
https://www.dropfans.io
```

Every endpoint lives under `/api/external/` on that host. This page collects the conventions the endpoint pages assume.

> [!TIP]
> The whole contract is also published as [OpenAPI 3.1](https://www.dropfans.io/developers/openapi.json) — ready to feed to a client generator, Postman, or a coding agent. See [Build with AI](https://www.dropfans.io/developers/build-with-ai/overview.md).

## Authentication

Every request carries `Authorization: Bearer dpfn_…`. A key is bound to one creator and grants the full surface — details in [Authentication & API keys](https://www.dropfans.io/developers/concepts/authentication.md).

## Requests

JSON bodies with `Content-Type: application/json` everywhere except the two upload endpoints ([upload a vault item](https://www.dropfans.io/developers/reference/upload-vault-item.md), [attach previews](https://www.dropfans.io/developers/reference/attach-drop-previews.md)), which take `multipart/form-data`. Malformed JSON returns `400 { "error": "Invalid JSON body" }`.

## Ids and timestamps

Ids are opaque strings (cuid format, e.g. `cmawq81x40001lb04xyz12abc`) — treat them as text, never parse them. Timestamps are ISO-8601 in UTC, e.g. `2026-08-19T12:00:00.000Z`.

## Pagination

Two styles, both `page`/`limit` based: vault lists put `hasMore`/`total`/`page`/`limit` at the top level (limit defaults to the max, 50); post lists nest them under `pagination` (default 20). Iterate on `hasMore`, not on short pages. Two batch endpoints truncate oversized id arrays silently — details and caps in [Pagination & batch limits](https://www.dropfans.io/developers/concepts/pagination.md).

## Errors

Baseline `{ "error": "…" }` prose; gateway errors add a stable `code` (`unauthorized`, `app_suspended`, `rate_limited`); the word filter adds `matchedWord` (posts, 422) or `field` + `matchedWord` (drops, 400). The full catalogue — including the three success envelopes — is in [Errors](https://www.dropfans.io/developers/concepts/errors.md). Each endpoint page lists its exact error rows.

## Rate-limit headers

Every response reports the budget:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Tier` | `personal`, `app` or `first_party` |
| `X-RateLimit-Limit` / `-Remaining` / `-Reset` | the minute window |
| `X-RateLimit-Limit-Day` / `-Remaining-Day` / `-Reset-Day` | the UTC-day window |
| `Retry-After` | on `429`, seconds to wait |

Tiers and defaults: [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md).

## Units

Prices go **in** as USD dollars (drops: `0` or 5–750); earnings and sales come **out** as integer cents; balance is dollars. The per-endpoint table is in [Money & units](https://www.dropfans.io/developers/concepts/money-and-units.md).

## Versioning

Changes are additive — new fields and new endpoints, announced in the [changelog](https://www.dropfans.io/developers/changelog.md). There is no version header. Ignore fields you do not recognise, and never assume a response has exactly the fields listed today.

Next: [Get current creator](https://www.dropfans.io/developers/reference/get-me.md) or [Errors](https://www.dropfans.io/developers/concepts/errors.md).

---

Previous: [Agent prompt](https://www.dropfans.io/developers/build-with-ai/agent-prompt.md) · Next: [Which creator this API key belongs to](https://www.dropfans.io/developers/reference/get-me.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)