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

# API contract

> Resource IDs, object shapes, metadata, metrics, and extensible values.

## Public IDs

Every public resource uses a prefixed ID.

| Prefix  | Resource          |
| ------- | ----------------- |
| `acct_` | Connected account |
| `sub_`  | Tracked media     |
| `prj_`  | Project           |
| `cl_`   | Connect link      |
| `whk_`  | Webhook endpoint  |
| `evt_`  | Webhook event     |

Store these IDs as opaque strings. Database IDs do not appear in `/v1`.

## Values that can grow

Clients must accept unknown values for these fields:

* `platform`
* `media_type`
* reason fields
* connect link `status`
* create item `status`
* account `capabilities`
* webhook `type`

The documentation lists known values, not complete enums. Instagram is the
only accepted platform for new connect links today.

These lifecycle fields are closed enums:

* submission `status`
* account `connection.status`
* account `tracking.status`
* audience and demographics `availability`

## Metadata

Accounts, projects, and tracked media have a flat `metadata` object. It accepts
up to 50 keys. Keys contain 1 to 40 characters. Values contain up to 500
characters.

Set account metadata in `POST /connect-links`. Set tracked media metadata on
each item in `POST /submissions`. Update any resource with its `PATCH` operation.
Reconnects merge connect-link metadata into the account.

A patch merges keys. Set one value to `null` to remove that key. Set
`metadata` to `null` to clear all keys.

An `already_tracked` create result does not change metadata. Full resource
objects and webhook payloads include metadata. A submission's nested `account`
summary does not include it.

Do not store passwords, API keys, or other secrets in metadata.

## Shared metrics

`latest` contains `captured_at`, `views`, `reach`, `likes`, `comments`,
`shares`, `saves`, `total_interactions`, and `extra`.

Each platform maps its headline view number to `views`. A metric value of
`null` means the platform did not report that metric. A `captured_at` value of
`null` means ClipStake has not read the media yet.

`extra` contains platform-specific numeric metrics. Its keys use snake case.
Clients must accept new keys.