> ## 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.references > 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.references 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.references: post: tags: - stage summary: >- Always the same two sets one reel is read against on the Stage, in the same order — the creator's whole reel library and the reels nearest by look across the pool — each with the set's median per measure, this reel's place in the set and the set's strip of stills; a set Dally could not draw is answered empty, never left out. The frame asks for it when a person opens the Stage; a card never carries it. 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.references 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_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 these sets are drawn for. platform: type: string minLength: 1 description: That reel's platform. references: type: array items: type: object properties: key: type: string enum: - usual - pool description: >- Which set the reel is read against: usual, the creator's reel library pushed the way this reel was, their Trial Reels for a Trial Reel and the rest for any other; pool, the reels nearest by look across every creator Dally admitted. measures: type: object properties: views: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. likes: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. comments: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. shares: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. saves: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. reach: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. stayed_pct: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. avg_watch_time_ms: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. likes_per_1k: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. comments_per_1k: type: object properties: median: type: number description: >- The middle value of this measure across the set. place: type: integer minimum: 1 description: >- Where this reel stands in the set on this measure, 1 for the highest value. of: type: integer minimum: 1 description: >- How many reels the set holds, counting this one. required: - median - place - of description: >- One measure read against one set: the set's median, this reel's place in it and the set's size. The multiple a count makes of the median is the reader's arithmetic, never a served number. description: >- Every measure this set can be read on. A measure the set or this reel has no number for is absent, never zero. A public creator's set carries only what the public measure law allows, plus likes and comments per 1,000 views, a ratio of two lawful counts. stills: 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: The reel's Content id. platform: type: string minLength: 1 description: The reel's platform. thumbnail_url: anyOf: - type: string - type: 'null' description: >- Durable cover-image URL on Dally's media domain, the same one the card carries; null when no cover image is cached. video_url: anyOf: - type: string - type: 'null' description: >- Durable video URL on Dally's media domain, the same one the card carries, so a tap on the still plays the reel before its card arrives; null where the card would carry none. caption: anyOf: - type: string - type: 'null' description: >- The first 300 characters of the reel's caption, the words the card carries, so the Stage can title the reel before its card arrives; null when the reel has no caption. 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. handle: anyOf: - type: string - type: 'null' description: >- The bare handle of the reel's creator; null when Dally has not resolved it. views: anyOf: - type: number - type: 'null' description: >- Views on that reel; null where the wing never observed them. wing: type: string enum: - mine - pool description: >- Which wing that reel is on: mine, a reel of an account this room holds, or pool, an admitted public reel; the Stage lays the reel out by its wing before its card arrives. required: - content_id - platform - thumbnail_url - video_url - caption - likes - comments - handle - views - wing description: >- One reel in the set's strip, as the picker shows it. description: >- The set's strip, highest views first, this reel among them: the ten either side of it for usual, the whole set for pool; empty when the set could not be drawn. required: - key - measures - stills description: >- One set this reel is read against. A set Dally could not draw comes with no measures and no stills, never left out and never faked. description: >- Always the same two sets, usual first, then pool. A set with no reels to draw from comes with no measures and no stills, never left out and never faked. 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_id - platform - references - request_id example: platform: instagram content_id: cbd78841-6529-4757-9469-dc61c9035517 references: - key: usual measures: views: median: 24159 place: 419 of: 1013 likes: median: 337 place: 372 of: 1013 stills: - content_id: cbd78841-6529-4757-9469-dc61c9035517 platform: instagram thumbnail_url: >- https://media.withdally.com/thumbnails/cbd78841-6529-4757-9469-dc61c9035517.jpg video_url: >- https://media.withdally.com/content/cbd78841-6529-4757-9469-dc61c9035517/video.mp4 caption: Call me a psycho but I enjoy cutting more than bulking likes: 613 comments: 11 handle: zacperna views: 40117 wing: mine - key: pool measures: {} stills: [] 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. ````