Skip to main content

​
Paths

Each platform has its own paths. The platform comes after the version: Projects hold tracked media from all platforms, so their path has no platform. An ID only works under the path of its own platform. An acct_, sub_, or cl_ ID from a different platform returns 404.

​
Public IDs

Every public resource uses a prefixed ID. 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
  • bot score signal metric
The documentation lists known values, not complete enums. For example, platform is instagram, x or youtube today. More platforms can come later. These lifecycle fields are closed enums:
  • submission status
  • account connection.status
  • account tracking.status
  • audience and demographics availability
  • bot score signal band

​
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 /{platform}/connect-links. Set tracked media metadata on each item in POST /{platform}/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 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. See Metrics on X and Metrics on YouTube for those mappings. 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.