# Media list schema (/docs/schema/media-list)



{/*
  AUTO-GENERATED. Do not hand-edit.
  Source: packages/social-api/src/docs/generate-schema-pages.ts
  Regenerate with: pnpm -F @repo/social-api generate:docs
  Field tables derive from the canonical Zod schemas (packages/social-api/src/schemas/canonical.ts);
  availability + equivalence derive from the registry fieldMaps.
  */}

Media list schema [#media-list-schema]

Every SocialCrawl endpoint that returns a media-file list gives you this exact shape, whatever the source platform. Write your parser once and the same code reads media list data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.

Field reference [#field-reference]

| Field         | Type       | Nullable | Description                                                                                                                                                                                                                                                                                                                       |
| ------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items`       | `object[]` | No       | Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type — this is a passthrough list, not a canonical object. |
| `next_cursor` | `string`   | Yes      | Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results.                                                                                                                                                                     |
| `total`       | `integer`  | Yes      | Total number of matching results, when the upstream provides a count. Omitted otherwise.                                                                                                                                                                                                                                          |

Platform availability [#platform-availability]

1 platform returns the `Media list` shape across 4 endpoints. This is a **passthrough** shape: the outer contract above is guaranteed on every platform, and each platform's own extra fields are preserved untouched rather than remapped, so there is no per-field availability matrix.

<div className="overflow-x-auto">
  | Platform | Endpoints                                                                                                           |
  | -------- | ------------------------------------------------------------------------------------------------------------------- |
  | YouTube  | `/v1/youtube/video/audio`, `/v1/youtube/video/files`, `/v1/youtube/video/subtitles`, `/v1/youtube/video/thumbnails` |
</div>

Machine-readable schema [#machine-readable-schema]

Validate responses programmatically against the JSON Schema (2020-12):

[`/schemas/media-list.json`](/schemas/media-list.json)

Point a validator (Ajv, `jsonschema`, or your framework's) at that URL, or hand it to an agent so it can check the shape without a live call.

Returned by [#returned-by]

Endpoints with the `MediaList` archetype return this shape:

[YouTube](/platforms/youtube)

See how the same fields map to each platform's raw upstream names in the [cross-platform field equivalence table](/docs/schema/field-equivalence.md).