> ## 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. # bed.read > 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/bed.read 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/bed.read: post: tags: - bed summary: >- One recording: the name a recognizer gave it, where to hear it away from Dally, its cover art while a person is looking at it, how many reels the caller can read carry it, what those reels usually get, and their cards. Every reel carrying the recording is gathered, whoever made it, however the fold grouped its windows. A reel the caller cannot read is absent from the cards and absent from the count. The frame asks for it when a person opens the bed; 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: bed.read requestBody: required: true content: application/json: schema: 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. required: - bed additionalProperties: false example: bed: isrc:QM24S2401697 responses: '200': description: Success. request_id is present on every response. content: application/json: schema: 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. 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. cover_art_url: anyOf: - type: string - type: 'null' description: >- Apple's own URL for this recording's album art, looked up from Apple while this answer was being written and never held by Dally, so the picture is loaded from Apple's servers by whoever is looking at it. Null unless this bed carries an apple_music_url the art can sit beside, and null whenever the lookup missed, timed out or answered anything but a picture; the bed reads the same either way. reels: type: integer minimum: 0 description: >- How many reels the caller can read carry this recording, counting every one of them, not only the ones whose cards ride in members. median_views: anyOf: - type: number minimum: 0 - type: 'null' description: >- The middle view count of those reels; null when none of them carries a view count. members: 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 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: >- One Content card exactly as a dally_show canvas carries it: the identity and Stage fields named here, and beside them every other column of the content_cards table dally_guide teaches — the creator, the cover, the video, the caption, the counts and the Swipe file mark. description: >- Those reels' cards, most-viewed first, in the same shape a card read hands back, capped at one page. A reel the caller cannot read is absent here and absent from reels. 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: - bed - title - artist - isrc - apple_music_url - shazam_url - cover_art_url - reels - median_views - members - request_id example: bed: isrc:QM24S2401697 title: Dramamine artist: Flawed Mangoes isrc: QM24S2401697 apple_music_url: >- https://music.apple.com/album/dramamine/1715911324?i=1715911902 shazam_url: https://www.shazam.com/track/706252169/dramamine cover_art_url: >- https://is1-ssl.mzstatic.com/image/thumb/Music126/v4/3c/16/98/3c16983a-69c6-fd9c-b573-ebf1d0897ec0/5056495122067_Cover.jpg/400x400bb.jpg reels: 2 median_views: 325000 members: - content_id: cbd78841-6529-4757-9469-dc61c9035517 platform: instagram duration_seconds: 43.093 frames_sheet: null cut_seconds: - 5.667 - 10.9 usual: null 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. ````