> ## Documentation Index > Fetch the complete documentation index at: https://docs.dally.ai/llms.txt > Use this file to discover all available pages before exploring further. # stage.card > Access: public. Send a JSON body; unknown keys are rejected with 400 invalid_request (inputs are strict). Responses may gain fields additively — never remove or repurpose; ignore unknown response fields. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/stage.card openapi: 3.1.0 info: title: Dally API version: v1 description: >- PRIVATE (posture 2026-09-01): the MCP connector is Dally's only supported surface; this REST surface serves internal harnesses only, and its keys are WorkOS-dashboard-issued, never product-issued (CONTEXT.md § Positions). Headless Dally v1 — Slack-shape RPC: every operation is POST /v1/ with a JSON body. Cursor-only pagination ({items, has_more, next_cursor}; next_cursor null is the only end signal). Unversioned while private (Jim 2026-09-03): a retired name drops in the first migration after the deployed release stops naming it; inputs are strict, responses are tolerant. servers: - url: https://dally.ai description: The production Headless Dally v1 API. security: [] paths: /v1/stage.card: post: tags: - stage summary: >- One reel's Content card, exactly the row a dally_show canvas carries, so a tap on a still in the Stage's strip can put that reel on the Stage without a new canvas. description: >- Access: public. Send a JSON body; unknown keys are rejected with 400 invalid_request (inputs are strict). Responses may gain fields additively — never remove or repurpose; ignore unknown response fields. operationId: stage.card requestBody: required: true content: application/json: schema: type: object properties: platform: type: string minLength: 1 description: >- The reel's platform as the card carries it: instagram, youtube or facebook. content_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: The reel's Content id, as every card carries it. required: - platform - content_id additionalProperties: false example: platform: instagram content_id: cbd78841-6529-4757-9469-dc61c9035517 responses: '200': description: Success. request_id is present on every response. content: application/json: schema: type: object properties: content: type: object properties: content_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: The reel this card is for. platform: type: string minLength: 1 description: That reel's platform. duration_seconds: anyOf: - type: number minimum: 0 - type: 'null' description: >- How long this content runs, in seconds; null for stills and for media Dally never measured. frames_sheet: anyOf: - type: object properties: key: type: string minLength: 1 description: >- Durable Dally object key of the sheet, the one picture every tile is cut from. url: anyOf: - type: string format: uri - type: 'null' description: >- Durable public URL of that sheet on Dally's media domain — non-expiring, safe to render inline, fetches without authentication. Null when no media domain is configured. columns: type: integer exclusiveMinimum: 0 description: How many tiles the sheet holds across. rows: type: integer exclusiveMinimum: 0 description: How many tiles the sheet holds down. tile_width_px: type: integer exclusiveMinimum: 0 description: Width of one tile in the sheet, in pixels. seconds: type: array items: type: number minimum: 0 description: >- The second each tile was taken at, in reading order across the sheet: left to right, top row first. required: - key - url - columns - rows - tile_width_px - seconds description: >- The Contact sheet Dally cut from this content: one picture, its geometry, and the second behind every tile. - type: 'null' description: >- The Contact sheet for this content; null until Dally's offline pipeline has cut one. A request never triggers the cutting. cut_seconds: type: array items: type: number minimum: 0 description: >- Every second a cut lands on, earliest first; empty when none were found or this content was never decomposed. usual: anyOf: - type: object properties: distribution: type: string enum: - organic - trial description: >- How the reels counted here were pushed, the same way this reel was: trial when this reel is a Trial Reel, read against the creator's other Trial Reels, which Instagram shows to people who do not follow them; organic for every other reel, read against the rest. The two are never mixed. reels: type: integer minimum: 1 description: >- How many of the creator's reels pushed that way the medians were taken over. views: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median views across those reels; null when the wing never observed views. likes: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median likes across those reels; null when the wing never observed likes. comments: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median comments across those reels; null when the wing never observed comments. saves: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median saves across those reels; null when the wing never observed saves. shares: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median shares across those reels; null when the wing never observed shares. reach: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median reach across those reels; null when the wing never observed reach. likes_per_1k: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median likes per 1,000 views across those reels — the middle of the reels' own ratios, never one median divided by another; null when the wing never observed likes or views. comments_per_1k: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median comments per 1,000 views across those reels — the middle of the reels' own ratios, never one median divided by another; null when the wing never observed comments or views. stayed_pct: anyOf: - type: number minimum: 0 maximum: 100 - type: 'null' description: >- Median share who stayed past three seconds, 100 minus the skip rate; null on a public creator, whose watch numbers only they can see. avg_watch_time_ms: anyOf: - type: number minimum: 0 - type: 'null' description: >- Median average watch time in milliseconds; null on a public creator, whose watch numbers only they can see. places: type: object properties: views: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. likes: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. comments: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. shares: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. saves: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. reach: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. stayed_pct: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. avg_watch_time_ms: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. likes_per_1k: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. comments_per_1k: type: object properties: place: type: integer minimum: 1 description: >- Where this reel stands among the creator's reels on this measure, 1 for the highest; reels tied on the measure share a place. of: type: integer minimum: 1 description: >- How many reels the creator's library holds, counting this one — the same count reels carries. required: - place - of description: >- One measure read against the creator's whole library: this reel's place in it and the library's size. A place is arithmetic over a named set, never a score for the reel. description: >- Where this reel stands in the creator's library, measure by measure. A measure this reel or the library has no number for is absent, never zero; empty when the caller cannot read the library. strip: type: array items: type: object properties: content_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: That reel's Content id. platform: type: string minLength: 1 description: That reel's platform. thumbnail_url: anyOf: - type: string - type: 'null' description: >- Durable cover-image URL on Dally's media domain, carried rather than guessed from the id; null when no cover image is cached. views: anyOf: - type: number - type: 'null' description: >- Views on that reel; null where the wing never observed them. likes: anyOf: - type: number - type: 'null' description: >- Likes on that reel as the card would carry them; null where the measure law withholds them. comments: anyOf: - type: number - type: 'null' description: >- Comments on that reel as the card would carry them; null where the measure law withholds them. required: - content_id - platform - thumbnail_url - views - likes - comments description: >- One reel in the strip: what it takes to paint its cover and print its count and multiple on the measure the strip is ordered by, views, likes or comments, never the video or the caption a tap needs. The multiple a count makes of the usual's median is the reader's arithmetic. description: >- The strip this reel sits in: the ten reels either side of it by views among the creator's reels pushed the same way, this reel among them, highest views first, each with its views, likes and comments so the strip can be reordered by any of the three; empty when the caller cannot read the library. required: - distribution - reels - views - likes - comments - saves - shares - reach - likes_per_1k - comments_per_1k - stayed_pct - avg_watch_time_ms - places - strip description: >- The creator's usual: the median of each measure across their reels pushed the way this one was, this reel's place among them and the strip it sits in, all of it the reference one reel is read against. A median and a place, never a rank of the creator and never a score. - type: 'null' description: >- What this creator's reels usually do; null when the caller's plan does not open it, or when this content is not a reel. media: type: array items: type: object properties: media_index: type: integer minimum: 0 description: >- 0 for standalone media; an album slide position counted from 1. media_type: type: string enum: - IMAGE - VIDEO description: >- Whether this item is a picture or a video, as the platform typed it. url: type: string format: uri description: >- Durable public URL of this item's bytes on Dally's media domain, the same class of URL as thumbnail_url. required: - media_index - media_type - url description: >- Every picture and clip of this Content that Dally holds bytes for, each at its original position, earliest first, read from the inventory the open operation reads: a video or a story is one clip at position 0, a photo one picture at 0, an album its slides from 1. A slide the provider withheld or Dally has not landed yet is absent here; the open operation names it with its coverage. Absent on a read that did not ask for it. beds: type: array items: type: object properties: bed: type: string minLength: 1 description: >- The recording's key, the one id a bed is served under: isrc: when the recognizer returned an ISRC, else shazam: when it returned its own key for the track, else window: for a bed no recognizer has identified beyond this fold. Every reel carrying the same recording carries the same key, so opening it from any card reaches the same bed. windows: minItems: 1 type: array items: type: object properties: start_seconds: type: number minimum: 0 description: >- The second of this reel where the recording comes in. end_seconds: type: number minimum: 0 description: >- The second of this reel where the recording goes out. required: - start_seconds - end_seconds description: >- Every window of this reel that carries this recording, earliest first. A reel that plays one recording three times carries one entry with three windows here, never three entries. title: type: string minLength: 1 description: >- The recording's title, as the recognizer returned it. artist: anyOf: - type: string - type: 'null' description: >- The recording's artist, as the recognizer returned it; null when the answer carried none. isrc: anyOf: - type: string - type: 'null' description: >- The recording's ISRC, as the recognizer returned it; null when the answer carried none. apple_music_url: anyOf: - type: string - type: 'null' description: >- Apple Music's own page for this recording, taken verbatim from the recognizer's answer; null unless that answer carried a real https://music.apple.com link, which about two thirds of them do. shazam_url: anyOf: - type: string - type: 'null' description: >- The recognizer's own page for this recording, taken verbatim from its answer; null when the answer carried none. required: - bed - windows - title - artist - isrc - apple_music_url - shazam_url description: >- The music under this reel's voice: one entry per recording this reel carries under a bed a recognizer named, earliest first by its first window. A window Dally heard as a sting, a window it heard as the same recording cut twice, and a bed no recognizer has named yet are never served here. Absent when this reel carries none. How many reels sit on a recording and what they usually do is the bed's own read, never the card's. required: - content_id - platform - duration_seconds - frames_sheet - cut_seconds - usual additionalProperties: {} description: The reel's card, with the creator's usual on it. request_id: type: string minLength: 1 description: >- Server-minted id for this request. Present on every response, success and error — quote it when reporting a problem. required: - content - request_id example: content: platform: instagram content_id: cbd78841-6529-4757-9469-dc61c9035517 duration_seconds: 43.093 frames_sheet: null cut_seconds: - 5.667 - 10.9 usual: distribution: organic reels: 1013 views: 24159 likes: 337 comments: 9 saves: null shares: null reach: null likes_per_1k: 18.2 comments_per_1k: 0.6 stayed_pct: null avg_watch_time_ms: null places: views: place: 419 of: 1013 likes: place: 420 of: 1013 comments: place: 524 of: 1013 likes_per_1k: place: 311 of: 1013 comments_per_1k: place: 604 of: 1013 strip: - content_id: 91459999-3dce-4dd4-962d-fa77bc017fa5 platform: instagram thumbnail_url: >- https://media.dally.ai/thumbnails/91459999-3dce-4dd4-962d-fa77bc017fa5.jpg views: 42308 likes: 613 comments: 11 - content_id: cbd78841-6529-4757-9469-dc61c9035517 platform: instagram thumbnail_url: >- https://media.dally.ai/thumbnails/cbd78841-6529-4757-9469-dc61c9035517.jpg views: 40117 likes: 613 comments: 11 request_id: req_01j8zkq default: description: >- Error — the real HTTP status carries the class; the body is always the one error envelope. Codes: invalid_request, stale_cursor, query_too_broad, unauthorized, forbidden, no_connected_accounts, stale_authority, not_found, precondition_failed, method_not_allowed, stale_snapshot, stale_revision, execution_payload_erased, exhaustiveness_unavailable, rate_limited, internal_error, unavailable, search_unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: ErrorEnvelope: type: object properties: error: type: object properties: code: type: string enum: - invalid_request - stale_cursor - query_too_broad - unauthorized - forbidden - no_connected_accounts - stale_authority - not_found - precondition_failed - method_not_allowed - stale_snapshot - stale_revision - execution_payload_erased - exhaustiveness_unavailable - rate_limited - internal_error - unavailable - search_unavailable description: >- The machine-readable error code. The set only grows — treat unknown codes by falling back to the HTTP status class. message: type: string description: >- A human-readable teaching message: what failed and the exact fix, never just the symptom. details: description: >- Optional structured context for this code — e.g. estimated_matches and ceiling on query_too_broad. type: object propertyNames: type: string additionalProperties: {} required: - code - message description: The error object — the one shape every failure wears. request_id: type: string minLength: 1 description: >- Server-minted id for this request. Present on every response, success and error — quote it when reporting a problem. required: - error - request_id description: The ONE error envelope (API-ERR-001). securitySchemes: bearerAuth: type: http scheme: bearer description: 'A WorkOS-dashboard-issued internal API key on Authorization: Bearer.' apiKeyAuth: type: apiKey in: header name: x-api-key description: The same internal API key, accepted on x-api-key. ````