Schemas and examples

API v1 is designed so clients can consume one stable schema across all normal scraper modules.

Top-level response

{
  "data": {},
  "meta": {"api_version": "1"}
}

meta.api_version is currently the literal string "1".

`data`

{
  "id": "CONTENT_ID",
  "source": {
    "platform": "instagram",
    "url": "https://www.instagram.com/p/CONTENT_ID/",
    "application": null
  },
  "content": {
    "title": null,
    "text": "Example caption",
    "html": null,
    "published_at": "2026-07-15T11:56:00Z"
  },
  "author": {
    "name": "Creator Name",
    "username": "creator"
  },
  "media": [],
  "music": null,
  "engagement": null,
  "safety": null,
  "link": null
}

`source.platform`

One of:

tiktok
instagram
shorts
soundcloud
ytmusic
spotify
deezer
threads
twitter

`content`

Field	Type	Notes
`title`	string or null	Platform/content title when available
`text`	string or null	Caption/post text/description
`html`	string or null	Structured HTML supplied by a module when applicable
`published_at`	ISO datetime or null	Normalized publication time

`author`

name and username are each nullable strings. Clients should not assume both are present.

Media assets

All downloadable images, video, audio, covers, and soundtracks are represented in one ordered data.media array.

{
  "index": 0,
  "type": "video",
  "role": "content",
  "url": "/media/instagram/CONTENT_ID/video.mp4",
  "preview_url": "/media/instagram/CONTENT_ID/thumbnail.jpg",
  "dimensions": {"width": 1080, "height": 1920},
  "duration_seconds": null,
  "title": null,
  "artist": null,
  "looping": false
}

Field	Type	Rules
`index`	integer	Zero or greater; ordering key
`type`	`image`, `video`, or `audio`	Physical media type
`role`	`content`, `soundtrack`, or `cover`	Semantic purpose
`url`	string	Protected media path or module-provided URL adapted by gateway
`preview_url`	string or null	Optional preview/thumbnail path
`dimensions`	object or null	Positive integer `width` and `height` when measurable
`duration_seconds`	integer or null	Zero or greater when known
`title`	string or null	Asset-level title, useful for music/soundtracks
`artist`	string or null	Asset-level artist
`looping`	boolean	Marks looping/animated video semantics

The gateway probes cached visual files for dimensions when possible. Images/videos can still have dimensions: null if inspection fails. Audio has no visual dimensions.

Carousels retain media ordering. Slideshow audio uses role: "soundtrack"; album art uses role: "cover". Threads music attachments can appear as soundtrack previews with separate cover assets.

Optional metadata

`music`

{"album":"Album name"}

Currently the stable normalized music metadata object exposes nullable album.

`engagement`

{
  "likes": 100,
  "replies": 3,
  "reposts": 4,
  "quotes": 1,
  "views": 1000
}

Every counter is nullable and, when present, non-negative.

`safety`

{
  "spoiler": false,
  "text_spoiler": false,
  "nsfw": false
}

All three values are booleans.

`link`

{"url":"https://example.com/..."}

Used when a normalized result includes a primary associated link.

Example machine response

{
  "data": {
    "id": "SHORTCODE",
    "source": {
      "platform": "instagram",
      "url": "https://www.instagram.com/p/SHORTCODE/",
      "application": null
    },
    "content": {
      "title": null,
      "text": "Example reel",
      "html": null,
      "published_at": null
    },
    "author": {"name": "creator", "username": "creator"},
    "media": [
      {
        "index": 0,
        "type": "video",
        "role": "content",
        "url": "/media/instagram/SHORTCODE/video.mp4",
        "preview_url": "/media/instagram/SHORTCODE/thumbnail.jpg",
        "dimensions": {"width": 1080, "height": 1920},
        "duration_seconds": null,
        "title": null,
        "artist": null,
        "looping": false
      }
    ],
    "music": null,
    "engagement": null,
    "safety": null,
    "link": null
  },
  "meta": {"api_version": "1"}
}

Error response

API v1 failures use one stable envelope:

{
  "error": {
    "code": "not_found",
    "message": "Human-readable explanation",
    "details": null
  }
}

details can contain structured context or be null. Clients should branch on error.code rather than parsing the message text.