Media list schema
The unified SocialCrawl media-file list schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
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 | 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
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.
| Platform | Endpoints |
|---|---|
| YouTube | /v1/youtube/video/audio, /v1/youtube/video/files, /v1/youtube/video/subtitles, /v1/youtube/video/thumbnails |
Machine-readable schema
Validate responses programmatically against the JSON Schema (2020-12):
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
Endpoints with the MediaList archetype return this shape:
See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.