# API reference

> **Note:**
>
> **Machine-readable contract:** [`openapi.yaml`](https://docs.creator-guard.com/openapi.yaml) (OpenAPI 3.1) — import it into Postman, Insomnia or a code generator; the [SDKs](https://docs.creator-guard.com/sdks/) are generated from it. **For AI agents:** [`llms-full.txt`](https://docs.creator-guard.com/llms-full.txt) holds this reference and every guide page as one Markdown file — see [Build with AI agents](https://docs.creator-guard.com/ai-agents/).

## API reference (OpenAPI 3.1.0, API version 1.23.0)

Generated from https://docs.creator-guard.com/openapi.yaml — the machine-readable contract; import it into a code generator or HTTP client.

Base URL: `https://api.creator-guard.com` (paths below start with `/v1`). Production. `cg_live_` keys work on live data, `cg_test_` keys on the sandbox (test mode) — same host, same paths.

Authentication: HTTP bearer — cg_live_ (or cg_test_) followed by 43 letters and digits. `Authorization: Bearer cg_live_…`. Keys are issued by Creator Guard per account and handed over once; only a
hash is stored. A key carries scopes (each operation names the one it needs), an optional expiry and an
optional IP allowlist. `cg_test_` keys work in test mode (sandbox data, halved limits).

### Service

#### API status and versions

`GET /v1/` · operationId `getApi`

Auth: none (no API key needed).

No key needed. Use it as a liveness check and to read the contract version. Like every request without a valid key it uses the per-IP budget (30 per minute), so poll it at most every few seconds.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ApiInfo` | The API document. |

Error statuses: 429, 500 — body `ErrorResponse`; codes per status under "Error responses by status".

### Account

#### The account the key belongs to

`GET /v1/me` · operationId `getAccount`

Auth: API key with scope `account:read` · account types: any.

Type, status, terms state per agreement type and the limits in effect for this key.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Account` | The account. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Change your account profile

`PATCH /v1/me` · operationId `updateAccount`

Auth: API key with scope `account:write` · account types: any.

Display name, company name, Telegram username and website — the same fields and checks as the portal's
profile page. Send only what changes; `null` (or an empty string) clears the company name or the website.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `AccountPatch` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Account` | The account. |

Error statuses: 400, 401, 403, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Agreements and your acceptances

`GET /v1/agreements` · operationId `listAgreements`

Auth: API key with scope `account:read` · account types: any.

The current published version of every agreement type that applies to the account, with the account's acceptance.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `AgreementList` | Agreements that apply to the account. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Full text of one agreement version

`GET /v1/agreements/{type}/{version}` · operationId `getAgreementText`

Auth: API key with scope `account:read` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `type` | path | string | required | `referrer_terms`, `agency_terms`, `warranty_terms`, `api_terms` or `api_dpa`. |
| `version` | path | integer · ≥ 1 | required |  |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `AgreementDocument` | One agreement version with its text. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Accept the current version of an agreement

`POST /v1/agreements/{type}/accept` · operationId `acceptAgreement`

Auth: API key with scope `agreements:write` · account types: any.

Only the current published version can be accepted (an older one → `409 invalid_state` with
`error.current_version`). Records the key,
the caller's IP address and user agent. Works before the terms are accepted — it is how you accept them.
`api_terms` (the [API Terms](https://docs.creator-guard.com/authentication/#api-terms)) and `api_dpa` (the
[data protection addendum](https://docs.creator-guard.com/authentication/#data-protection-addendum)) belong to the account: accepted once,
with a live or a test key, they apply to both modes. Only keys of an owner or admin carry `agreements:write`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `type` | path | string | required | `referrer_terms`, `agency_terms`, `warranty_terms`, `api_terms` or `api_dpa`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `AgreementAccept` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Agreement` | The agreement with your acceptance. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state` (all codes: Error codes below).

#### The portal's pick lists

`GET /v1/option-lists` · operationId `getOptionLists`

Auth: API key with scope `account:read` · account types: any.

Values that match what agencies search for. Full lists: https://docs.creator-guard.com/reference/allowed-values/

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `OptionLists` | The pick lists. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Brokerage numbers

`GET /v1/settings` · operationId `getSettings`

Auth: API key with scope `account:read` · account types: any.

Offer deadline, undo window, payment due days, warranty days and the Creator Guard share of a fee.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Settings` | Brokerage numbers. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Upload your logo

`PUT /v1/me/logo` · operationId `setLogo`

Auth: API key with scope `account:write` · account types: any.

`multipart/form-data` with one part `file`: PNG, JPEG or WebP, at most 2 MB. We re-encode it (at most 512 px
on the long edge, every metadata block removed) and replace the old logo. Counts against the upload limit of
the account (60 per minute, 3,000 per day, halved in test mode).

Request body (`multipart/form-data`): `LogoUpload` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Account` | The account. |

Error statuses: 400, 401, 403, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Remove your logo

`DELETE /v1/me/logo` · operationId `deleteLogo`

Auth: API key with scope `account:write` · account types: any.

Removes the file, then the logo. If the file cannot be removed, nothing changes and the answer is
`502 upstream_failed` — retry.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Account` | The account. |

Error statuses: 401, 403, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `upstream_failed` (all codes: Error codes below).

### Leads

#### List your leads

`GET /v1/leads` · operationId `listLeads`

Auth: API key with scope `leads:read` · account types: any.

Newest first (`created_at`, then `id`). Filters combine with AND. Unknown parameters → `400 unknown_parameter`; an invalid filter value → `400 invalid_field`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `ending_before` | query | string | optional | Id of the first item of the current page: the page before. |
| `stage` | query | string · one of `draft`, `in_review`, `ready`, `offered`, `accepted`, `in_placement`, `placed`, `rejected`, `lost`, `withdrawn` | optional | One stage (see the Lead schema). |
| `external_id` | query | string · 1–200 chars | optional | Your own reference, exact match. |
| `creator_ref` | query | string · pattern `^(?:[Cc][Rr][ -]?)?[0-9]{1,9}$` | optional | Creator number, `CR-1047` or `1047`. |
| `instagram_handle` | query | string · 1–200 chars | optional | Handle or profile link; compared after normalising. |
| `q` | query | string · 1–200 chars | optional | Part of the creator name, case-insensitive. |
| `created_since` | query | string (date-time) | optional | Leads created at or after this instant (RFC 3339, e.g. `2026-10-09T12:00:00Z`). |
| `updated_since` | query | string (date-time) | optional | Leads changed at or after this instant — for incremental sync. |
| `has_blockers` | query | boolean | optional | `true`: only leads with `next_actions.blockers`; `false`: only without. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `LeadList` | A page of leads. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `unknown_parameter`, `invalid_field` (all codes: Error codes below).

#### Create a lead

`POST /v1/leads` · operationId `createLead`

Auth: API key with scope `leads:write` · account types: any.

Creates a lead for one creator under your account, optionally with her listing. Only `creator_name` and
`consent_confirmed` are required (the portal's rule); send every other field you have. Without an
`instagram_handle` there is no duplicate check by handle: use `external_id` so a retry finds her again.

- **201** — a new lead was created.
- **200** — nothing new was created: you already used this `external_id` (that lead is returned
  unchanged), or you already submitted this Instagram handle and that lead is still a `draft` (it is
  updated with the lead fields you sent; a `listing` in the body is applied like `PATCH …/listing`).
- **409 `duplicate_own_lead`** — your lead with this handle is past `draft`. Nothing changes; `error.lead`.
- **409 `duplicate_other_referrer`** — another account submitted this handle. Budgeted: 20 such answers
  per rolling 24 h, then `429 duplicate_limit_reached` for every request with an `instagram_handle`.

Both answers carry `consent`. The `201` carries her personal consent link in `consent.url` (valid at least
30 days) — send it to her. Links are stored only as hashes, so the `url` is shown only there: a `200`, a
`GET` and an `Idempotency-Key` replay answer `url: null`; `POST /v1/leads/{id}/consent-link` makes a new one.

Send an `Idempotency-Key` so a retry after a timeout returns the first answer.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `LeadCreate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Lead` | Already known: your `external_id`, or your handle while that lead is still a draft. `consent` carries her consent link. |
| 201 | `Lead` | A new lead was created; `consent` carries her consent link. |

Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `duplicate_own_lead`, `duplicate_other_referrer`, `duplicate_limit_reached` (all codes: Error codes below).

#### Get a lead

`GET /v1/leads/{id}` · operationId `getLead`

Auth: API key with scope `leads:read` · account types: any.

With `?expand=listing,photos,confirmations` (any combination) the lead carries those objects too. Any other query parameter → `400 unknown_parameter`, another `expand` value → `400 invalid_field`. `consent` shows her consent link as it is; reading never extends it.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `expand` | query | string | optional | Comma-separated: `listing`, `photos`, `confirmations`. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Lead` | The lead, with her consent link (`consent`). |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `unknown_parameter`, `invalid_field` (all codes: Error codes below).

#### Change lead fields

`PATCH /v1/leads/{id}` · operationId `updateLead`

Auth: API key with scope `leads:write` · account types: any.

Lead fields only while the lead is a `draft` (`next_actions.can_edit_lead`), else `409 lead_locked`.
`external_id` can be changed at any stage (unique within your account, else `409 external_id_taken`).
Both `instagram_handle` and `other_contact` may be cleared (`null`), as in the portal. A new `instagram_handle`
that another account already submitted → `409 duplicate_other_referrer` (counts against the same daily
budget as on create, then `429 duplicate_limit_reached`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `LeadUpdate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Lead` | The lead. |

Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `duplicate_other_referrer`, `lead_locked`, `external_id_taken`, `duplicate_limit_reached` (all codes: Error codes below).

#### Withdraw a lead

`POST /v1/leads/{id}/withdraw` · operationId `withdrawLead`

Auth: API key with scope `leads:write` · account types: any.

Allowed while `next_actions.can_withdraw` (`draft` or `in_review`, no live offer); else `409 invalid_state`. No body.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Lead` | The lead. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state` (all codes: Error codes below).

#### Suggest lead fields from text

`POST /v1/extract` · operationId `extractFields`

Auth: API key with scope `extract` · account types: any.

Paste a profile text, a chat or notes (20–20,000 characters); the answer suggests lead and listing fields for
you to review. Nothing is stored — not the text, not the suggestions — so an `Idempotency-Key` is ignored and
a retry simply runs again. Limits: 20 per minute and 200 per day per account (halved in test mode). With a
`cg_test_` key the answer is a fixed fictitious example and no AI runs. Works before the terms are accepted.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | optional | Ignored on this endpoint: nothing is stored, a retry runs again. |

Request body (`application/json`): `ExtractRequest` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ExtractResult` | Suggested fields; nothing was stored. |

Error statuses: 400, 401, 403, 413, 415, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

### Listing

#### Get the listing of a lead

`GET /v1/leads/{id}/listing` · operationId `getListing`

Auth: API key with scope `leads:read` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Listing` | The listing. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Change listing fields

`PATCH /v1/leads/{id}/listing` · operationId `updateListing`

Auth: API key with scope `leads:write` · account types: any.

While the listing is not live (`next_actions.can_edit_listing`), else `409 listing_locked`.
`placement_fee` only while `next_actions.can_edit_fee`. Send `null` to clear a value, `[]` to empty a list.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `ListingPatch` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Listing` | The listing. |

Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `listing_locked` (all codes: Error codes below).

#### Submit a draft for review

`POST /v1/leads/{id}/submit-for-review` · operationId `submitForReview`

Auth: API key with scope `leads:write` · account types: any.

Draft → in review (`next_actions.can_submit_for_review`). Remaining blockers → `422 not_ready_for_review`
with `error.blockers`, `fee_missing` included: set `placement_fee` before you submit her.
Not a draft → `409 invalid_state`. No body.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Lead` | The lead. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state`, `not_ready_for_review` (all codes: Error codes below).

#### Her consent, 18+ confirmation and login state

`GET /v1/leads/{id}/confirmations` · operationId `getConfirmations`

Auth: API key with scope `leads:read` · account types: any.

Status and dates only — never her IP address or browser.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Confirmations` | Her confirmations. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Her personal consent link

`POST /v1/leads/{id}/consent-link` · operationId `createConsentLink`

Auth: API key with scope `leads:write` · account types: any.

Returns the hosted page where she confirms consent and 18+ herself: a NEW link, valid at least 30 days from
now. Links are stored only as hashes, so each call makes a new one; the previous link of the lead can then only
be used to withdraw consent (never to give it). An `Idempotency-Key` replay answers `url: null`. Send the link to her; never confirm for her.
After her data was erased on her request → `409 invalid_state` with `error.current_state` `anonymized`. No body.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ConsentLink` | Her consent link. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state` (all codes: Error codes below).

#### Her claim link (her own login)

`POST /v1/leads/{id}/claim-link` · operationId `createClaimLink`

Auth: API key with scope `leads:write` · account types: any.

A single-use link to the hosted page where she chooses her own email and password for the creator portal.
It works once and for 7 days; a new link makes every earlier unused link of the lead invalid. The URL is
shown only in this answer: an `Idempotency-Key` replay returns the same object with `url: null` (call again
without the key for a new link). A `cg_test_` key gets a `…/claim/test_…` URL that opens a notice only.
`409 invalid_state` with `error.current_state` `claimed` (she already has a login), `withdrawn` or
`rejected`. No body.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `ClaimLink` | Her claim link (shown once). |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state` (all codes: Error codes below).

#### Milestones of a lead

`GET /v1/leads/{id}/timeline` · operationId `getTimeline`

Auth: API key with scope `leads:read` · account types: any.

Submitted, review requested, approved, offers, acceptance, payment, warranty, completion, commission. No agency names.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Timeline` | The milestones. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Your earnings from a lead

`GET /v1/leads/{id}/earnings` · operationId `getEarnings`

Auth: API key with scope `earnings:read` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Earnings` | Your earnings. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

### Photos

#### List her photos

`GET /v1/leads/{id}/photos` · operationId `listPhotos`

Auth: API key with scope `leads:read` · account types: any.

Primary photo first, then oldest first; every photo on one page. Each `url` is signed and works for one hour.
No query parameters besides `fields`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `PhotoList` | Her photos, primary first. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Upload a photo

`POST /v1/leads/{id}/photos` · operationId `uploadPhoto`

Auth: API key with scope `photos:write` · account types: any.

`multipart/form-data`: `file` (JPEG, PNG or WebP, at most 40 MB and 50 megapixels), optionally `kind` (default
`portrait`) and `is_primary`. We read the format from the bytes, bake in the orientation, scale to at most
3000 px on the long edge and remove **every** metadata block (EXIF, GPS, XMP, IPTC) before anything is
stored; your original bytes are never kept, nor the file name. At most 20 photos per lead (`409
limit_reached`); only while the listing is not live (`409 photos_locked`). Counts against the upload limit
(60 per minute, 3,000 per day, halved in test mode). A replay of the same `Idempotency-Key` answers `url: null`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`multipart/form-data`): `PhotoUpload` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `Photo` | The photo was stored (re-encoded, metadata removed). A replay of the same `Idempotency-Key` answers `url` and `url_expires_at` as `null`; list the photos for a fresh URL. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `photos_locked`, `limit_reached` (all codes: Error codes below).

#### Change kind or make primary

`PATCH /v1/leads/{id}/photos/{photo}` · operationId `updatePhoto`

Auth: API key with scope `photos:write` · account types: any.

`kind`, or `is_primary: true` (the previous primary photo stops being primary). Only while the listing is not
live (`409 photos_locked`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `photo` | path | string | required | Photo id (`photo_…`). |
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `PhotoPatch` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Photo` | The photo. |

Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `photos_locked` (all codes: Error codes below).

#### Delete a photo

`DELETE /v1/leads/{id}/photos/{photo}` · operationId `deletePhoto`

Auth: API key with scope `photos:write` · account types: any.

Removes the file, then the photo. If it was her primary photo, the oldest remaining one becomes primary. Only
while the listing is not live (`409 photos_locked`). If the file cannot be removed, nothing changes and the
answer is `502 upstream_failed` — retry.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `photo` | path | string | required | Photo id (`photo_…`). |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 204 | — | Deleted. The answer has no body. |

Error statuses: 401, 403, 404, 409, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `photos_locked`, `upstream_failed` (all codes: Error codes below).

### Earnings

#### List your commissions

`GET /v1/commissions` · operationId `listCommissions`

Auth: API key with scope `earnings:read` · account types: any.

Newest first. A commission is booked for your lead when her placement completes.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `ending_before` | query | string | optional | Id of the first item of the current page: the page before. |
| `status` | query | string · one of `due`, `paid`, `void` | optional | Only this status. |
| `created_since` | query | string (date-time) | optional | Booked at or after this instant (RFC 3339). |
| `lead` | query | string | optional | Only the commissions of this lead (`lead_…`). |
| `expand` | query | string | optional | `lead`: `lead` is a short lead object (`id`, `creator_name`, `creator_ref`, `stage`) instead of its id. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CommissionList` | A page of commissions. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Get a commission

`GET /v1/commissions/{id}` · operationId `getCommission`

Auth: API key with scope `earnings:read` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Commission id (`com_…`). |
| `expand` | query | string | optional | `lead`: `lead` is a short lead object (`id`, `creator_name`, `creator_ref`, `stage`) instead of its id. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Commission` | The commission. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Your payout details (masked)

`GET /v1/payout-details` · operationId `getPayoutDetails`

Auth: API key with scope `earnings:read` · account types: any.

Method and a masked destination, never the full account data. Change them in the portal (Settings → Payout,
needs your second factor); the API cannot.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `PayoutDetails` | Your payout details, masked. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

### Keys

#### List the keys of this mode

`GET /v1/api-keys` · operationId `listApiKeys`

Auth: API key with scope `keys:manage` · account types: any.

Active keys of the calling key's mode (`live` or `test`), then the ones revoked in the last 90 days, on one
page. Never a secret. No query parameters besides `fields`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ApiKeyList` | The keys of this mode. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Create a key

`POST /v1/api-keys` · operationId `createApiKey`

Auth: API key with scope `keys:manage` · account types: any.

The new key has the calling key's mode and at most its scopes (more → `403 insufficient_scope`). So
`keys:manage` and `webhooks:manage` reach a key made here only through a key that already has them, and
those come from the portal with a second factor. The secret is in this answer only — store it now; a replay
of the same `Idempotency-Key` answers `secret: null`. At most 10 active keys per mode (`409 limit_reached`);
your key policy may cap `expires_at`. The new key inherits the calling key's restrictions: without
`ip_allowlist` it gets the caller's; an `ip_allowlist` outside the caller's is `400 invalid_field`; it expires
no later than the caller. A rolled key in its grace period cannot call this (`403 insufficient_scope`).
A new live key needs the [API Terms](https://docs.creator-guard.com/authentication/#api-terms) and the data protection addendum
(`403 terms_not_accepted` with `agreement_type: "api_terms"` or `"api_dpa"`); a test key does not.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `ApiKeyCreate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `ApiKey` | The key with its new secret — shown this once. A replay of the same `Idempotency-Key` answers `secret: null`. |

Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_field`, `terms_not_accepted`, `insufficient_scope`, `limit_reached` (all codes: Error codes below).

#### Revoke a key

`DELETE /v1/api-keys/{id}` · operationId `revokeApiKey`

Auth: API key with scope `keys:manage` · account types: any.

Effective on the next request; repeating it is harmless. Only for keys whose scopes the calling key holds
(else `403 insufficient_scope` naming the first missing one). The calling key itself only with `?force=true`
(else `409 invalid_state` with `current_state: in_use`). Answers the revoked key.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Key id (`key_…`). |
| `force` | query | boolean | optional | `true` to revoke the key that makes this request. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ApiKey` | The key (no secret). |

Error statuses: 400, 401, 403, 404, 409, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `insufficient_scope`, `invalid_state` (all codes: Error codes below).

#### Roll a key

`POST /v1/api-keys/{id}/roll` · operationId `rollApiKey`

Auth: API key with scope `keys:manage` · account types: any.

A new key with the same label, scopes, IP allowlist and expiry; the old one keeps working for `grace_hours`
(0–72, default 24; `0` revokes it now). Only for keys whose scopes the calling key holds. The new key also
takes on the calling key's restrictions: IP allowlist = the overlap of the old key's and the caller's (none at
all → `409 invalid_state` with `current_state: ip_allowlist_outside_caller`), expiry no later than the
caller's. The new secret is in this answer only; a replay of the same `Idempotency-Key` answers
`secret: null`. Rolling a live key needs the [API Terms](https://docs.creator-guard.com/authentication/#api-terms) and the data protection
addendum (`403 terms_not_accepted` with `agreement_type: "api_terms"` or `"api_dpa"`); revoking never does.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Key id (`key_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `ApiKeyRoll` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ApiKey` | The key with its new secret — shown this once. A replay of the same `Idempotency-Key` answers `secret: null`. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `invalid_state` (all codes: Error codes below).

### Events

#### List events

`GET /v1/events` · operationId `listEvents`

Auth: API key (any scopes) · account types: any.

The last 30 days of this mode, newest first. Any key works; you only see events whose object the key may read
(`leads:read` for lead, photo and confirmation events, `earnings:read` for commissions, … — see
[Events](https://docs.creator-guard.com/events/)).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `ending_before` | query | string | optional | Id of the first item of the current page: the page before. |
| `type` | query | string | optional | Exact type (`lead.updated`) or a group (`lead.*`). |
| `created_after` | query | string (date-time) | optional | RFC 3339 timestamp; only events after it. |
| `object` | query | string | optional | Events about one object: the id of a lead, photo, commission, API key or webhook endpoint (confirmation events carry the lead id). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `EventList` | A page of events. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Get an event

`GET /v1/events/{id}` · operationId `getEvent`

Auth: API key (any scopes) · account types: any.

`404 not_found` for an unknown id, another account's event or one older than 30 days; `403 insufficient_scope`
(with `error.scope`) when the key lacks the scope that reads the event's object.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Event id (`evt_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Event` | The event. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `insufficient_scope`, `not_found` (all codes: Error codes below).

### Webhooks

#### List webhook endpoints

`GET /v1/webhook-endpoints` · operationId `listWebhookEndpoints`

Auth: API key with scope `webhooks:manage` · account types: any.

The endpoints of this mode (at most 10, one page). Secrets are never listed.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `WebhookEndpointList` | The endpoints of this mode. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Create a webhook endpoint

`POST /v1/webhook-endpoints` · operationId `createWebhookEndpoint`

Auth: API key with scope `webhooks:manage` · account types: any.

`https` only, port 443, a host that resolves to public addresses only; checked now and again before every
delivery (a failed DNS lookup now → `502 upstream_failed`). At most 10 endpoints per mode
(`409 limit_reached`). Every event type must be readable with this key's scopes (else
`403 insufficient_scope` naming the scope); `["*"]` means every type this key can read, and the endpoint
never carries more. The signing secret is in this answer only; a replay of the same `Idempotency-Key`
answers `secret: null`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `WebhookEndpointCreate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `WebhookEndpoint` | The endpoint with its new signing secret — shown this once. A replay of the same `Idempotency-Key` answers `secret: null`. |

Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `insufficient_scope`, `limit_reached`, `upstream_failed` (all codes: Error codes below).

#### Get a webhook endpoint

`GET /v1/webhook-endpoints/{id}` · operationId `getWebhookEndpoint`

Auth: API key with scope `webhooks:manage` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Webhook endpoint id (`we_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `WebhookEndpoint` | The endpoint (no secret). |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Change a webhook endpoint

`PATCH /v1/webhook-endpoints/{id}` · operationId `updateWebhookEndpoint`

Auth: API key with scope `webhooks:manage` · account types: any.

URL, event types, description, or `enabled` (re-enabling an endpoint disabled for failing starts its failure
clock afresh). A new URL is checked like on create. New event types must be readable with this key's scopes
(`403 insufficient_scope`); after a new URL or new event types the endpoint carries only what this key can
read, and waiting deliveries it may no longer carry end `failed` (`scope_removed`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Webhook endpoint id (`we_…`). |
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `WebhookEndpointUpdate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `WebhookEndpoint` | The endpoint (no secret). |

Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `insufficient_scope` (all codes: Error codes below).

#### Delete a webhook endpoint

`DELETE /v1/webhook-endpoints/{id}` · operationId `deleteWebhookEndpoint`

Auth: API key with scope `webhooks:manage` · account types: any.

The endpoint and its deliveries are removed; pending deliveries to it are dropped.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Webhook endpoint id (`we_…`). |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 204 | — | Deleted. The answer has no body. |

Error statuses: 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Roll the signing secret

`POST /v1/webhook-endpoints/{id}/roll` · operationId `rotateWebhookSecret`

Auth: API key with scope `webhooks:manage` · account types: any.

A new signing secret, in this answer only (a replay of the same `Idempotency-Key` answers `secret: null`).
For 24 hours every delivery is signed with both (two `v1=` values in `CG-Signature`). Only the newest two
secrets sign: a second roll within the 24 hours retires the oldest at once.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Webhook endpoint id (`we_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `WebhookEndpoint` | The endpoint with its new signing secret — shown this once. A replay of the same `Idempotency-Key` answers `secret: null`. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Send a test event

`POST /v1/webhook-endpoints/{id}/test` · operationId `testWebhookEndpoint`

Auth: API key with scope `webhooks:manage` · account types: any.

Queues a `ping` event for this endpoint only and answers its delivery (`202`); it is delivered and retried
like every other event. Follow it in the deliveries list.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Webhook endpoint id (`we_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 202 | `WebhookDelivery` | The delivery, queued. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Re-send events of a time range

`POST /v1/webhook-endpoints/{id}/replay` · operationId `replayWebhookEvents`

Auth: API key with scope `webhooks:manage` · account types: any.

Queues every event of the range that the endpoint subscribes to and may carry again (at most 30 days back).
The endpoint holds at most 1,000 open deliveries afterwards; a range that does not fit is refused whole with
`409 limit_reached` (`limit: 1000`), nothing queued. Deliveries are spread 250 ms apart and carry
`replay: true`; receivers drop what they already have by `sequence`. At most 10 replays per account and day
(test mode: 5) → `429 rate_limited`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Webhook endpoint id (`we_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `WebhookReplay` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 202 | `ReplayResult` | How many deliveries were queued. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `rate_limited`, `limit_reached` (all codes: Error codes below).

#### Deliveries to an endpoint

`GET /v1/webhook-endpoints/{id}/deliveries` · operationId `listWebhookDeliveries`

Auth: API key with scope `webhooks:manage` · account types: any.

Newest first, 30 days, each with every attempt (status code, duration, error). Pages forward only:
`starting_after`, no `ending_before`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Webhook endpoint id (`we_…`). |
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `WebhookDeliveryList` | A page of deliveries. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Retry a delivery now

`POST /v1/webhook-endpoints/{id}/deliveries/{d}/retry` · operationId `retryWebhookDelivery`

Auth: API key with scope `webhooks:manage` · account types: any.

Also for a delivery that has already `failed`: it is due again now (`202`), its attempt count is kept.
A delivery of an event the endpoint may no longer carry (its object type left the endpoint's scope) is
refused with `409 invalid_state` (`current_state: scope_removed`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Webhook endpoint id (`we_…`). |
| `d` | path | string | required | Delivery id (`whd_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 202 | `WebhookDelivery` | The delivery, queued. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state` (all codes: Error codes below).

### OAuth apps

#### List OAuth apps

`GET /v1/oauth-apps` · operationId `listOAuthApps`

Auth: API key with scope `oauth_apps:manage` · account types: any.

The OAuth apps of this mode (at most 10, one page). Client secrets are never listed. No query parameters
besides `fields`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `OAuthAppList` | The OAuth apps of this mode. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Register an OAuth app

`POST /v1/oauth-apps` · operationId `createOAuthApp`

Auth: API key with scope `oauth_apps:manage` · account types: any.

An app that creators sign in to with Creator Guard (OAuth 2.1, authorization code with PKCE). Redirect URIs
are matched exactly; `https` only, no private or loopback hosts (`http://localhost` and `127.0.0.1` with a
port only for apps of test keys). A confidential app gets a `client_secret`, in this answer only — a replay
of the same `Idempotency-Key` answers `client_secret: null`. At most 10 apps per mode
(`409 invalid_state` with `current_state: app_limit_reached`). Registering a live app needs the
[API Terms](https://docs.creator-guard.com/authentication/#api-terms) and the data protection addendum (`403 terms_not_accepted` with
`agreement_type: "api_terms"` or `"api_dpa"`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `OAuthAppCreate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `OAuthApp` | The OAuth app with its new client secret (confidential apps) — shown this once. A replay of the same `Idempotency-Key` answers `client_secret: null`. |

Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `invalid_state` (all codes: Error codes below).

#### Get an OAuth app

`GET /v1/oauth-apps/{id}` · operationId `getOAuthApp`

Auth: API key with scope `oauth_apps:manage` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | OAuth app id (`app_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `OAuthApp` | The OAuth app (no client secret). |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Change an OAuth app

`PATCH /v1/oauth-apps/{id}` · operationId `updateOAuthApp`

Auth: API key with scope `oauth_apps:manage` · account types: any.

Name, logo, privacy URL, redirect URIs or scopes. Narrowing the scopes narrows the creators' existing
grants too. `confidential` cannot change (`400 invalid_field`; register a new app instead).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | OAuth app id (`app_…`). |
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `OAuthAppUpdate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `OAuthApp` | The OAuth app (no client secret). |

Error statuses: 400, 401, 403, 404, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_field` (all codes: Error codes below).

#### Delete an OAuth app

`DELETE /v1/oauth-apps/{id}` · operationId `deleteOAuthApp`

Auth: API key with scope `oauth_apps:manage` · account types: any.

Every creator's grant to the app is revoked first: its access and refresh tokens stop working at once.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | OAuth app id (`app_…`). |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 204 | — | Deleted. The answer has no body. |

Error statuses: 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Roll the client secret

`POST /v1/oauth-apps/{id}/roll` · operationId `rollOAuthAppSecret`

Auth: API key with scope `oauth_apps:manage` · account types: any.

A new client secret for a confidential app, in this answer only (a replay of the same `Idempotency-Key`
answers `client_secret: null`). The previous secret keeps working for 24 hours; a second roll within them
ends it at once. A public app has no secret (`409 invalid_state` with `current_state: public_client`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | OAuth app id (`app_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `OAuthApp` | The OAuth app with its new client secret (confidential apps) — shown this once. A replay of the same `Idempotency-Key` answers `client_secret: null`. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state` (all codes: Error codes below).

### Members

#### People and open invitations

`GET /v1/members` · operationId `listMembers`

Auth: API key with scope `members:manage` · account types: any.

Everyone who can sign in to the account (`status: active`, id `mem_…`, the owner first) and every open,
unexpired invitation (`status: invited`, id `inv_…`). Not paginated. Live keys only: a `cg_test_` key gets
`404 not_found`, because test mode has no logins.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `MemberList` | People (owner first) and open invitations. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found` (all codes: Error codes below).

#### Invite a person by email

`POST /v1/members` · operationId `inviteMember`

Auth: API key with scope `members:manage` · account types: any.

Creates an invitation for `developer` or `viewer` (admins are invited in the portal by an owner or admin with
two-factor authentication) and returns it once with `join_url` (valid 48 hours). Send the link yourself,
only through a channel the person controls — Creator Guard sends no email, and whoever opens the link first
sets the password for this address. On the join page the person sets a password for exactly this email
address (or signs in, if a login with it exists) and accepts. A replay of the same `Idempotency-Key` answers
`join_url: null` — the link is never stored. Inviting an address again replaces its open invitation (the old
link stops working). A person who already is a member → `409 invalid_state` with `current_state: active`. An
address whose login cannot join any account (it belongs to another account, a creator or Creator Guard
staff) gets the same `201` invitation as any address, with the same join page; it can never be accepted. At
most 20 invitations per account in 24 hours, those included → `409 limit_reached` with `limit: 20`.
Works before the terms are accepted. Live keys only.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `MemberInvite` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `Member` | The invitation with `join_url` — shown this once. A replay of the same `Idempotency-Key` answers `join_url: null`. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state`, `limit_reached` (all codes: Error codes below).

#### Remove a person or revoke an invitation

`DELETE /v1/members/{id}` · operationId `deleteMember`

Auth: API key with scope `members:manage` · account types: any.

`mem_…` removes the person from the account in one step: their login acts for no account from its next
request on, their open invitations are revoked, every API key whose secret they had is revoked (keys they
created in the portal and keys those keys created), and webhook endpoints whose signing secret they know get
a new secret nobody has seen and are disabled until an owner or admin rolls the secret and enables them
again. A login that was created through a join link is deleted with its last membership. `inv_…` revokes an
open invitation; its link stops working. The owner cannot be removed: `409 invalid_state` with
`current_state: owner`. Works before the terms are accepted. Live keys only.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Member id (`mem_…`) or invitation id (`inv_…`). |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `MemberDeleted` | The person was removed or the invitation revoked. |

Error statuses: 400, 401, 403, 404, 409, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state` (all codes: Error codes below).

### Creator

#### Get the creator

`GET /v1/creator/me` · operationId `getCreatorMe`

Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any.

Her name, stage and next steps and, once an agency paid for her, that agency. All `/v1/creator/…` endpoints take
a creator's OAuth access token (`cgo_live_…`) and act for her alone; an account API key is `403
wrong_account_type`. A grant whose app owner no longer submitted her, or whose reservation ended, stops working
(`401 invalid_token`); an app owner that is not approved gets `403 account_not_active`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Creator` | Her creator object. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_token`, `account_not_active`, `wrong_account_type` (all codes: Error codes below).

#### Get her profile

`GET /v1/creator/profile` · operationId `getCreatorProfile`

Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorProfile` | Her profile. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Change her profile

`PATCH /v1/creator/profile` · operationId `updateCreatorProfile`

Auth: creator access token (OAuth) with scope `creator.profile:write` · account types: any.

`lead` (contact fields) while her lead is `submitted`, else `409 lead_locked`; `listing` until the listing is
live, else `409 listing_locked`. Every problem of the body comes back at once (`400`, `error.details`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `CreatorProfilePatch` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorProfile` | Her profile. |

Error statuses: 400, 401, 403, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `lead_locked`, `listing_locked` (all codes: Error codes below).

#### Submit her listing for review

`POST /v1/creator/submit-for-review` · operationId `submitCreatorForReview`

Auth: creator access token (OAuth) with scope `creator.profile:write` · account types: any.

Same rules as for the partner: `422 not_ready_for_review` with `blockers` while something is missing.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Creator` | Her creator object. |

Error statuses: 400, 401, 403, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_ready_for_review` (all codes: Error codes below).

#### List her photos

`GET /v1/creator/photos` · operationId `listCreatorPhotos`

Auth: creator access token (OAuth) with scope `creator.photos:write` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorPhotoList` | Her photos, primary first, each with a URL signed for 1 hour. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Upload a photo

`POST /v1/creator/photos` · operationId `uploadCreatorPhoto`

Auth: creator access token (OAuth) with scope `creator.photos:write` · account types: any.

Multipart, like a partner upload: the image is re-encoded on our side and every metadata (EXIF, GPS) removed
before it is stored; the file name is never used. `409 photos_locked` once her listing is live; at most 20
photos. A repeated `Idempotency-Key` replays the first answer (with `url: null`) even with another file.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`multipart/form-data`): `PhotoUpload` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `CreatorPhoto` | The photo was stored (re-encoded, metadata removed). A replay of the same `Idempotency-Key` answers `url` and `url_expires_at` as `null`; list her photos for a fresh URL. |

Error statuses: 400, 401, 403, 409, 413, 415, 422, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `photos_locked` (all codes: Error codes below).

#### Delete a photo

`DELETE /v1/creator/photos/{photo}` · operationId `deleteCreatorPhoto`

Auth: creator access token (OAuth) with scope `creator.photos:write` · account types: any.

The photo is removed, then its file (`502 upstream_failed`: the photo is put back, nothing changed). `409 photos_locked` once live.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `photo` | path | string | required | Photo id (`photo_…`). |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 204 | — | Deleted. The answer has no body. |

Error statuses: 401, 403, 404, 409, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `photos_locked`, `upstream_failed` (all codes: Error codes below).

#### Get a consent text

`GET /v1/creator/consent-text` · operationId `getConsentText`

Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any.

The current text of `kind` that your app must show her in full before it sends her decision, and the
`version` to send with it.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | query | string · one of `consent`, `age_confirmation`, `creator_terms` | required | `consent`, `age_confirmation` or `creator_terms`. |
| `locale` | query | string · pattern `^[a-z]{2}$` | optional | Two lowercase letters, default `en`; a language without its own text falls back to English. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ConsentText` | The current published text of that kind and language. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Get her consent state

`GET /v1/creator/consent` · operationId `getCreatorConsent`

Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any.

Consent and 18+ state with every entry of her consent ledger (never her IP address or browser).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorConsentState` | Her consent and 18+ state with her ledger entries. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Record her consent

`POST /v1/creator/consent/grant` · operationId `grantCreatorConsent`

Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any.

A ledger entry with channel `oauth_app:app_…`, the text version she saw and the IP and user agent of your
request (your server). Only the current version (`409 consent_text_outdated` with `current_version`).
The consent text includes her 18+ confirmation: unless 18+ is already confirmed, the grant also records
`age_confirmed` on the same text, like the hosted consent page. While her 18+ check is declined or under
document review the grant is `409 invalid_state` (`current_state` `age_declined` or `age_pending`) and
records nothing. An app owned by the account that referred her → `403 referrer_app_not_allowed` (she
consents on Creator Guard: consent link or creator portal).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `ConsentDecision` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorConsentState` | Her consent and 18+ state with her ledger entries. |

Error statuses: 400, 401, 403, 409, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `referrer_app_not_allowed`, `invalid_state`, `consent_text_outdated` (all codes: Error codes below).

#### Record her withdrawal

`POST /v1/creator/consent/revoke` · operationId `revokeCreatorConsent`

Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any.

Her photos stop being released. Never refused because of the text version; send the one she saw if you have it.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `ConsentDecision` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorConsentState` | Her consent and 18+ state with her ledger entries. |

Error statuses: 400, 401, 403, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Record her 18+ confirmation

`POST /v1/creator/age-confirmation` · operationId `confirmCreatorAge`

Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any.

Only the current text version. Declined or under document review → `409 invalid_state`; already confirmed → unchanged. An app owned by the account that referred her → `403 referrer_app_not_allowed`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `ConsentDecision` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorConsentState` | Her consent and 18+ state with her ledger entries. |

Error statuses: 400, 401, 403, 409, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `referrer_app_not_allowed`, `invalid_state` (all codes: Error codes below).

#### List her agreements

`GET /v1/creator/agreements` · operationId `listCreatorAgreements`

Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorAgreementList` | Her agreements (the creator terms). |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Record her acceptance of the creator terms

`POST /v1/creator/agreements/{type}/accept` · operationId `acceptCreatorTerms`

Auth: creator access token (OAuth) with scope `creator.consent:write` · account types: any.

Only `creator_terms`, only the current version (`409 consent_text_outdated`). An app owned by the account that referred her → `403 referrer_app_not_allowed`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `type` | path | string | required | Always `creator_terms`; any other value is `404`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `CreatorTermsAccept` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `CreatorAgreement` | The agreement with her acceptance. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `referrer_app_not_allowed`, `consent_text_outdated` (all codes: Error codes below).

#### List her support tickets

`GET /v1/creator/support-tickets` · operationId `listCreatorTickets`

Auth: creator access token (OAuth) with scope `creator.support` · account types: any.

Newest first; pages forward only (`starting_after`; `ending_before` is `400 invalid_field`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `SupportTicketList` | Her support tickets, newest first. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_field` (all codes: Error codes below).

#### Open a support ticket

`POST /v1/creator/support-tickets` · operationId `createCreatorTicket`

Auth: creator access token (OAuth) with scope `creator.support` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `SupportTicketCreate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `SupportTicket` | The support ticket. |

Error statuses: 400, 401, 403, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### List the messages of a ticket

`GET /v1/creator/support-tickets/{id}/messages` · operationId `listCreatorTicketMessages`

Auth: creator access token (OAuth) with scope `creator.support` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Support ticket id (`tkt_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `SupportMessageList` | Every message of the ticket, oldest first. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Reply to a ticket

`POST /v1/creator/support-tickets/{id}/messages` · operationId `replyCreatorTicket`

Auth: creator access token (OAuth) with scope `creator.support` · account types: any.

A closed ticket → `409 invalid_state`; open a new one.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Support ticket id (`tkt_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `SupportReply` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `SupportMessage` | Her new message. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_state` (all codes: Error codes below).

#### Close a ticket

`POST /v1/creator/support-tickets/{id}/close` · operationId `closeCreatorTicket`

Auth: creator access token (OAuth) with scope `creator.support` · account types: any.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Support ticket id (`tkt_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `SupportTicket` | The support ticket. |

Error statuses: 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Request her data export

`POST /v1/creator/data-export` · operationId `requestCreatorDataExport`

Auth: creator access token (OAuth) with scope `creator.privacy` · account types: any.

Everything we hold about her that she may see, as one JSON file (her GDPR rights of access and portability). Answers `202` with a job
(`Location: /v1/jobs/job_…`); when it succeeded, `GET /v1/creator/data-export/{id}` with `result.data_request`
gives a download link; the file is kept for 7 days. One export per app per 24 hours: asking again answers your
app's open or recent job. The export belongs to the app that asked: another of her apps gets `404 not_found`
for it and asks for its own. The file includes her support conversations with us. The app owner also receives
`data_export.ready` and `job.completed`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 202 | `Job` | The export job (new, or the open/recent one of the last 24 hours). Poll `Location` until `status` is `succeeded` or `failed`. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found` (all codes: Error codes below).

#### Get her data export

`GET /v1/creator/data-export/{id}` · operationId `getCreatorDataExport`

Auth: creator access token (OAuth) with scope `creator.privacy` · account types: any.

With `download_url` while `status` is `ready`: a fresh link on every call, valid for 1 hour at most and never past `expires_at`. Download right away; call again for a new link. Only the app that requested the export may read it (another of her apps: `404 not_found`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Data request id (`dreq_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `DataRequest` | The data request. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found` (all codes: Error codes below).

#### Request the deletion of her data

`POST /v1/creator/deletion-request` · operationId `requestCreatorDeletion`

Auth: creator access token (OAuth) with scope `creator.privacy` · account types: any.

Creates her deletion request (or answers the open one). Creator Guard checks and completes it: her personal
data, photos, login and grants are deleted; your account receives `deletion_request.completed`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 202 | `DataRequest` | Her deletion request (new, or the open one). Creator Guard handles it; the app owner receives `deletion_request.completed` when it is done. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Your app's connection

`GET /v1/creator/connected-apps` · operationId `listCreatorConnectedApps`

Auth: creator access token (OAuth) with scope `creator.profile:read` · account types: any.

Your own active grant for her (a list of at most one entry). Her other connected apps are never shown to an app: she sees and manages the full list in the hosted creator portal.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ConnectedAppList` | The apps she authorised and has not revoked. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Disconnect your app

`DELETE /v1/creator/connected-apps/{app}` · operationId `revokeCreatorConnectedApp`

Auth: creator access token (OAuth) with scope `creator.profile:write` · account types: any.

Revokes her grant of the calling app (pass your own app id), which ends this token and its refresh token. Any other app id is `404 not_found`: an app can never revoke her other connections; she does that in the hosted creator portal.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `app` | path | string | required | Id of a connected OAuth app (`app_…`). |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 204 | — | Deleted. The answer has no body. |

Error statuses: 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found` (all codes: Error codes below).

### Jobs

#### Get a job

`GET /v1/jobs/{id}` · operationId `getJob`

Auth: API key (any scopes) or creator access token (OAuth) (any scopes) · account types: any.

An asynchronous job. A `data_export` job needs a creator access token with `creator.privacy` (`403
insufficient_scope` otherwise) of the app that started it (another of her apps: `404`); no job type can be read
with an account API key yet (`404`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Job id (`job_…`). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Job` | The job. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `insufficient_scope` (all codes: Error codes below).

### Usage & audit

#### Your request log

`GET /v1/request-logs` · operationId `listRequestLogs`

Auth: API key with scope `account:read` · account types: any.

The last 30 days of this mode, newest first. Method, route template, status, error code, key and duration —
never bodies.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `ending_before` | query | string | optional | Id of the first item of the current page: the page before. |
| `status` | query | integer · 100–599 | optional | HTTP status, e.g. `429`. |
| `route` | query | string | optional | Route template as logged, e.g. `/v1/leads/{id}`. |
| `key` | query | string | optional | Only requests of this key (`key_…`). |
| `created_since` | query | string (date-time) | optional | RFC 3339 timestamp; only requests from then on. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `RequestLogList` | A page of your request log. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Usage statistics

`GET /v1/usage` · operationId `getUsage`

Auth: API key with scope `usage:read` · account types: any.

Requests, errors by code and p50/p95 latency per UTC day, per route and per key, for this mode. Without
`from` and `to` you get the last 30 days up to today; a range spans at most 90 days.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string (date) | optional | First day (UTC), `YYYY-MM-DD`; default 29 days before `to`. |
| `to` | query | string (date) | optional | Last day (UTC), inclusive; default today. |
| `granularity` | query | string | optional | `day` (the only value today). |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Usage` | Usage statistics. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

#### Audit trail of your account

`GET /v1/audit-events` · operationId `listAuditEvents`

Auth: API key with scope `audit:read` · account types: any.

Key, webhook and key-policy changes, account changes made with the API, test-data resets and limits changed
by Creator Guard — who, when, from which IP. 90 days, newest first, in the key's mode: a live key also sees
account-wide changes (`mode: null`), a test key only test-mode ones.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `ending_before` | query | string | optional | Id of the first item of the current page: the page before. |
| `action` | query | string | optional | e.g. `api_key.created`. |
| `created_since` | query | string (date-time) | optional | RFC 3339 timestamp; only changes from then on. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `AuditEventList` | A page of audit events. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

### Agency

#### Get your search profile

`GET /v1/search-profile` · operationId `getSearchProfile`

Auth: API key with scope `offers:read` · account types: agency.

What we match creators against before we offer them to you. Agency keys only (`403 wrong_account_type` otherwise). Before your first `PUT` you get the
defaults (`updated_at: null`, no `ETag`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `SearchProfile` | Your search profile. `ETag` only once you saved one. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type` (all codes: Error codes below).

#### Replace your search profile

`PUT /v1/search-profile` · operationId `replaceSearchProfile`

Auth: API key with scope `search_profile:write` · account types: agency.

**Full replacement:** a field you leave out goes back to its default (`[]`, `null`, `creator_stage: "both"`,
the portal `flex`) — read it, change what you need, send the whole object back. `flex` takes only the portal's
preset levels (`400 invalid_field` with `field: "flex.<key>"`). Money is US dollars only. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `SearchProfilePut` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `SearchProfile` | Your search profile. `ETag` only once you saved one. |

Error statuses: 400, 401, 403, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_field`, `terms_not_accepted`, `wrong_account_type` (all codes: Error codes below).

#### Get your agency profile

`GET /v1/agency-profile` · operationId `getAgencyProfile`

Auth: API key with scope `account:read` · account types: agency.

Your agency's public facts. `tier` and `verified_revenue` are set by Creator Guard. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `AgencyProfile` | Your agency profile. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type` (all codes: Error codes below).

#### Update your agency profile

`PATCH /v1/agency-profile` · operationId `updateAgencyProfile`

Auth: API key with scope `account:write` · account types: agency.

Only the fields you send change; `null` clears one. `tier` and `verified_revenue` cannot be sent
(`400 unknown_field`); `monthly_revenue` is whole US dollars. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `AgencyProfilePatch` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `AgencyProfile` | Your agency profile. |

Error statuses: 400, 401, 403, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `unknown_field`, `terms_not_accepted`, `wrong_account_type` (all codes: Error codes below).

### Offers

#### List your offers

`GET /v1/offers` · operationId `listOffers`

Auth: API key with scope `offers:read` · account types: agency.

Newest first. `status` is the public status: an open offer whose deadline passed reads `expired` even before
our hourly job closes it. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `ending_before` | query | string | optional | Id of the first item of the current page: the page before. |
| `status` | query | string · one of `offered`, `accepted`, `declined`, `expired`, `retracted`, `contacted`, `in_talks`, `signed`, `lost` | optional | Only offers with this status (an open offer past its deadline counts as `expired`). |
| `created_since` | query | string (date-time) | optional | RFC 3339 timestamp; only items created from then on. |
| `updated_since` | query | string (date-time) | optional | RFC 3339 timestamp; only items changed from then on. |
| `expires_before` | query | string (date-time) | optional | RFC 3339 timestamp; only offers whose deadline is before it. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `OfferList` | A page of offers. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type` (all codes: Error codes below).

#### Get an offer

`GET /v1/offers/{id}` · operationId `getOffer`

Auth: API key with scope `offers:read` · account types: agency.

The offer, the creator's listing while you may see it (open or accepted offers and later; `null` once declined,
expired or retracted), your reservation, `next_actions` and `match` against your search profile. Never her contact details, the referrer or internal
notes — the contact comes with `GET /v1/reservations/{id}/creator` after payment. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type` (all codes: Error codes below).

#### Set your note on an offer

`PATCH /v1/offers/{id}` · operationId `updateOffer`

Auth: API key with scope `offers:write` · account types: agency.

`agency_note` (1–500 characters after trimming, `null` clears it). Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `If-Match` | header | string | optional | The `ETag` you read. Stale → `412 precondition_failed`; without it the last write wins. |

Request body (`application/json`): `OfferPatch` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 409, 412, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type` (all codes: Error codes below).

#### List the creator's photos

`GET /v1/offers/{id}/photos` · operationId `listOfferPhotos`

Auth: API key with scope `offers:read` · account types: agency.

Only photos she agreed to share, as signed links valid for one hour, on one page. Only while the listing is
visible to you; otherwise `409 invalid_state` with `error.current_state`. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `OfferPhotoList` | The photos she agreed to share, as signed links valid for one hour. |

Error statuses: 400, 401, 403, 404, 409, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type`, `invalid_state` (all codes: Error codes below).

#### Accept an offer

`POST /v1/offers/{id}/accept` · operationId `acceptOffer`

Auth: API key with scope `offers:write` · account types: agency.

Reserves the creator for you and creates the reservation (`reservation`, status `awaiting_payment`). Needs the
current `agency_terms` **and** the current `warranty_terms` — otherwise `403 terms_not_accepted` with
`error.agreement_type` and nothing changes. `409 offer_taken` (another agency accepted first),
`409 offer_expired` (deadline passed), `409 listing_unavailable` (listing pulled or offer retracted),
`409 invalid_state` (not open). No request fields. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state`, `offer_taken`, `offer_expired`, `listing_unavailable` (all codes: Error codes below).

#### Decline an offer

`POST /v1/offers/{id}/decline` · operationId `declineOffer`

Auth: API key with scope `offers:write` · account types: agency.

`note` (50–500 characters after trimming) tells us why. Only open offers (`409 invalid_state`); a passed deadline
is `409 offer_expired`. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `OfferDecline` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state`, `offer_expired` (all codes: Error codes below).

#### Undo an accept

`POST /v1/offers/{id}/undo-accept` · operationId `undoAcceptOffer`

Auth: API key with scope `offers:write` · account types: agency.

Until `undo_until` (`GET /v1/settings` → `accept_undo_minutes`) and while the reservation is unpaid, the offer
goes back to `offered` and the reservation is cancelled. Later: `409 undo_window_passed`; not accepted or
already paid: `409 invalid_state`. No request fields. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state`, `undo_window_passed` (all codes: Error codes below).

#### Mark the creator as contacted

`POST /v1/offers/{id}/mark-contacted` · operationId `markOfferContacted`

Auth: API key with scope `offers:write` · account types: agency.

From `accepted`, once your reservation is paid (`409 payment_pending` before). No request fields. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `payment_pending` (all codes: Error codes below).

#### Mark talks as started

`POST /v1/offers/{id}/mark-in-talks` · operationId `markOfferInTalks`

Auth: API key with scope `offers:write` · account types: agency.

From `contacted` (`409 invalid_state` otherwise). No request fields. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state` (all codes: Error codes below).

#### Mark the creator as signed

`POST /v1/offers/{id}/mark-signed` · operationId `markOfferSigned`

Auth: API key with scope `offers:write` · account types: agency.

From `contacted` or `in_talks`, or from `accepted` once the reservation is paid (`409 payment_pending` before).
No request fields. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `payment_pending` (all codes: Error codes below).

#### Mark the placement as lost

`POST /v1/offers/{id}/mark-lost` · operationId `markOfferLost`

Auth: API key with scope `offers:write` · account types: agency.

Only from `accepted`, before the placement fee was received, with an `outcome_reason`. Once the fee was received the deal can no longer be marked lost (`409 deal_paid`): file a warranty claim (`POST /v1/reservations/{id}/warranty-claim`) instead. Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Offer id (`offer_…`). An id that is not one of your offers answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `OfferMarkLost` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Offer` | The offer. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `deal_paid` (all codes: Error codes below).

### Reservations

#### List your reservations

`GET /v1/reservations` · operationId `listReservations`

Auth: API key with scope `reservations:read` · account types: agency.

Newest first. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
| `starting_after` | query | string | optional | Id of the last item of the previous page: the next page. |
| `ending_before` | query | string | optional | Id of the first item of the current page: the page before. |
| `status` | query | string · one of `awaiting_payment`, `paid`, `completed`, `refunded`, `cancelled` | optional | Only reservations with this status. |
| `created_since` | query | string (date-time) | optional | RFC 3339 timestamp; only items created from then on. |
| `updated_since` | query | string (date-time) | optional | RFC 3339 timestamp; only items changed from then on. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ReservationList` | A page of reservations. |

Error statuses: 400, 401, 403, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type` (all codes: Error codes below).

#### Get a reservation

`GET /v1/reservations/{id}` · operationId `getReservation`

Auth: API key with scope `reservations:read` · account types: agency.

Amount, payment reference and due date, payment and warranty dates, your warranty claim. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Reservation` | The reservation. |

Error statuses: 400, 401, 403, 404, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type` (all codes: Error codes below).

#### File a warranty claim

`POST /v1/reservations/{id}/warranty-claim` · operationId `fileWarrantyClaim`

Auth: API key with scope `reservations:write` · account types: agency.

Once per reservation, while it is paid and the warranty runs. `409 claim_exists` (already filed),
`409 payment_pending` (not paid yet), `409 warranty_expired` (warranty over or completed), `409 invalid_state`
(refunded or cancelled). Agency keys only (`403 wrong_account_type` otherwise). Needs the current `agency_terms` (`403 terms_not_accepted`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `WarrantyClaimCreate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Reservation` | The reservation. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `terms_not_accepted`, `wrong_account_type`, `invalid_state`, `payment_pending`, `claim_exists`, `warranty_expired` (all codes: Error codes below).

#### Get the creator's contact

`GET /v1/reservations/{id}/creator` · operationId `getReservationCreator`

Auth: API key with scope `reservations:read` · account types: agency.

After payment only (`paid` or `completed`): name, Instagram, other contact, platforms, followers, niche and creator
number. Never the referrer or internal notes. Unpaid: `409 payment_pending`; refunded or cancelled:
`409 invalid_state`. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. |
| `fields` | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. `id,stage,creator_ref`; `id` and `object` always come along. In lists it applies to each item of `data`. A name the object does not have → `400 invalid_field`. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ReservationCreator` | The creator's contact. |

Error statuses: 400, 401, 403, 404, 409, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type`, `invalid_state`, `payment_pending` (all codes: Error codes below).

### Test mode

#### Confirm consent and 18+ (test mode)

`POST /v1/test-helpers/leads/{id}/confirm` · operationId `testConfirmLead`

Auth: API key with scope `leads:write` · account types: any.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Records consent and the
18+ confirmation as if she had used her link.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Lead` | The lead. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found` (all codes: Error codes below).

#### Approve the listing (test mode)

`POST /v1/test-helpers/leads/{id}/approve-listing` · operationId `testApproveListing`

Auth: API key with scope `leads:write` · account types: any.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Plays our review: a
listing in review goes live. Missing consent, 18+ confirmation or fee → `422 not_ready_for_review`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Lead` | The lead. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found`, `not_ready_for_review` (all codes: Error codes below).

#### Reject a lead (test mode)

`POST /v1/test-helpers/leads/{id}/reject` · operationId `testRejectLead`

Auth: API key with scope `leads:write` · account types: any.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Plays our review: the lead
becomes `rejected` with your `outcome_reason`.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Lead id (`lead_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `TestLeadReject` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Lead` | The lead. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found` (all codes: Error codes below).

#### Pay a commission (test mode)

`POST /v1/test-helpers/commissions/{id}/mark-paid` · operationId `testMarkCommissionPaid`

Auth: API key with scope `leads:write` · account types: any.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. A `due` commission becomes
`paid` (any other → `409 invalid_state`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Commission id (`com_…`). |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Commission` | The commission. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found`, `invalid_state` (all codes: Error codes below).

#### Delete all test data (test mode)

`POST /v1/test-helpers/reset` · operationId `testReset`

Auth: API key with scope `keys:manage` · account types: any.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Deletes every lead, photo,
commission, event, delivery, sandbox file and stored `Idempotency-Key` answer of your account in the
sandbox. Your keys, webhook endpoints and accepted terms stay.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `TestReset` | What was deleted from the sandbox. |

Error statuses: 401, 403, 404, 409, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `not_found` (all codes: Error codes below).

#### A sandbox photo or logo

`GET /v1/test-files/{path}` · operationId `getTestFile`

Auth: none (no API key needed).

Photo and logo URLs of test mode point here; use them exactly as given. No key needed: the URL carries a
signed `token` that expires like every photo URL (1 hour). `{path}` is `<bucket>/<folder>/<file>` and
contains slashes, so your request log shows this route as `/v1/test-files/{bucket}/{path}`. Requests
without a key share a per-IP budget (`429 rate_limited`).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `path` | path | string | required | Bucket and object path as in the URL we gave you; contains slashes. |
| `token` | query | string | required | Signed token from the URL we gave you. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | — | The file. |

Error statuses: 400, 404, 429, 500, 502, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `rate_limited` (all codes: Error codes below).

#### Create a test offer (test mode)

`POST /v1/test-helpers/offers` · operationId `testCreateOffer`

Auth: API key with scope `offers:write` · account types: agency.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Creates a synthetic creator of a fixed sandbox referrer and offers her to your agency, as our matching
would. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `TestOfferCreate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `Offer` | The new test offer. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below).

#### Mark a reservation as paid (test mode)

`POST /v1/test-helpers/reservations/{id}/mark-paid` · operationId `testMarkReservationPaid`

Auth: API key with scope `reservations:write` · account types: agency.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Plays our bookkeeping when your transfer arrives: `awaiting_payment` → `paid` (her contact is unlocked, the
warranty starts). No request fields. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Reservation` | The reservation. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below).

#### Complete a reservation (test mode)

`POST /v1/test-helpers/reservations/{id}/complete` · operationId `testCompleteReservation`

Auth: API key with scope `reservations:write` · account types: agency.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Ends the warranty early: `paid` → `completed`. No request fields. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Reservation` | The reservation. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below).

#### Refund a reservation (test mode)

`POST /v1/test-helpers/reservations/{id}/refund` · operationId `testRefundReservation`

Auth: API key with scope `reservations:write` · account types: agency.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Plays an accepted warranty claim: `paid` → `refunded`. Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | required | Reservation id (`res_…`). An id that is not one of your reservations answers `404 not_found`. |
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `TestReservationRefund` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `Reservation` | The reservation. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below).

#### Advance the test clock (test mode)

`POST /v1/test-helpers/clock/advance` · operationId `testAdvanceClock`

Auth: API key with scope `offers:write` · account types: agency.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. Moves the deadlines of your test offers and reservations `hours` (1–720) into the past and runs our expiry
jobs: open offers expire, unpaid reservations are cancelled, warranties complete — with the same events.
Agency keys only (`403 wrong_account_type` otherwise).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |

Request body (`application/json`): `ClockAdvance` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 200 | `ClockAdvanceResult` | What the expiry jobs changed in your sandbox. |

Error statuses: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `wrong_account_type`, `not_found` (all codes: Error codes below).

#### Create an authorization code (test mode)

`POST /v1/test-helpers/oauth-codes` · operationId `testOAuthCode`

Auth: API key with scope `oauth_apps:manage` · account types: any.

Only with a `cg_test_` key — a live key gets `404 not_found` and nothing happens. The hosted sign-in page
`/oauth/authorize` serves live apps only (the sandbox has no real creator logins), so a test-mode app
(`cgcl_test_…`) gets its authorization codes here, exactly as if the creator of the lead had clicked
"Allow": the answer's `code` is valid for 60 seconds and one exchange at the normal `/oauth/token`, together
with the `code_verifier` behind `code_challenge` (S256). The lead must be one your account may connect (you
submitted it, or you hold a paid reservation for it), otherwise `404 not_found`. `redirect_uri` and every
scope must be registered for the app (`400 invalid_field`). A code is a single-use secret, so an
`Idempotency-Key` is ignored and a retry creates a new code. `503 not_configured` while OAuth is switched
off on our side.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | optional | Ignored on this endpoint: a code is single-use, a retry creates a new one. |

Request body (`application/json`): `OAuthTestCodeCreate` — fields under Schemas.

Responses:

| Status | Body | Meaning |
|---|---|---|
| 201 | `OAuthTestCode` | A test-mode authorization code, shown this once: valid for 60 seconds and one exchange at `/oauth/token`. |

Error statuses: 400, 401, 403, 404, 413, 415, 429, 500, 503 — body `ErrorResponse`; codes per status under "Error responses by status".

Error codes named for this operation: `invalid_field`, `not_found`, `not_configured` (all codes: Error codes below).

### Response headers

| Header | Type | Sent | Description |
|---|---|---|---|
| `X-Request-Id` | string · pattern `^req_[a-z2-7]{26}$` | always | Id of this request (`req_…`), also `error.request_id`. Quote it to support. |
| `X-API-Version` | string · pattern `^1\.[0-9]+\.[0-9]+$` | always | The contract version that answered (`info.version`). Log it with your requests. |
| `RateLimit-Policy` | string | when it applies | The limits that apply to this key, e.g. `100;w=60, 10000;w=86400`. |
| `RateLimit` | string | when it applies | State of the tightest window: `limit=100, remaining=97, reset=42` (seconds). |
| `Retry-After` | integer | when it applies | Seconds to wait before the next attempt, computed from the window that is used up. |
| `ETag` | string | when it applies | Version of the resource; send it back in `If-Match` to make a change race-safe. |
| `Idempotent-Replayed` | string | when it applies | `true` when this is the stored answer to an earlier request with the same `Idempotency-Key`. |

### Error responses by status

| Status | Codes and meaning |
|---|---|
| 400 | The body, a field or a query parameter is invalid: `invalid_json`, `invalid_body`, `unknown_field`, `unknown_parameter`, `missing_field`, `invalid_field`, `missing_contact`, `age_below_18`, `consent_required`, `invalid_cursor`. `unknown_parameter` and `invalid_cursor` name the query parameter in `error.parameter`. |
| 401 | `missing_key`, `invalid_key` (unknown or revoked) or `expired_key`. Not counted against any limit. |
| 403 | `account_not_active`, `terms_not_accepted` (with `error.agreement_type`), `insufficient_scope` (with `error.scope`), `wrong_account_type` or `ip_not_allowed`. |
| 404 | `not_found`: unknown id, a resource of another account (never `403`), or a test helper called with a live key. |
| 409 | `duplicate_own_lead` (with `error.lead`), `duplicate_other_referrer` (on create and on a `PATCH` that changes `instagram_handle`), `lead_locked`, `listing_locked`, `invalid_state`, `external_id_taken`, `photos_locked`, `limit_reached` (with `error.limit`) or `idempotency_in_progress`; on the agency endpoints also `offer_taken`, `offer_expired`, `listing_unavailable`, `payment_pending`, `deal_paid`, `undo_window_passed`, `claim_exists` or `warranty_expired`. `invalid_state` carries `error.current_state` — the lead's stage (`draft`, `in_review`, `ready`, `offered`, `accepted`, `in_placement`, `placed`, `withdrawn`, `rejected`, `lost`), `withdrawn` for a fee on a withdrawn listing, `anonymized` for a consent link after her data was erased, or `age_declined` / `age_pending` for a consent grant while her 18+ check is declined or under review — except on agreement accept, where it carries `error.current_version` instead. |
| 412 | `precondition_failed`: the `If-Match` value is not the current `ETag`. Read again, then retry. |
| 413 | `payload_too_large`: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB. |
| 415 | `unsupported_media_type`: send `Content-Type: application/json` (uploads: `multipart/form-data` with a JPEG, PNG or WebP file). |
| 422 | `not_ready_for_review` (with `error.blockers`), `idempotency_key_reused` (same key, different body) or `image_unreadable` (an upload that cannot be decoded). |
| 429 | `rate_limited`, `concurrency_limited` or `duplicate_limit_reached`. Wait `Retry-After` seconds. Before a key is accepted (per-IP budget for requests without a valid key) the answer has no RateLimit headers. |
| 500 | `internal_error`. Safe to retry with the same `Idempotency-Key`; quote `request_id` to support. |
| 503 | `not_configured`: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable. |
| 502 | `upstream_failed`: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored. |

### Limits

Defaults of every API key (test keys get half, rounded up — see Rate limits):

- `per-minute`: 100
- `per-day`: 10000
- `duplicate-probes-per-day`: 20
- `concurrent-requests-per-key`: 25
- `max-body-bytes`: 1000000

### Error codes

Every error has the body `ErrorResponse` (`{"error": {type, code, message, …}}`). Branch on `error.code`.

| Status | Code | When | Retry |
|---|---|---|---|
| 400 | `invalid_json` | The body is not valid JSON. | no |
| 400 | `invalid_body` | The body is not a JSON object (for example an array). | no |
| 400 | `unknown_field` | A request field is not in the contract; `error.field` names it. | no |
| 400 | `unknown_parameter` | A query parameter this endpoint does not support; `error.parameter` names it. | no |
| 400 | `missing_field` | A required field is missing; `error.details` lists every problem. | no |
| 400 | `invalid_field` | A value has the wrong type, length, range or format. | no |
| 400 | `missing_contact` | `PATCH /v1/creator/profile` would leave her lead with neither `instagram_handle` nor `other_contact`. | no |
| 400 | `age_below_18` | `age` is below 18. | no |
| 400 | `consent_required` | `consent_confirmed` is not exactly `true`. | no |
| 400 | `invalid_cursor` | `starting_after` or `ending_before` is not one of your leads; `error.parameter` names it. | no |
| 401 | `missing_key` | No `Authorization: Bearer` header. | no |
| 401 | `invalid_key` | The key is unknown or revoked. | no |
| 401 | `expired_key` | The key is past its expiry date. | no |
| 401 | `invalid_token` | The creator access token is unknown, revoked, or from the other mode (her grant ended or was revoked: send her through the authorize flow again). | refresh |
| 401 | `expired_token` | The creator access token is past its hour: refresh it at `/oauth/token`. | refresh |
| 403 | `account_not_active` | The account is pending approval or disabled. With a creator access token: the account that owns the OAuth app (her grant stays and works again once the account is approved). | no |
| 403 | `terms_not_accepted` | A write needs the account's terms — and with a live key the API Terms (`api_terms`) and the data protection addendum (`api_dpa`); `error.agreement_type` names one at a time (the API Terms first), so accept and retry until the write goes through. | after accepting |
| 403 | `insufficient_scope` | The key lacks the scope in `error.scope`. | no |
| 403 | `wrong_account_type` | The endpoint is not for this account type. | no |
| 403 | `ip_not_allowed` | The key has an IP allowlist that does not contain the caller. | no |
| 403 | `mfa_required` | Portal only: key, webhook and payout changes need a second factor. API keys never get it. | after sign-in |
| 403 | `referrer_app_not_allowed` | Creator token of an OAuth app owned by the account that referred her: her consent, 18+ confirmation and creator terms are given only on Creator Guard (consent link or creator portal). Withdrawing consent is never refused. | no |
| 404 | `not_found` | Unknown path or id, or a resource of another account. | no |
| 405 | `method_not_allowed` | The path exists, the HTTP method does not. | no |
| 409 | `duplicate_own_lead` | Your lead with this Instagram handle is past `draft`; `error.lead` names it. | no |
| 409 | `duplicate_other_referrer` | Another account already submitted this Instagram handle (create, or a `PATCH` of `instagram_handle`). | no |
| 409 | `lead_locked` | Lead fields can no longer change (the lead left `draft`). | no |
| 409 | `listing_locked` | The listing is live; its fields and fee can no longer change. | no |
| 409 | `photos_locked` | The listing is live; its photos can no longer change (partner and creator endpoints alike). | no |
| 409 | `invalid_state` | Not allowed in the current state; `error.current_state` names it (`error.current_version` on agreement accept). | no |
| 409 | `offer_taken` | Accepting an offer: another agency accepted her first. | no |
| 409 | `offer_expired` | Accepting or declining an offer whose deadline passed. | no |
| 409 | `listing_unavailable` | Accepting an offer whose listing was pulled or that we retracted. | no |
| 409 | `payment_pending` | The step needs a paid reservation (offer progress, the creator's contact, a warranty claim). | later |
| 409 | `deal_paid` | Marking an offer lost after the placement fee was received. A paid deal ends only through a warranty claim or Creator Guard. | no |
| 409 | `undo_window_passed` | Undoing an accept after `undo_until`. | no |
| 409 | `claim_exists` | A second warranty claim on the same reservation. | no |
| 409 | `warranty_expired` | A warranty claim after the warranty ended. | no |
| 409 | `external_id_taken` | `external_id` is used by another of your leads. | no |
| 409 | `consent_text_outdated` | Granting consent, the 18+ confirmation or accepting the creator terms with a text version that is not the current one; `error.current_version` names it. Show her the current text (`GET /v1/creator/consent-text`) and ask again. A withdrawal never fails for this reason. | after refetch |
| 409 | `idempotency_in_progress` | The first request with this `Idempotency-Key` is still running. | yes |
| 409 | `limit_reached` | A limit of the account is reached (10 active keys or 10 webhook endpoints per mode, 20 photos per lead, 1,000 open deliveries per endpoint on replay); `error.limit` is the number. | no |
| 410 | `version_sunset` | A retired major version (not used in v1 yet). | no |
| 412 | `precondition_failed` | `If-Match` is not the current `ETag`. | after refetch |
| 413 | `payload_too_large` | The body is larger than 1 MB. | no |
| 415 | `unsupported_media_type` | The body is not `application/json`. | no |
| 422 | `not_ready_for_review` | Blockers remain; `error.blockers` lists them. | after fixing |
| 422 | `idempotency_key_reused` | The same `Idempotency-Key` with a different body. | no |
| 422 | `image_unreadable` | The uploaded file is not a readable JPEG, PNG or WebP image. | no |
| 429 | `rate_limited` | A rate limit is used up; wait `Retry-After` seconds. | yes |
| 429 | `concurrency_limited` | More than 25 requests of this key are in flight. | yes, slower |
| 429 | `duplicate_limit_reached` | The daily budget of answers about other accounts' creators is used up. | after Retry-After |
| 500 | `internal_error` | Unexpected error on our side; quote `request_id`. | yes |
| 502 | `upstream_failed` | A service we depend on failed (text extraction, or the DNS lookup of a webhook URL); nothing was stored. | yes |
| 503 | `not_configured` | A setting is missing on our side (for example text extraction), or test mode is briefly unavailable. | no |

### Event types

Webhook events and `GET /v1/events`; the payload of each is the `Event` envelope with `data.object`.

| Type | When | `data.object` | Sent to | Scope to read it |
|---|---|---|---|---|
| `lead.created` | A lead was created (API or portal). | `Lead` | The account that owns the lead. | `leads:read` |
| `lead.updated` | Lead or listing fields changed; `previous_attributes` names them. | `Lead` | The account that owns the lead. | `leads:read` |
| `lead.stage_changed` | The lead moved to another stage; `previous_attributes.stage` is the old one. | `Lead` | The account that owns the lead. | `leads:read` |
| `lead.withdrawn` | The lead was withdrawn. | `Lead` | The account that owns the lead. | `leads:read` |
| `listing.approved` | Our review approved the listing; it is live for agencies. | `Lead` | The account that owns the lead. | `leads:read` |
| `photo.added` | A photo was added (API or portal). | `Photo` | The account that owns the lead. | `leads:read` |
| `photo.removed` | A photo was removed; `data.object` is the photo as it was, `url` is `null`. | `Photo` | The account that owns the lead. | `leads:read` |
| `consent.granted` | She granted consent on her page. | `Confirmations` | The account that owns the lead. | `leads:read` |
| `consent.revoked` | She revoked her consent. | `Confirmations` | The account that owns the lead. | `leads:read` |
| `age_confirmation.confirmed` | Her 18+ confirmation was recorded. | `Confirmations` | The account that owns the lead. | `leads:read` |
| `commission.created` | A commission was booked for your lead (her placement completed). | `Commission` | The account that owns the lead. | `earnings:read` |
| `commission.paid` | We paid a commission; `previous_attributes.status` is the old status. | `Commission` | The account that owns the lead. | `earnings:read` |
| `commission.voided` | A commission was voided; `previous_attributes.status` is the old status. | `Commission` | The account that owns the lead. | `earnings:read` |
| `agreement.published` | A new version of terms that apply to you was published. | `Agreement` | Every approved account of the type the terms are for; for `api_terms` and `api_dpa` every approved account. | `account:read` |
| `api_key.expiring` | A live key expires within 7 days (sent once per key). | `ApiKey` | The account of the key (live keys only). | `keys:manage` |
| `webhook_endpoint.disabled` | An endpoint was disabled after 72 hours of failed deliveries. | `WebhookEndpoint` | The account of the endpoint. | `webhooks:manage` |
| `offer.created` | We offered a creator to your agency (portal, matching or `POST /v1/test-helpers/offers`). | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.accepted` | The offer was accepted (API or portal); `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.declined` | The offer was declined; `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.expired` | The offer deadline passed before an accept or decline. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.retracted` | We withdrew the offer (for example the listing was pulled or another agency won her). | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.reopened` | Your retracted offer is open again: the agency that won her undid its accept within the undo window. `previous_attributes.status` is `retracted`. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.progressed` | Any other status change: contacted, in talks, signed, lost, or back to offered after your own undo; `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.consent_revoked` | She withdrew her consent to share her profile. Sent for every offer your agency holds for her, whatever its status: delete what you keep of her listing and photos. Her listing is hidden (`listing` and `photo_count` `null`, photos refused) while the withdrawal stands, unless your placement of her is completed; an open offer is retracted as well (`offer.retracted`), and an accepted offer whose reservation still awaits payment is retracted with its reservation cancelled (`reservation.cancelled`). | `Offer` | Every agency holding an offer for her. | `offers:read` |
| `reservation.created` | An accept created a reservation (`awaiting_payment`). | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `reservation.paid` | We received your payment: the reservation is `paid`, her contact is unlocked, the warranty runs. | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `reservation.completed` | The warranty ended without a refund. | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `reservation.refunded` | We refunded the fee after an accepted warranty claim. | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `reservation.cancelled` | The reservation was cancelled: not paid in time, or the accept was undone. | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `warranty_claim.created` | A warranty claim was filed on the reservation (API or portal). | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `data_export.ready` | A creator's data export that your app requested is ready. Fetch the download link with her token: `GET /v1/creator/data-export/{id}`. | `DataRequestRef` | The account that owns the OAuth app whose creator token requested the export. | `oauth_apps:manage` |
| `job.completed` | An asynchronous job your app started finished (`succeeded` or `failed`). `GET /v1/jobs/{id}` with her token has the status and result. | `JobRef` | The account that owns the OAuth app whose creator token started the job. | `oauth_apps:manage` |
| `deletion_request.completed` | Creator Guard carried out the deletion request your app sent: her data is anonymised and her login and grants are gone. Stop processing her data in your systems. | `DataRequestRef` | The account that owns the OAuth app whose creator token sent the deletion request (even though her grant no longer exists). | `oauth_apps:manage` |
| `ping` | A test send (`POST /v1/webhook-endpoints/{id}/test`). | `{}` | Only the endpoint that was tested. | any key |

### Schemas

#### `ApiInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"api"` (exactly) | required |  |
| `api_version` | string | required | Same as `X-API-Version`. |
| `status` | string | required | `beta` today. |
| `docs_url` | string (uri) | required |  |
| `openapi_url` | string (uri) | required |  |

#### `Account`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"account"` (exactly) | required |  |
| `id` | string · pattern `^acct_[a-z2-7]{26}$` | required |  |
| `type` | string | required | `referrer` or `agency`. |
| `status` | string | required | `approved` for every key that works (other states answer `403 account_not_active`). |
| `display_name` | string or null | required |  |
| `company_name` | string or null | required |  |
| `website` | string or null | required |  |
| `telegram_username` | string or null | required |  |
| `logo_url` | string or null | required |  |
| `terms` | array of object | required | One entry per agreement type that applies to the account (`api_terms` and `api_dpa` for every account). |
| `limits` | object | required | Limits in effect (defaults or your account's overrides). |

#### `Agreement`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"agreement"` (exactly) | required |  |
| `type` | string | required | `referrer_terms`, `agency_terms`, `warranty_terms`, `api_terms`, `api_dpa` |
| `current_version` | integer or null | required |  |
| `published_at` | string or null (date-time) | required |  |
| `accepted` | boolean | required |  |
| `accepted_version` | integer or null | required |  |
| `accepted_at` | string or null (date-time) | required |  |
| `acceptances` | array of object | required | Every version the account accepted. |

#### `AgreementList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `Agreement` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `AgreementDocument`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"agreement_document"` (exactly) | required |  |
| `type` | string | required |  |
| `version` | integer | required |  |
| `published_at` | string or null (date-time) | required |  |
| `current` | boolean | required | Whether this is the version to accept. |
| `body_md` | string | required | The text as Markdown. |

#### `AgreementAccept`

| Field | Type | Required | Description |
|---|---|---|---|
| `version` | integer · ≥ 1 | required | Must be the current published version. |

#### `OptionLists`

Values in the spelling we store. Lists can change. Full lists: https://docs.creator-guard.com/reference/allowed-values/

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"option_lists"` (exactly) | required |  |
| `platforms` | array of string | required |  |
| `languages` | array of string | required |  |
| `content_types` | array of string | required |  |
| `niches` | array of string | required |  |
| `specializations` | array of string | required |  |

#### `Settings`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"settings"` (exactly) | required |  |
| `offer_deadline_hours` | integer | required |  |
| `accept_undo_minutes` | integer | required |  |
| `payment_due_days` | integer | required |  |
| `warranty_days` | integer | required |  |
| `creator_guard_share_percent` | integer | required | Creator Guard's share of a placement fee; yours is the rest. |

#### `Money`

An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set.

| Field | Type | Required | Description |
|---|---|---|---|
| `amount_minor` | integer | required |  |
| `currency` | string | required | `USD`, `EUR` or `GBP` today. |

#### `MoneyInput`

`{"amount_minor": 150000, "currency": "USD"}` = 1,500.00 USD. `null` clears the fee.

| Field | Type | Required | Description |
|---|---|---|---|
| `amount_minor` | integer · 0–9999999999 | required |  |
| `currency` | string · one of `USD`, `EUR`, `GBP` | required |  |

#### `NextActions`

What you can do with the lead right now — computed by Creator Guard, so you never re-implement the rules.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_edit_lead` | boolean | required |  |
| `can_edit_listing` | boolean | required |  |
| `can_edit_fee` | boolean | required |  |
| `can_withdraw` | boolean | required |  |
| `can_submit_for_review` | boolean | required |  |
| `blockers` | array of string | required | What still keeps her off the marketplace, while the lead is `draft` or `in_review` and the listing is not live (else empty): `age_missing`, `languages_missing`, `country_missing`, `content_types_missing`, `photos_missing` (3 needed), `consent_missing`, `age_confirmation_missing`, `fee_missing`. Every blocker also blocks submit-for-review. `fee_missing` appears only on leads whose fee you set (never on leads our team added for your account). New values may be added. |

#### `ListingSummary`

The listing summary every lead carries. With `?expand=listing` the lead carries the full Listing object instead (without `photo_count`).

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | required | `draft`, `in_review`, `live` or `withdrawn`. |
| `placement_fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `photo_count` | integer | required | Photos she has. |

#### `Photo`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"photo"` (exactly) | required |  |
| `id` | string · pattern `^photo_[a-z2-7]{26}$` | required |  |
| `kind` | string | required |  |
| `is_primary` | boolean | required |  |
| `consent_status` | string | required |  |
| `url` | string or null (uri) | required | Signed, valid for 1 hour; `null` when the file could not be signed, for a removed photo and in the replay of an upload. |
| `url_expires_at` | string or null (date-time) | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `created_at` | string or null (date-time) | required |  |
| `version` | integer · ≥ 0 | required | Grows with every change of the photo; events about it carry the same number as `sequence`. |

#### `ConsentState`

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | required | `pending`, `granted` or `revoked`. |
| `granted_at` | string or null (date-time) | required |  |
| `revoked_at` | string or null (date-time) | required |  |

#### `AgeConfirmation`

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | required | `missing`, `confirmed` or `declined`. |
| `confirmed_at` | string or null (date-time) | required |  |

#### `CreatorLogin`

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | required | `none` or `active`. |

#### `Confirmations`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"confirmations"` (exactly) | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `consent` | `ConsentState` | required |  |
| `age_confirmation` | `AgeConfirmation` | required |  |
| `creator_login` | `CreatorLogin` | required |  |

#### `Lead`

One creator you submitted. New fields may be added within v1; ignore fields you do not know.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"lead"` (exactly) | required |  |
| `id` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `external_id` | string or null | required |  |
| `creator_ref` | string or null · pattern `^CR-[0-9]+$` | required | Her creator number; quote it to support. |
| `creator_name` | string | required |  |
| `instagram_handle` | string or null | required | As stored (normalised username). |
| `other_contact` | string or null | required |  |
| `platforms` | array of string | required |  |
| `follower_count` | integer or null | required |  |
| `niche` | string or null | required |  |
| `notes` | string or null | required |  |
| `stage` | string | required | `draft`, `in_review`, `ready`, `offered`, `accepted`, `in_placement`, `placed`, `rejected`, `lost` or `withdrawn`. New values may be added. |
| `outcome_reason` | string or null | required | Why a lead was rejected or lost. |
| `next_actions` | `NextActions` | required | What you can do with the lead right now — computed by Creator Guard, so you never re-implement the rules. |
| `listing` | `ListingSummary` or `Listing` | required | The summary; with `?expand=listing` the full Listing object. |
| `confirmations` | `Confirmations` | optional |  |
| `consent` | `LeadConsent` | optional | Her consent and her personal consent link. Links are stored only as hashes, so `url` is shown once: in the `201` that created the lead (a new link, valid at least 30 days). A `200` of `POST /v1/leads` and `GET /v1/leads/{id}` answer `url: null` with the current `expires_at`; `POST /v1/leads/{id}/consent-link` makes a new link. Reading a lead never extends it. |
| `photos` | array of `Photo` | optional | Only with `?expand=photos`. |
| `created_at` | string (date-time) | required |  |
| `updated_at` | string (date-time) | required |  |
| `version` | integer · ≥ 0 | required | Grows with every change of the lead or its listing; events about it carry the same number as `sequence`. `0` until the first change after 1.5.0. |

#### `LeadList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `Lead` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required | Pass as `starting_after` for the next page; `null` on the last page. |

#### `LeadCreate`

One creator. Required are only her name and `consent_confirmed`, as in the portal; send every other field
you know (a contact and her platforms make her far easier to place). Unknown fields → `400 unknown_field`.
Strings are trimmed before they are checked; lengths count after trimming. `null` for an optional field is
the same as leaving it out (not for `platforms`: leave it out instead).

| Field | Type | Required | Description |
|---|---|---|---|
| `external_id` | string or null · 1–100 chars | optional | Your own reference, unique within your account. Repeating it returns the existing lead (`200`). |
| `creator_name` | string · 1–120 chars | required | Name or alias. |
| `instagram_handle` | string or null · 1–200 chars | optional | Username (`@handle`) or profile link (`instagram.com/<handle>`). Anything else → `400 invalid_field`. Recognises creators already in the system; without it there is no duplicate check by handle. |
| `other_contact` | string or null · 1–200 chars | optional | Any other way to reach her (Telegram, phone, …). |
| `platforms` | array of string · at least 1, at most 20, each ≤ 40 chars | optional | Platforms she is on; pick-list values are stored in their spelling. [Allowed values](https://docs.creator-guard.com/reference/allowed-values/). Optional; when sent, at least one entry. |
| `follower_count` | integer or null (int32) · 0–2147483647 | optional | Followers on her largest platform. |
| `niche` | string or null · 1–80 chars | optional | A pick-list niche is stored in its spelling. [Allowed values](https://docs.creator-guard.com/reference/allowed-values/). |
| `notes` | string or null · 1–2000 chars | optional | For our team; never shown to agencies. |
| `consent_confirmed` | `true` (exactly) | required | Your declaration that she agreed to be referred and to you sending these details. Must be exactly `true`. |
| `listing` | `ListingPatch` | optional | Listing fields. Every field is optional; `null` clears a value, `[]` empties a list. |

#### `LeadUpdate`

Send only the fields to change; `null` clears an optional field. Lead fields while `can_edit_lead`; `external_id` always.

| Field | Type | Required | Description |
|---|---|---|---|
| `external_id` | string or null · 1–100 chars | optional |  |
| `creator_name` | string · 1–120 chars | optional |  |
| `instagram_handle` | string or null · 1–200 chars | optional |  |
| `other_contact` | string or null · 1–200 chars | optional |  |
| `platforms` | array of string · at least 1, at most 20, each ≤ 40 chars | optional |  |
| `follower_count` | integer or null (int32) · 0–2147483647 | optional |  |
| `niche` | string or null · 1–80 chars | optional |  |
| `notes` | string or null · 1–2000 chars | optional |  |

#### `ListingPatch`

Listing fields. Every field is optional; `null` clears a value, `[]` empties a list.

| Field | Type | Required | Description |
|---|---|---|---|
| `age` | integer or null · 18–99 | optional | Below 18 → `400 age_below_18`. |
| `gender` | string or null · one of `female`, `male`, `trans`, `non_binary`, `other` | optional |  |
| `origin_country` | string or null · 1–80 chars | optional |  |
| `languages` | array of string · at most 20, each ≤ 40 chars | optional |  |
| `english_level` | integer or null · 1–10 | optional |  |
| `content_types` | array of string · at most 30, each ≤ 40 chars | optional | Content categories she is comfortable with. Values: [allowed values](https://docs.creator-guard.com/reference/allowed-values/). |
| `content_freetext` | string or null · 1–2000 chars | optional |  |
| `has_of_account` | boolean or null | optional |  |
| `of_verified` | boolean or null | optional |  |
| `of_current_earnings` | integer or null · 0–2147483647 | optional | USD per month. |
| `content_ready` | boolean or null | optional |  |
| `scripts_ready` | boolean or null | optional |  |
| `account_access` | string or null · one of `yes`, `no`, `undiscussed` | optional |  |
| `device` | string or null · 1–200 chars | optional |  |
| `social_status` | string or null · one of `none`, `ready_to_create`, `existing` | optional |  |
| `social_preferences` | object | optional | Platform (1–40 characters) → wants to be active there; at most 20 entries. |
| `tiktok_ok` | boolean or null | optional |  |
| `blocked_countries` | array of string · at most 250, each ≤ 80 chars | optional |  |
| `start_availability` | string or null · one of `now`, `date` | optional |  |
| `start_date` | string or null (date) | optional |  |
| `availability_hours_per_week` | number or null · 0–168 | optional |  |
| `availability_hours_per_day` | number or null · 0–24 | optional |  |
| `compensation_model` | string or null · one of `revenue_share`, `fixed` | optional |  |
| `creator_share_percent` | integer or null · 0–100 | optional |  |
| `fixed_salary` | integer or null · 0–2147483647 | optional |  |
| `salary_period` | string or null · one of `weekly`, `monthly` | optional |  |
| `placement_fee` | `MoneyInput` | optional | `{"amount_minor": 150000, "currency": "USD"}` = 1,500.00 USD. `null` clears the fee. |
| `notes_public` | string or null · 1–2000 chars | optional | Shown to agencies with the listing. |

#### `Listing`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"listing"` (exactly) | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `status` | string | required | `draft`, `in_review`, `live` or `withdrawn`. |
| `age` | integer or null | required |  |
| `gender` | string or null | required |  |
| `origin_country` | string or null | required |  |
| `languages` | array of string | required |  |
| `english_level` | integer or null | required |  |
| `content_types` | array of string | required |  |
| `content_freetext` | string or null | required |  |
| `has_of_account` | boolean or null | required |  |
| `of_verified` | boolean or null | required |  |
| `of_current_earnings` | integer or null | required |  |
| `content_ready` | boolean or null | required |  |
| `scripts_ready` | boolean or null | required |  |
| `account_access` | string or null | required |  |
| `device` | string or null | required |  |
| `social_status` | string or null | required |  |
| `social_preferences` | object | required |  |
| `tiktok_ok` | boolean or null | required |  |
| `blocked_countries` | array of string | required |  |
| `start_availability` | string or null | required |  |
| `start_date` | string or null (date) | required |  |
| `availability_hours_per_week` | number or null | required |  |
| `availability_hours_per_day` | number or null | required |  |
| `compensation_model` | string or null | required |  |
| `creator_share_percent` | integer or null | required |  |
| `fixed_salary` | integer or null | required |  |
| `salary_period` | string or null | required |  |
| `placement_fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `notes_public` | string or null | required |  |
| `updated_at` | string or null (date-time) | required |  |

#### `LeadConsent`

Her consent and her personal consent link. Links are stored only as hashes, so `url` is shown once: in the `201` that created the lead (a new link, valid at least 30 days). A `200` of `POST /v1/leads` and `GET /v1/leads/{id}` answer `url: null` with the current `expires_at`; `POST /v1/leads/{id}/consent-link` makes a new link. Reading a lead never extends it.

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | required | `pending`, `granted` or `revoked`. |
| `url` | string or null (uri) | required | Her personal page on app.creator-guard.com — only in the `201` that created the lead; `null` otherwise (stored hashed) and after her data was erased at her request. |
| `expires_at` | string or null (date-time) | required | When her current link stops working; a new one: `POST /v1/leads/{id}/consent-link`. `null` after her data was erased. |

#### `ConsentLink`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"consent_link"` (exactly) | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `url` | string (uri) | required | Her personal page on app.creator-guard.com — a new link; the previous one can then only be used to withdraw consent. Shown only in this answer. |
| `expires_at` | string (date-time) | required |  |

#### `ClaimLink`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"claim_link"` (exactly) | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `url` | string or null (uri) | required | Her single-use page on app.creator-guard.com (`/claim/<token>`); `null` in an Idempotency-Key replay. |
| `expires_at` | string (date-time) | required |  |

#### `Timeline`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"timeline"` (exactly) | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `events` | array of object | required | Oldest first; only milestones that happened (or, for `warranty_until`, are scheduled). |

#### `Earnings`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"earnings"` (exactly) | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `creator_guard_amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `your_amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `status` | string or null | required | `expected` (fee set, before completion), `due`, `paid` or `void` (also for a lost, rejected or withdrawn lead without a booked commission); `null` (with every amount `null`) while no fee is set. |

#### `AccountPatch`

Send only what changes; the same fields and checks as the portal's profile page. Strings are trimmed first.

| Field | Type | Required | Description |
|---|---|---|---|
| `display_name` | string · 1–120 chars | optional | The name agencies and creators see. |
| `company_name` | string or null · 0–200 chars | optional | `null` or an empty string clears it. |
| `telegram_username` | string | optional | `name`, `@name` or a `t.me/name` link; stored as the name, 5–32 letters, digits or `_`. Cannot be removed. |
| `website` | string or null · 0–300 chars | optional | An `https://` (or `http://`) address with a dot in the host; without a scheme `https://` is added. `null` or an empty string clears it. |

#### `LogoUpload`

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | string (binary) | required | PNG, JPEG or WebP, at most 2 MB. |

#### `ExtractRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string · 20–20000 chars | required | Any text about her: profile, chat, notes (at least 20 characters after trimming). Not stored. |

#### `ExtractResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"extract_result"` (exactly) | required |  |
| `suggestions` | object | required | Only fields the text supports, each already valid under the rules of `POST /v1/leads`; review them before you send a lead. |

#### `PhotoUpload`

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | string (binary) | required | JPEG, PNG or WebP; at most 40 MB and 50 megapixels. Exactly one file part. |
| `kind` | string · one of `portrait`, `body`, `content_sample`, `non_nude`, `lingerie`, `professional` | optional | Default `portrait`. |
| `is_primary` | string · one of `true`, `false` | optional | `true` makes it her primary photo (default `false`). Her first photo is always primary. |

#### `PhotoPatch`

| Field | Type | Required | Description |
|---|---|---|---|
| `kind` | string · one of `portrait`, `body`, `content_sample`, `non_nude`, `lingerie`, `professional` | optional |  |
| `is_primary` | `true` (exactly) | optional | Makes this her primary photo. Only `true`: make another photo primary instead. |

#### `PhotoList`

Every photo of the lead (at most 20) on one page: `has_more` is always `false`.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `Photo` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `LeadSummary`

The short lead object of `?expand=lead`.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"lead"` (exactly) | required |  |
| `id` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `creator_name` | string | required |  |
| `creator_ref` | string or null · pattern `^CR-[0-9]+$` | required |  |
| `stage` | string | required |  |

#### `Commission`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"commission"` (exactly) | required |  |
| `id` | string · pattern `^com_[a-z2-7]{26}$` | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` or `LeadSummary` | required | The lead id (`lead_…`); with `?expand=lead` a short lead object (stays the id when you can no longer read the lead). |
| `creator_ref` | string or null · pattern `^CR-[0-9]+$` | required |  |
| `status` | string | required | `due` (we owe it), `paid` or `void`. New values may be added. |
| `fee_total` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `creator_guard_amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `your_amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `created_at` | string or null (date-time) | required |  |
| `paid_at` | string or null (date-time) | required |  |
| `version` | integer · ≥ 0 | required | Grows with every change; events about it carry the same number as `sequence`. |

#### `CommissionList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `Commission` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `PayoutDetails`

All three are `null` until you save payout details in the portal.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"payout_details"` (exactly) | required |  |
| `method` | string or null | required | `bank`, `paypal` or `crypto`. |
| `destination_masked` | string or null | required | The destination with all but a few characters hidden. |
| `updated_at` | string or null (date-time) | required |  |

#### `ApiKey`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"api_key"` (exactly) | required |  |
| `id` | string · pattern `^key_[a-z2-7]{26}$` | required |  |
| `mode` | string | required | `live` or `test`. |
| `label` | string or null | required |  |
| `prefix` | string | required | The start of the key, e.g. `cg_live_ab12`; enough to recognise it. |
| `scopes` | array of string | required |  |
| `ip_allowlist` | array of string | required | CIDR blocks; empty = any address. |
| `expires_at` | string or null (date-time) | required | Its expiry, capped by your key policy's maximum age. |
| `grace_until` | string or null (date-time) | required | Set on a key that was rolled: it works until then. |
| `last_used_at` | string or null (date-time) | required |  |
| `created_at` | string (date-time) | required |  |
| `created_via` | string | required | `admin`, `portal` or `api`. |
| `revoked_at` | string or null (date-time) | required |  |
| `rolled_from` | string or null | required | The key (`key_…`) this one replaced in a roll. |
| `secret` | string or null | optional | The full key. Only in the answer that made it (create, roll) — `null` in a replay of that answer; never again. |

#### `ApiKeyCreate`

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | string or null · 0–100 chars | optional | Trimmed; empty = no label. |
| `scopes` | array of `Scope` · at least 1 | required | Only scopes the calling key has (else `403 insufficient_scope`). |
| `ip_allowlist` | array of string · at most 20 | optional | CIDR blocks with the host bits zero, e.g. `203.0.113.0/24`; empty = any address. |
| `expires_at` | string or null (date-time) | optional | In the future; capped by your key policy's maximum age. |

#### `ApiKeyRoll`

| Field | Type | Required | Description |
|---|---|---|---|
| `grace_hours` | integer or null · 0–72 | optional | How long the old key keeps working (default 24; `0` = it stops now). |

#### `ApiKeyList`

The active keys and those revoked in the last 90 days, on one page.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `ApiKey` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `RequestLog`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"request_log"` (exactly) | required |  |
| `id` | string · pattern `^req_[a-z2-7]{26}$` | required | The request id (`X-Request-Id`). |
| `method` | string | required |  |
| `route` | string | required | Route template, e.g. `/v1/leads/{id}`. |
| `status` | integer | required |  |
| `error_code` | string or null | required |  |
| `key` | string or null | required | Key id (`key_…`). |
| `duration_ms` | integer | required |  |
| `created_at` | string (date-time) | required |  |

#### `RequestLogList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `RequestLog` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `Usage`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"usage"` (exactly) | required |  |
| `from` | string (date) | required |  |
| `to` | string (date) | required |  |
| `granularity` | string | required | `day`. |
| `mode` | string | required | `live` or `test` — the mode of the calling key. |
| `series` | array of object | required | One entry per UTC day of the range. |
| `by_route` | array of object | required |  |
| `by_key` | array of object | required |  |

#### `AuditEvent`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"audit_event"` (exactly) | required |  |
| `id` | string · pattern `^aud_[a-z2-7]{26}$` | required |  |
| `action` | string | required | e.g. `api_key.created`, `api_key.rolled`, `api_key.revoked`, `webhook_endpoint.created`, `account.updated`, `limits.changed`. New values may be added. |
| `actor` | object | required |  |
| `target` | object or null | required |  |
| `mode` | string or null | required | `live`, `test`, or `null` for account-wide changes. |
| `ip` | string or null | required |  |
| `user_agent` | string or null | required |  |
| `details` | object | required | What changed (names and new values; never secrets or creator data). |
| `created_at` | string (date-time) | required |  |

#### `AuditEventList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `AuditEvent` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `EventType`

The event types of the catalogue. New types may be added; `ping` is sent only by a test send and cannot be subscribed to.

Type: string · one of `lead.created`, `lead.updated`, `lead.stage_changed`, `lead.withdrawn`, `listing.approved`, `photo.added`, `photo.removed`, `consent.granted`, `consent.revoked`, `age_confirmation.confirmed`, `commission.created`, `commission.paid`, `commission.voided`, `agreement.published`, `api_key.expiring`, `webhook_endpoint.disabled`, `offer.created`, `offer.accepted`, `offer.declined`, `offer.expired`, `offer.retracted`, `offer.reopened`, `offer.progressed`, `offer.consent_revoked`, `reservation.created`, `reservation.paid`, `reservation.completed`, `reservation.refunded`, `reservation.cancelled`, `warranty_claim.created`, `data_export.ready`, `job.completed`, `deletion_request.completed`, `ping`.

#### `Event`

One change. `data.object` is the object as your account may see it when the event is read or delivered; its `object` tells which schema: [Lead](#schema-Lead), [Photo](#schema-Photo), [Confirmations](#schema-Confirmations), [Commission](#schema-Commission), [Agreement](#schema-Agreement), [ApiKey](#schema-ApiKey), [WebhookEndpoint](#schema-WebhookEndpoint), [Offer](#schema-Offer), [Reservation](#schema-Reservation), a reference [DataRequestRef](#schema-DataRequestRef) or [JobRef](#schema-JobRef) (creator-side events: never her data), or `{}` for `ping`. An object that no longer exists is `{"id": …, "object": …, "deleted": true}` (a removed photo: the photo as it was, `url` `null`). New types may be added.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required | `live` or `test`. |
| `api_version` | string | required | The contract version that rendered the payload. |
| `sequence` | integer | required | The `version` the object reached with this change. Drop an event whose `sequence` is not above the last one you applied for that object (`0` for `ping`). |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change: what changed, by contract field name (listing fields under `listing`, `consent` and `age_confirmation` as objects), each with `null` — the old value only for `stage` and `status`. Never creator data. |

#### `EventList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `Event` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `WebhookEndpoint`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"webhook_endpoint"` (exactly) | required |  |
| `id` | string · pattern `^we_[a-z2-7]{26}$` | required |  |
| `url` | string (uri) | required |  |
| `description` | string or null | required |  |
| `event_types` | array of string | required | The subscribed types, or `["*"]` for all. |
| `enabled` | boolean | required |  |
| `disabled_reason` | string or null | required | `manual` (you) or `failing` (72 hours of failed deliveries). |
| `created_at` | string (date-time) | required |  |
| `updated_at` | string (date-time) | required |  |
| `secret` | string or null | optional | `whsec_…` signing secret. Only in the answers to create and roll — `null` in a replay of that answer; never again. |

#### `WebhookEndpointCreate`

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string · 0–2048 chars · pattern `^https://` | required | https on port 443, no credentials, a host that resolves to public addresses only. |
| `event_types` | array of string · at least 1, at most 32 | required | `["*"]` for every type, or event types of [EventType](#schema-EventType) except `ping`. |
| `description` | string or null · 0–500 chars | optional |  |

#### `WebhookEndpointUpdate`

Send only what changes. Enabling an endpoint that was disabled as failing restarts its failure clock.

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string · 0–2048 chars · pattern `^https://` | optional |  |
| `event_types` | array of string · at least 1, at most 32 | optional |  |
| `description` | string or null · 0–500 chars | optional |  |
| `enabled` | boolean | optional |  |

#### `WebhookEndpointList`

Every endpoint of this mode (at most 10) on one page.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `WebhookEndpoint` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `WebhookReplay`

| Field | Type | Required | Description |
|---|---|---|---|
| `from` | string (date-time) | required | At most 30 days ago. |
| `to` | string or null (date-time) | optional | After `from`; default now. |

#### `ReplayResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"webhook_replay"` (exactly) | required |  |
| `endpoint` | string · pattern `^we_[a-z2-7]{26}$` | required |  |
| `from` | string (date-time) | required |  |
| `to` | string (date-time) | required |  |
| `queued` | integer | required | Deliveries queued (a range that would pass 1,000 open deliveries → `409 limit_reached`, nothing queued). |

#### `WebhookDelivery`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"webhook_delivery"` (exactly) | required |  |
| `id` | string · pattern `^whd_[a-z2-7]{26}$` | required |  |
| `event` | string | required | Event id (`evt_…`). |
| `event_type` | string | required |  |
| `status` | string | required | `pending`, `sending`, `succeeded` or `failed`. |
| `attempt` | integer | required |  |
| `next_attempt_at` | string or null (date-time) | required |  |
| `last_status` | integer or null | required | HTTP status your endpoint answered. |
| `last_error` | string or null | required | Why the last attempt failed (a short code, e.g. a timeout); `null` after a success. |
| `replay` | boolean | required |  |
| `created_at` | string (date-time) | required |  |
| `completed_at` | string or null (date-time) | required |  |
| `attempts` | array of object | required |  |

#### `WebhookDeliveryList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `WebhookDelivery` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `TestLeadReject`

| Field | Type | Required | Description |
|---|---|---|---|
| `outcome_reason` | string · one of `profile_mismatch`, `not_reachable`, `duplicate`, `quality`, `capacity`, `other` | required |  |

#### `TestReset`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"sandbox_reset"` (exactly) | required |  |
| `mode` | `"test"` (exactly) | required |  |
| `deleted` | object | required |  |

#### `LeadEvent`

An event whose `data.object` is a [Lead](#schema-Lead) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `PhotoEvent`

An event whose `data.object` is a [Photo](#schema-Photo); for `photo.removed` the photo as it was, with `url` `null`.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `ConfirmationsEvent`

An event whose `data.object` is a [Confirmations](#schema-Confirmations) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `CommissionEvent`

An event whose `data.object` is a [Commission](#schema-Commission) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `AgreementEvent`

An event whose `data.object` is an [Agreement](#schema-Agreement) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `ApiKeyEvent`

An event whose `data.object` is an [ApiKey](#schema-ApiKey) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `WebhookEndpointEvent`

An event whose `data.object` is a [WebhookEndpoint](#schema-WebhookEndpoint) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `PingEvent`

The event of a test send: `data.object` is empty, `sequence` is 0.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | `"ping"` (exactly) | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |

#### `UsdInput`

An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `<field>.currency`; `null` clears the value.

| Field | Type | Required | Description |
|---|---|---|---|
| `amount_minor` | integer · ≥ 0 | required |  |
| `currency` | `"USD"` (exactly) | required |  |

#### `Flex`

Where a creator may be near your criteria instead of matching exactly. A key that is present means "may deviate" (a creator just outside counts as a near match); a missing key means "must match". Levels are the presets of the portal: `age` 3, 8 or 20 (years outside your range), `revenue` `"zero"`, 50 or 100 (percent), `english` 3, 5 or `"any"`, `fee` 25, 50 or 100 (percent above your maximum fee), `split` 10, 20 or 30 (points above your maximum creator share), `stage` `"opposite"`. In the four list keys `also` holds other values that are fine; `[]` means anything else is close too.

| Field | Type | Required | Description |
|---|---|---|---|
| `age` | object | optional |  |
| `revenue` | object | optional |  |
| `english` | object | optional |  |
| `fee` | object | optional |  |
| `split` | object | optional |  |
| `stage` | object | optional |  |
| `niches` | object | optional |  |
| `platforms` | object | optional |  |
| `content_types` | object | optional |  |
| `languages` | object | optional |  |

#### `FlexInput`

The `flex` you send: only the preset levels (anything else is `400 invalid_field` with `field: "flex.<key>"`); values in `also` that repeat your primary selection are dropped. `null` = the portal default.

| Field | Type | Required | Description |
|---|---|---|---|
| `age` | object | optional |  |
| `revenue` | object | optional |  |
| `english` | object | optional |  |
| `fee` | object | optional |  |
| `split` | object | optional |  |
| `stage` | object | optional |  |
| `niches` | object | optional |  |
| `platforms` | object | optional |  |
| `content_types` | object | optional |  |
| `languages` | object | optional |  |

#### `SearchProfile`

What we match creators against before we offer them to you. Before your first `PUT` the defaults (`updated_at: null`).

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"search_profile"` (exactly) | required |  |
| `niches` | array of string | required |  |
| `platforms` | array of string | required |  |
| `languages` | array of string | required |  |
| `content_types` | array of string | required |  |
| `age_min` | integer or null | required |  |
| `age_max` | integer or null | required |  |
| `english_level_min` | integer or null | required |  |
| `revenue_min` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `revenue_max` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `max_placement_fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `creator_share_max_percent` | integer or null | required |  |
| `creator_stage` | string | required | `beginners`, `earning` or `both`. |
| `countries_excluded` | array of string | required |  |
| `capacity_per_month` | integer or null | required |  |
| `notes` | string or null | required |  |
| `flex` | `Flex` | required | Where a creator may be near your criteria instead of matching exactly. A key that is present means "may deviate" (a creator just outside counts as a near match); a missing key means "must match". Levels are the presets of the portal: `age` 3, 8 or 20 (years outside your range), `revenue` `"zero"`, 50 or 100 (percent), `english` 3, 5 or `"any"`, `fee` 25, 50 or 100 (percent above your maximum fee), `split` 10, 20 or 30 (points above your maximum creator share), `stage` `"opposite"`. In the four list keys `also` holds other values that are fine; `[]` means anything else is close too. |
| `updated_at` | string or null (date-time) | required |  |

#### `SearchProfilePut`

Full replacement: every field is optional, and a field you leave out goes back to its default (`[]`, `null`, `creator_stage: "both"`, the portal `flex`). Pick-list values are stored in the pick-list spelling. Money is US dollars only; `revenue_*` in whole dollars (`amount_minor` a multiple of 100).

| Field | Type | Required | Description |
|---|---|---|---|
| `niches` | array of string · at most 50, each ≤ 100 chars | optional |  |
| `platforms` | array of string · at most 50, each ≤ 100 chars | optional |  |
| `languages` | array of string · at most 50, each ≤ 100 chars | optional |  |
| `content_types` | array of string · at most 50, each ≤ 100 chars | optional |  |
| `age_min` | integer or null · 18–99 | optional |  |
| `age_max` | integer or null · 18–99 | optional | Not below `age_min`. |
| `english_level_min` | integer or null · 1–10 | optional |  |
| `revenue_min` | `UsdInput` | optional | An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `<field>.currency`; `null` clears the value. |
| `revenue_max` | `UsdInput` | optional | An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `<field>.currency`; `null` clears the value. |
| `max_placement_fee` | `UsdInput` | optional | An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `<field>.currency`; `null` clears the value. |
| `creator_share_max_percent` | integer or null · 0–100 | optional |  |
| `creator_stage` | string or null · one of `beginners`, `earning`, `both` | optional |  |
| `countries_excluded` | array of string · at most 50, each ≤ 100 chars | optional |  |
| `capacity_per_month` | integer or null · 0–1000 | optional |  |
| `notes` | string or null · 1–2000 chars | optional |  |
| `flex` | `FlexInput` | optional | The `flex` you send: only the preset levels (anything else is `400 invalid_field` with `field: "flex.<key>"`); values in `also` that repeat your primary selection are dropped. `null` = the portal default. |

#### `AgencyProfile`

Your agency's public facts. `tier` (`A`, `B`, `C` or `unranked`) and `verified_revenue` are set by Creator Guard.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"agency_profile"` (exactly) | required |  |
| `country` | string or null | required |  |
| `website` | string or null | required |  |
| `team_size` | integer or null | required |  |
| `years_active` | number or null | required |  |
| `monthly_revenue` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `managed_creators_count` | integer or null | required |  |
| `specialization` | array of string | required |  |
| `references` | string or null | required |  |
| `tier` | string | required |  |
| `verified_revenue` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `vetting` | `AgencyVetting` | required | Read-only, set by Creator Guard: where the 5-point vetting of your agency stands. Your agency receives offers with a creator's profile only once `status` is `vetted`; before that a creator who matches your search profile waits (`waiting_matches`) and her offer arrives when the vetting is done. The sandbox (test keys) always reports `vetted` with `waiting_matches: 0`. |
| `updated_at` | string or null (date-time) | required |  |

#### `AgencyVetting`

Read-only, set by Creator Guard: where the 5-point vetting of your agency stands. Your agency receives offers with a creator's profile only once `status` is `vetted`; before that a creator who matches your search profile waits (`waiting_matches`) and her offer arrives when the vetting is done. The sandbox (test keys) always reports `vetted` with `waiting_matches: 0`.

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | required | One of `registered`, `in_review`, `vetted`. `registered`: account ready, vetting not started; `in_review`: we are vetting your agency; `vetted`: offers reach your account. |
| `waiting_matches` | integer · ≥ 0 | required | Creators matched to your agency who wait for your vetting. A count only. |

#### `AgencyProfilePatch`

Only the fields you send change; `null` clears one (`specialization`: send `[]`). `tier`, `verified_revenue` and `vetting` cannot be sent (`400 unknown_field`).

| Field | Type | Required | Description |
|---|---|---|---|
| `country` | string or null · 1–100 chars | optional |  |
| `website` | string or null · 0–300 chars | optional | An `https://` URL. |
| `team_size` | integer or null · 0–100000 | optional |  |
| `years_active` | number or null · 0–99.9 | optional | At most one decimal, e.g. `3.5`. |
| `monthly_revenue` | `UsdInput` | optional | An amount in US dollars as integer cents: `{"amount_minor": 300000, "currency": "USD"}` = 3,000.00 USD. Another currency is `400 invalid_field` on `<field>.currency`; `null` clears the value. |
| `managed_creators_count` | integer or null · 0–100000 | optional |  |
| `specialization` | array of string · at most 20, each ≤ 100 chars | optional |  |
| `references` | string or null · 1–2000 chars | optional |  |

#### `OfferListing`

The creator's listing as agencies see it — the fields of [Listing](#schema-Listing) without its lead, status and the referrer's data. `placement_fee` is the price of this offer.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"listing"` (exactly) | required |  |
| `age` | integer or null | required |  |
| `gender` | string or null | required |  |
| `origin_country` | string or null | required |  |
| `languages` | array of string | required |  |
| `english_level` | integer or null | required |  |
| `content_types` | array of string | required |  |
| `content_freetext` | string or null | required |  |
| `has_of_account` | boolean or null | required |  |
| `of_verified` | boolean or null | required |  |
| `of_current_earnings` | integer or null | required |  |
| `content_ready` | boolean or null | required |  |
| `scripts_ready` | boolean or null | required |  |
| `account_access` | string or null | required |  |
| `device` | string or null | required |  |
| `social_status` | string or null | required |  |
| `social_preferences` | object | required |  |
| `tiktok_ok` | boolean or null | required |  |
| `blocked_countries` | array of string | required |  |
| `start_availability` | string or null | required |  |
| `start_date` | string or null (date) | required |  |
| `availability_hours_per_week` | number or null | required |  |
| `availability_hours_per_day` | number or null | required |  |
| `compensation_model` | string or null | required |  |
| `creator_share_percent` | integer or null | required |  |
| `fixed_salary` | integer or null | required |  |
| `salary_period` | string or null | required |  |
| `placement_fee` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `notes_public` | string or null | required |  |
| `updated_at` | string or null (date-time) | required |  |

#### `OfferNextActions`

What you can do with the offer now — so you never re-implement the rules.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_accept` | boolean | required |  |
| `can_decline` | boolean | required |  |
| `can_undo_accept` | boolean | required |  |
| `can_mark_contacted` | boolean | required |  |
| `can_mark_in_talks` | boolean | required |  |
| `can_mark_signed` | boolean | required |  |
| `can_mark_lost` | boolean | required |  |

#### `ReservationSummary`

The reservation your accept created; the whole object: `GET /v1/reservations/{id}`.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string · pattern `^res_[a-z2-7]{26}$` | required |  |
| `status` | string | required | `awaiting_payment`, `paid`, `completed`, `refunded` or `cancelled`. |
| `amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `payment_reference` | string or null | required |  |
| `payment_due_at` | string or null (date-time) | required |  |
| `paid_at` | string or null (date-time) | required |  |
| `warranty_until` | string or null (date-time) | required |  |

#### `Offer`

A creator we offered to your agency. Never her contact details, the referrer or internal notes — the contact comes with `GET /v1/reservations/{id}/creator` after payment. Her name too only after payment; until then she is her creator number (`creator_ref`). New fields may be added within v1.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"offer"` (exactly) | required |  |
| `id` | string · pattern `^offer_[a-z2-7]{26}$` | required |  |
| `status` | string | required | `offered`, `accepted`, `declined`, `expired`, `retracted`, `contacted`, `in_talks`, `signed` or `lost`. An open offer whose deadline passed reads `expired` at once. |
| `creator_name` | string or null | required | `null` until your agency paid for her (a reservation of yours for her that is `paid` or `completed`; a refunded one does not count). Use `creator_ref` before that. |
| `creator_ref` | string or null | required | Her creator number, e.g. `CR-1047`. |
| `expires_at` | string or null (date-time) | required | The deadline to accept or decline. |
| `accepted_at` | string or null (date-time) | required |  |
| `undo_until` | string or null (date-time) | required | Until when `undo-accept` works (while unpaid). |
| `agency_note` | string or null | required |  |
| `outcome_reason` | string or null | required | Set on `lost`: `profile_mismatch`, `not_reachable`, `duplicate`, `quality`, `capacity` or `other`. |
| `listing` | `OfferListing` or null | required | `null` once the offer is declined, expired, retracted or lost without a paid reservation, and while she has withdrawn her consent (event `offer.consent_revoked`) — unless your placement of her is completed. |
| `photo_count` | integer or null | required | Photos she agreed to share; `null` while the listing is hidden. |
| `reservation` | `ReservationSummary` or null | required |  |
| `next_actions` | `OfferNextActions` | required | What you can do with the offer now — so you never re-implement the rules. |
| `match` | `OfferMatch` or null | required | How well she fits your search profile (`GET /v1/search-profile`), checked with the same rules as our own matching. `null` while you have no search profile (or nothing filled in) and while her listing is hidden. Criterion names and results only: `niche` and `platforms` are only ever `hit` or `miss` (a close match within your tolerance shows as `hit`, while `score` still counts it ½). |
| `created_at` | string (date-time) | required |  |
| `updated_at` | string (date-time) | required |  |

#### `OfferList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `Offer` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `OfferMatch`

The match of an offer against your search profile. Criteria you left empty are not checked.

| Field | Type | Required | Description |
|---|---|---|---|
| `score` | number · ≥ 0 | required | Criteria met; a close match (within the tolerance you allowed, or a value she has not filled in yet) counts ½. Sort by score / total, knocked-out offers last. |
| `total` | integer · ≥ 1 | required | Criteria checked. |
| `knocked_out` | boolean | required | `true` when a must-match criterion (one without tolerance; the country always) is a miss. |
| `criteria` | array of `OfferMatchCriterion` | required |  |

#### `OfferMatchCriterion`

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | string | required | `content_types`, `niche`, `languages`, `platforms`, `age`, `english`, `revenue`, `fee`, `split`, `stage` or `country`. New keys may be added within v1. |
| `result` | string | required | `hit`, `near` (counts ½) or `miss`; `niche` and `platforms` are only `hit` or `miss`. New values may be added within v1. |
| `must` | boolean | required | Must match: a miss knocks her out. |

#### `OfferPhoto`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"photo"` (exactly) | required |  |
| `id` | string · pattern `^photo_[a-z2-7]{26}$` | required |  |
| `kind` | string | required |  |
| `is_primary` | boolean | required |  |
| `url` | string or null | required | Signed link, valid for one hour. |
| `url_expires_at` | string or null (date-time) | required |  |

#### `OfferPhotoList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `OfferPhoto` | required |  |
| `has_more` | boolean | required | Always `false`: every photo on one page. |
| `next_cursor` | string or null | required |  |

#### `OfferPatch`

| Field | Type | Required | Description |
|---|---|---|---|
| `agency_note` | string or null · 1–500 chars | required | Your note (trimmed); `null` clears it. |

#### `OfferDecline`

| Field | Type | Required | Description |
|---|---|---|---|
| `note` | string · 50–500 chars | required | Why she is not a fit, 50–500 characters after trimming. |

#### `OfferMarkLost`

| Field | Type | Required | Description |
|---|---|---|---|
| `outcome_reason` | string · one of `profile_mismatch`, `not_reachable`, `duplicate`, `quality`, `capacity`, `other` | required |  |

#### `WarrantyClaim`

| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | string | required |  |
| `note` | string or null | required |  |
| `filed_at` | string or null (date-time) | required |  |

#### `ReservationNextActions`

| Field | Type | Required | Description |
|---|---|---|---|
| `can_file_warranty_claim` | boolean | required |  |
| `can_view_creator` | boolean | required |  |

#### `Reservation`

What your accept reserved: the fee to transfer, its payment reference and due date, then payment, warranty and your warranty claim. New fields may be added within v1.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"reservation"` (exactly) | required |  |
| `id` | string · pattern `^res_[a-z2-7]{26}$` | required |  |
| `offer` | string or null | required | The offer (`offer_…`). |
| `status` | string | required | `awaiting_payment`, `paid` (her contact is unlocked, the warranty runs), `completed`, `refunded` or `cancelled`. |
| `creator_name` | string or null | required | `null` until your agency paid for her (`paid` or `completed`; also `null` again after a refund). |
| `creator_ref` | string or null | required |  |
| `amount` | `Money` | required | An amount in integer minor units (cents) and its ISO 4217 currency; `null` when not set. |
| `payment_reference` | string | required | Put it on your bank transfer. |
| `payment_due_at` | string or null (date-time) | required |  |
| `paid_at` | string or null (date-time) | required |  |
| `warranty_until` | string or null (date-time) | required |  |
| `completed_at` | string or null (date-time) | required |  |
| `refunded_at` | string or null (date-time) | required |  |
| `warranty_claim` | `WarrantyClaim` or null | required |  |
| `next_actions` | `ReservationNextActions` | required |  |
| `created_at` | string or null (date-time) | required |  |
| `updated_at` | string or null (date-time) | required |  |

#### `ReservationList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `Reservation` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `ReservationCreator`

Her contact, after payment only. Never the referrer, internal notes or her consent records.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"reservation_creator"` (exactly) | required |  |
| `reservation` | string · pattern `^res_[a-z2-7]{26}$` | required |  |
| `creator_name` | string | required |  |
| `creator_ref` | string or null | required |  |
| `instagram_handle` | string or null | required |  |
| `other_contact` | string or null | required |  |
| `platforms` | array of string | required |  |
| `follower_count` | integer or null | required |  |
| `niche` | string or null | required |  |

#### `WarrantyClaimCreate`

| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | string · one of `creator_unreachable`, `no_show`, `false_data`, `contract_refused`, `other` | required |  |
| `note` | string or null · 0–2000 chars | optional | Trimmed; blank counts as no note. |

#### `TestOfferCreate`

Every field is optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `creator_name` | string · 1–120 chars | optional | Default: a generated test name. The offer shows it only after `…/mark-paid`, like a live offer. |
| `placement_fee` | `MoneyInput` | optional | `{"amount_minor": 150000, "currency": "USD"}` = 1,500.00 USD. `null` clears the fee. |
| `expires_in_hours` | integer · 1–720 | optional | Default: the offer deadline of `GET /v1/settings`. |

#### `TestReservationRefund`

| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | string · one of `creator_unreachable`, `no_show`, `false_data`, `contract_refused`, `other` | optional | Default: the reason of your warranty claim, else `other`. |

#### `ClockAdvance`

| Field | Type | Required | Description |
|---|---|---|---|
| `hours` | integer · 1–720 | required |  |

#### `ClockAdvanceResult`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"clock_advance"` (exactly) | required |  |
| `hours` | integer | required |  |
| `expired_offers` | integer | required |  |
| `cancelled_reservations` | integer | required |  |
| `completed_reservations` | integer | required |  |

#### `OfferEvent`

An event whose `data.object` is an [Offer](#schema-Offer) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `ReservationEvent`

An event whose `data.object` is a [Reservation](#schema-Reservation) — or `{"id": …, "object": …, "deleted": true}` when it no longer exists.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |
| `previous_attributes` | object | optional | Only on events about a change; see [Event](#schema-Event). |

#### `CreatorScope`

What a creator lets an OAuth app do for her (request values; new scopes may be added). An app asks for a subset of its registered scopes.

Type: string · one of `creator.profile:read`, `creator.profile:write`, `creator.photos:write`, `creator.consent:write`, `creator.support`, `creator.privacy`.

#### `OAuthApp`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"oauth_app"` (exactly) | required |  |
| `id` | string · pattern `^app_[a-z2-7]{26}$` | required |  |
| `mode` | string | required | `live` or `test` (the mode of the key that registered it). |
| `client_id` | string · pattern `^cgcl_(live\|test)_[0-9a-f]{32}$` | required | Public; sent to `/oauth/authorize` and `/oauth/token`. |
| `name` | string | required | Shown to the creator on the consent screen. |
| `logo_url` | string or null (uri) | required |  |
| `privacy_url` | string (uri) | required |  |
| `redirect_uris` | array of string | required | Matched exactly, character for character. Empty only while the app is disabled. |
| `scopes` | array of string | required | Creator scopes ([CreatorScope](#schema-CreatorScope)). |
| `confidential` | boolean | required | `true`: a server-side app with a client secret; `false`: a public client (PKCE only). |
| `secret_prefix` | string or null | required | The start of the current client secret, e.g. `cgcs_live_Ab3x`; `null` for a public client. |
| `enabled` | boolean | required | `false` while the app is disabled: unknown to `/oauth/authorize`, and `/oauth/token` answers `unauthorized_client` (existing grants are kept). Send `redirect_uris` in `PATCH /v1/oauth-apps/{id}` to enable it again. |
| `disabled_reason` | string or null | required | `member_offboarded`: removing a member (or lowering her role below admin) removed every redirect URI that one of her keys had added, and none was left. `null` while enabled. |
| `created_at` | string (date-time) | required |  |
| `updated_at` | string (date-time) | required |  |
| `client_secret` | string or null | optional | `cgcs_live_…` / `cgcs_test_…`. Only in the answers to create and roll (`null` for a public client, and in a replay of that answer); never again. |

#### `OAuthAppCreate`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string · 3–60 chars | required | Trimmed. |
| `redirect_uris` | array of string · at least 1, at most 10, each ≤ 2000 chars | required | Distinct; https, no fragment, no user info, no wildcard, no private or loopback host. Test keys may also use `http://localhost:<port>` or `http://127.0.0.1:<port>`. |
| `logo_url` | string or null · 0–2000 chars · pattern `^https://` | optional |  |
| `privacy_url` | string · 0–2000 chars · pattern `^https://` | required | Your privacy policy, linked on the consent screen. |
| `scopes` | array of `CreatorScope` · at least 1 | required | Distinct. |
| `confidential` | boolean | required |  |

#### `OAuthAppUpdate`

Send only what changes. `logo_url: null` removes the logo.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string · 3–60 chars | optional |  |
| `redirect_uris` | array of string · at least 1, at most 10, each ≤ 2000 chars | optional |  |
| `logo_url` | string or null · 0–2000 chars · pattern `^https://` | optional |  |
| `privacy_url` | string · 0–2000 chars · pattern `^https://` | optional |  |
| `scopes` | array of `CreatorScope` · at least 1 | optional |  |
| `confidential` | boolean | optional | Only its current value; it cannot change. |

#### `OAuthAppList`

Every OAuth app of this mode (at most 10) on one page.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `OAuthApp` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `OAuthTestCodeCreate`

| Field | Type | Required | Description |
|---|---|---|---|
| `client_id` | string · pattern `^cgcl_test_[0-9a-f]{32}$` | required | A test-mode app of your account. |
| `lead_id` | string · pattern `^lead_[a-z2-7]{26}$` | required | A sandbox lead you may connect (you submitted it, or you hold a paid reservation for it). |
| `redirect_uri` | string · 0–2000 chars | required | One of the app's registered redirect URIs, character for character. |
| `scopes` | array of `CreatorScope` · at least 1 | required | A subset of the app's scopes; repeats are ignored. |
| `code_challenge` | string · pattern `^[A-Za-z0-9_-]{43}$` | required | BASE64URL(SHA256(code_verifier)) without padding (PKCE S256). |

#### `OAuthTestCode`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"oauth_test_code"` (exactly) | required |  |
| `code` | string · pattern `^cgac_[A-Za-z0-9]{43}$` | required | The authorization code; exchange it at `/oauth/token` with `grant_type=authorization_code`. |
| `expires_in` | `60` (exactly) | required | Seconds. |

#### `Creator`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"creator"` (exactly) | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required | Her lead. |
| `creator_name` | string | required |  |
| `stage` | string | required | Same stages as `lead.stage`. |
| `next_actions` | object | required |  |
| `placement` | object or null | required | The agency she was placed with, once it paid; `null` before. |
| `updated_at` | string or null (date-time) | required |  |

#### `CreatorProfile`

Her contact fields and the listing fields she edits herself. Never fees, deal terms or `of_verified`.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"creator_profile"` (exactly) | required |  |
| `lead` | object | required |  |
| `listing` | object | required |  |
| `can_edit_lead` | boolean | required | Contact fields can change while the lead is `submitted` (else `409 lead_locked`). |
| `can_edit_listing` | boolean | required | Listing fields can change until the listing is live (else `409 listing_locked`). |
| `updated_at` | string or null (date-time) | required |  |

#### `CreatorProfilePatch`

Send only what changes; `null` clears a value. Any other field (fees, deal terms, `of_verified`, partner fields) is `400 unknown_field`.

| Field | Type | Required | Description |
|---|---|---|---|
| `lead` | object | optional |  |
| `listing` | object | optional |  |

#### `CreatorPhoto`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"photo"` (exactly) | required |  |
| `id` | string · pattern `^photo_[a-z2-7]{26}$` | required |  |
| `lead` | string · pattern `^lead_[a-z2-7]{26}$` | required |  |
| `kind` | string | required |  |
| `is_primary` | boolean | required |  |
| `consent_status` | string | required |  |
| `url` | string or null (uri) | required | Signed, valid for 1 hour; `null` when it could not be signed and in the replay of an upload. |
| `url_expires_at` | string or null (date-time) | required |  |
| `created_at` | string or null (date-time) | required |  |

#### `CreatorPhotoList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `CreatorPhoto` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `CreatorConsentEvent`

One entry of her consent ledger. Never carries her IP address or browser.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"consent_event"` (exactly) | required |  |
| `id` | string · pattern `^cev_[a-z2-7]{26}$` | required |  |
| `kind` | string | required | `consent_granted`, `consent_revoked`, `age_confirmed` or `creator_terms_accepted`. |
| `text_kind` | string | required |  |
| `text_version` | integer | required |  |
| `channel` | string or null | required | Where she decided: `hosted_link`, `hosted_portal`, `admin`, `legacy` or `oauth_app:app_…` (the app that sent it). |
| `created_at` | string (date-time) | required |  |

#### `CreatorConsentState`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"consent_state"` (exactly) | required |  |
| `consent` | object | required |  |
| `age_confirmation` | object | required |  |
| `events` | array of `CreatorConsentEvent` | required | Oldest first. |

#### `ConsentText`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"consent_text"` (exactly) | required |  |
| `kind` | string | required |  |
| `version` | integer | required | Send it as `text_version` (creator terms: `version`) with her decision. |
| `locale` | string | required |  |
| `body_md` | string | required | Markdown. Show it to her in full before she decides. |
| `sha256` | string | required |  |
| `published_at` | string or null (date-time) | required |  |

#### `ConsentDecision`

The text version she was shown. Required for a grant and the 18+ confirmation (`409 consent_text_outdated` with `current_version` when it is not the current one); optional for a withdrawal, which is never refused because of the text.

| Field | Type | Required | Description |
|---|---|---|---|
| `text_version` | integer · ≥ 1 | optional |  |
| `locale` | string · pattern `^[a-z]{2}$` | optional | The language of the text she saw, default `en`. |

#### `CreatorAgreement`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"creator_agreement"` (exactly) | required |  |
| `type` | string | required |  |
| `current_version` | integer or null | required |  |
| `accepted_version` | integer or null | required |  |
| `accepted_at` | string or null (date-time) | required |  |

#### `CreatorAgreementList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `CreatorAgreement` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `CreatorTermsAccept`

| Field | Type | Required | Description |
|---|---|---|---|
| `version` | integer · ≥ 1 | required | The current version (`409 consent_text_outdated` otherwise). |

#### `SupportTicket`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"support_ticket"` (exactly) | required |  |
| `id` | string · pattern `^tkt_[a-z2-7]{26}$` | required |  |
| `subject` | string | required |  |
| `status` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `updated_at` | string (date-time) | required |  |
| `last_message_at` | string or null (date-time) | required |  |

#### `SupportTicketList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `SupportTicket` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `SupportTicketCreate`

| Field | Type | Required | Description |
|---|---|---|---|
| `subject` | string · 3–200 chars | required | Trimmed. |
| `body` | string · 1–5000 chars | required | Her first message; trimmed. |

#### `SupportMessage`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"support_message"` (exactly) | required |  |
| `id` | string · pattern `^msg_[a-z2-7]{26}$` | required |  |
| `ticket` | string · pattern `^tkt_[a-z2-7]{26}$` | required |  |
| `body` | string | required |  |
| `from_staff` | boolean | required |  |
| `created_at` | string (date-time) | required |  |

#### `SupportMessageList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `SupportMessage` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `SupportReply`

| Field | Type | Required | Description |
|---|---|---|---|
| `body` | string · 1–5000 chars | required | Trimmed. |

#### `Job`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"job"` (exactly) | required |  |
| `id` | string · pattern `^job_[a-z2-7]{26}$` | required |  |
| `type` | string | required | `data_export`. |
| `status` | string | required | `queued`, `running`, `succeeded` or `failed`. |
| `progress` | integer or null · 0–100 | required |  |
| `result` | object or null | required | After success: the data request that holds the download. |
| `error_code` | string or null | required | Why it failed, e.g. `timeout`, `upload_failed`, `lead_anonymized`. Request a new export. |
| `created_at` | string (date-time) | required |  |
| `finished_at` | string or null (date-time) | required |  |

#### `DataRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"data_request"` (exactly) | required |  |
| `id` | string · pattern `^dreq_[a-z2-7]{26}$` | required |  |
| `kind` | string | required | `export` or `deletion`. |
| `status` | string | required | `open`, `ready` (export to download), `completed`, `rejected`, `failed` or `expired`. |
| `job` | string or null | required | The export job (`job_…`); `null` for a deletion request. |
| `expires_at` | string or null (date-time) | required | Until when the export can be downloaded (7 days after it was ready). |
| `created_at` | string (date-time) | required |  |
| `completed_at` | string or null (date-time) | required |  |
| `download_url` | string or null (uri) | optional | Only on `GET /v1/creator/data-export/{id}`: a JSON file, signed until `download_url_expires_at` (1 hour at most, never past `expires_at`; each call signs a new link); `null` unless `status` is `ready`. |
| `download_url_expires_at` | string or null (date-time) | optional |  |

#### `ConnectedApp`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"connected_app"` (exactly) | required |  |
| `id` | string · pattern `^app_[a-z2-7]{26}$` | required |  |
| `name` | string | required |  |
| `logo_url` | string or null (uri) | required |  |
| `privacy_url` | string (uri) | required |  |
| `owner_name` | string | required | The partner or agency behind the app. |
| `scopes` | array of string | required |  |
| `connected_at` | string or null (date-time) | required |  |
| `last_used_at` | string or null (date-time) | required |  |

#### `ConnectedAppList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `ConnectedApp` | required |  |
| `has_more` | boolean | required |  |
| `next_cursor` | string or null | required |  |

#### `DataRequestRef`

A reference to a creator's data request (export or deletion) — never her data, IP or browser. Read it with her access token: `GET /v1/creator/data-export/{id}` for an export. `deleted: true` when it is no longer visible to your account.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string · pattern `^dreq_[a-z2-7]{26}$` | required |  |
| `object` | `"data_request"` (exactly) | required |  |
| `deleted` | `true` (exactly) | optional | Only when the request no longer exists for your account. |

#### `JobRef`

A reference to an asynchronous job. Read its status and result with the creator's access token: `GET /v1/jobs/{id}`. `deleted: true` when it is no longer visible to your account.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string · pattern `^job_[a-z2-7]{26}$` | required |  |
| `object` | `"job"` (exactly) | required |  |
| `deleted` | `true` (exactly) | optional | Only when the job no longer exists for your account. |

#### `DataRequestEvent`

An event whose `data.object` is a [DataRequestRef](#schema-DataRequestRef): `{"id": "dreq_…", "object": "data_request"}`.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |

#### `JobEvent`

An event whose `data.object` is a [JobRef](#schema-JobRef): `{"id": "job_…", "object": "job"}`.

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"event"` (exactly) | required |  |
| `id` | string · pattern `^evt_[a-z2-7]{26}$` | required |  |
| `type` | string | required |  |
| `created_at` | string (date-time) | required |  |
| `mode` | string | required |  |
| `api_version` | string | required |  |
| `sequence` | integer | required |  |
| `data` | object | required |  |

#### `Member`

A person who can sign in to the account (`status` `active`) or an open invitation (`invited`).

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"member"` (exactly) | required |  |
| `id` | string | required | `mem_…` for a person, `inv_…` for an invitation. Use it with `DELETE /v1/members/{id}`. |
| `email` | string | required | Lower-case email address of the login or the invitation. |
| `role` | string | required | `owner`, `admin`, `developer` or `viewer` — https://docs.creator-guard.com/members/ |
| `status` | string | required | `active` or `invited`. New values may be added. |
| `email_verified` | boolean or null | required | People: `false` when the login was created on the join page — whoever opened the link set its password, nobody proved the address; `true` otherwise. `null` for invitations. |
| `created_at` | string (date-time) | required | When the person joined or the invitation was created. |
| `expires_at` | string or null (date-time) | required | Invitations: when the link stops working (48 hours). `null` for people. |
| `join_url` | string or null (uri) | required | Only in the first answer to `POST /v1/members`: the one-time link for the person. `null` everywhere else, also in an `Idempotency-Key` replay. |

#### `MemberInvite`

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string · 3–254 chars | required | The address the person signs in with; compared without case and surrounding whitespace. |
| `role` | string · one of `developer`, `viewer` | required | Admins are invited in the portal only (by an owner or admin with two-factor authentication). The owner is the login the account was created with and is never invited. |

#### `MemberList`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` (exactly) | required |  |
| `data` | array of `Member` | required |  |
| `has_more` | boolean | required | Always `false`: the list is not paginated. |
| `next_cursor` | string or null | required |  |

#### `MemberDeleted`

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | `"member"` (exactly) | required |  |
| `id` | string | required |  |
| `deleted` | `true` (exactly) | required |  |

#### `ErrorResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | required |  |

`error` object:

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | required | `invalid_request`, `authentication`, `permission`, `rate_limit` or `api_error`. |
| `code` | `ErrorCode` | required | Stable, machine-readable error code. Branch on this, not on `message`. New codes may be added within v1. |
| `message` | string | required | For a developer reading a log; may change. Never branch on it. |
| `doc_url` | string (uri) | required | https://docs.creator-guard.com/errors/#<code> |
| `request_id` | string | required | Same as `X-Request-Id`. |
| `field` | string | optional | The request field the error is about (first one when there are several). |
| `details` | array of object | optional | Every field problem of the request, not just the first. |
| `lead` | object or null | optional | With `duplicate_own_lead`: your existing lead. |
| `parameter` | string | optional | With `unknown_parameter` and `invalid_cursor`: the query parameter. |
| `agreement_type` | string | optional | With `terms_not_accepted`. |
| `scope` | string | optional | With `insufficient_scope`: the scope the key lacks. |
| `blockers` | array of string | optional | With `not_ready_for_review`. |
| `current_state` | string | optional | With `invalid_state`: the state that blocks the call. |
| `current_version` | integer | optional | With `invalid_state` on agreement accept: the version to accept. |
| `limit` | integer | optional | With `limit_reached`: the limit that is reached. |

#### `Scope`

Scopes a key can carry. Each operation names the one it needs. Scopes of later endpoints are added with them.

`account:read`, `account:write`, `agreements:write`, `keys:manage`, `webhooks:manage`, `leads:read`, `leads:write`, `photos:write`, `earnings:read`, `offers:read`, `offers:write`, `reservations:read`, `reservations:write`, `search_profile:write`, `extract`, `usage:read`, `audit:read`, `oauth_apps:manage`, `members:manage`
