Concepts
Objects and schemas
The objects every endpoint shares, one JSON Schema each, and the rule that an unreported count is null.
- Same shape everywhere
- A Video, Creator or Ad has one shape on every platform and every endpoint.
- Metrics
engagementon Videos and comments,statson Creators. Null means not reported, never 0.- Schemas
- One JSON Schema per object under
https://www.shortsintel.com/docs/schemas/.
Every endpoint returns the same few objects. A Video read from TikTok has the same fields as one from YouTube, and a search result carries the same Video fields as a lookup. Each object has a JSON Schema you can validate against or generate types from.
The objects
| Object | JSON Schema | Where it appears |
|---|---|---|
| Video | video.json | Every read that returns a video, on every platform. |
| Creator | creator.json | A creator lookup. Counts are under stats. |
| Comment | comment.json | One item of a comments or replies page. |
| Ad | ad.json | One Ad from an ad library. |
| Advertiser | advertiser.json | An advertiser lookup (Meta shape). |
| Hashtag | hashtag.json | A hashtag lookup. |
| Sound | sound.json | A sound lookup. |
| Keyword | keyword.json | A keyword lookup. |
Each schema is generated from the same source as the API reference and its OpenAPI document, so the two cannot disagree. Shared parts, such as the Video inside a Hashtag, sit under $defs.
When to use the schemas
Use a schema to validate a response in a test, to generate a type for one object, or to hand an Assistant the exact shape it will read. For whole operations, with requests and errors, use the OpenAPI document.
How unknown values work
A count the platform did not report is null, never 0. On a platform that shows no saves, engagement.saves is null. A hidden follower count is a null stats.followers. Treat 0 as a real zero and null as unknown.
engagement is the Video’s latest Snapshot, the same numbers its Snapshots history shows last. It is null when the Video has no Snapshot yet.
Limits: deprecated fields
The old metric fields are still returned with the same values and types. They are marked deprecated in the OpenAPI document, so a generated client warns on them. Read the new names in new code.
| Deprecated | Use | Object |
|---|---|---|
snapshot | engagement | Video |
like_count | engagement.likes | Comment |
reply_count | engagement.replies | Comment |
follower_count | stats.followers | Creator |
following_count | stats.following | Creator |
video_count | stats.videos | Creator |
total_likes | stats.likes | Creator |
total_views | stats.views | Creator |
Example: one Video
A Video’s engagement when the platform reported no saves:
"engagement": {
"views": 48210,
"likes": 1903,
"comments": 88,
"shares": 41,
"saves": null,
"at": "2026-11-13T09:00:00.000Z"
}Questions about objects and schemas
Is a Video the same on every platform?
Yes. A field a platform does not have is null, not absent.
Will the deprecated fields be removed?
Not in /v1. They stay with their current values and types.
Can the schemas and the API disagree?
No. Both are generated from the same source, and a test checks that each schema matches its OpenAPI component.