# Objects and schemas

> For the complete documentation index, see [llms.txt](https://www.shortsintel.com/llms.txt). Every docs page is also available as markdown: add .md to its URL. To connect, read [agents.md](https://www.shortsintel.com/agents.md).

> 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: `engagement` on Videos and comments, `stats` on 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`](https://www.shortsintel.com/docs/schemas/video.json) | Every read that returns a video, on every platform. |
| Creator | [`creator.json`](https://www.shortsintel.com/docs/schemas/creator.json) | A creator lookup. Counts are under `stats`. |
| Comment | [`comment.json`](https://www.shortsintel.com/docs/schemas/comment.json) | One item of a comments or replies page. |
| Ad | [`ad.json`](https://www.shortsintel.com/docs/schemas/ad.json) | One Ad from an ad library. |
| Advertiser | [`advertiser.json`](https://www.shortsintel.com/docs/schemas/advertiser.json) | An advertiser lookup (Meta shape). |
| Hashtag | [`hashtag.json`](https://www.shortsintel.com/docs/schemas/hashtag.json) | A hashtag lookup. |
| Sound | [`sound.json`](https://www.shortsintel.com/docs/schemas/sound.json) | A sound lookup. |
| Keyword | [`keyword.json`](https://www.shortsintel.com/docs/schemas/keyword.json) | A keyword lookup. |

Each schema is generated from the same source as the [API reference](https://www.shortsintel.com/docs/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:

```json
"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.