> ## 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. # previs.discard > 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/previs.discard 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/previs.discard: post: tags: - previs summary: >- Let a whole hook go. The card calls this when the creator swipes a hook left; call it yourself only when they say in words to drop that hook. It buys nothing, and keeping the hook later brings it back. 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: previs.discard requestBody: required: true content: application/json: schema: type: object properties: previs_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 completed hooks' Previs id. index: type: integer minimum: 0 maximum: 3 description: 'Zero-based frame: A=0, B=1, C=2, D=3.' request_key: type: string minLength: 1 maxLength: 128 description: >- One key for this one discard; send the same key again and nothing is logged twice. required: - previs_id - index - request_key additionalProperties: false example: previs_id: bc3c7b36-7ac7-433d-82ef-58bc2d1fe1d1 index: 2 request_key: discard-c-1 responses: '200': description: Success. request_id is present on every response. content: application/json: schema: type: object properties: previs: type: object properties: previs_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: >- Durable Dally id of this previs; previs.read, previs.pick and previs.reword take it, and a storyboard names it as parent_id. kind: type: string enum: - hooks - storyboard description: >- hooks: four alternative openings for one idea. storyboard: four consecutive beats of the picked hook's story. title: type: string description: The short title the model gave this idea. format: type: string enum: - '9:16' - '16:9' description: >- The video frame shape: 9:16 short form or 16:9 long form. frames: minItems: 4 maxItems: 4 type: array items: type: object properties: say: type: string maxLength: 1000 description: >- The verbatim spoken line, authored for this new idea. see: type: string minLength: 1 maxLength: 2000 description: >- The shot: the move borrowed from the receipt, then action, setting, framing, expression and props. Write a concrete scene; Dally draws it wordless and paints the words in the band above the head, so frame it with room for them, head and shoulders or wider and never a tight close-up of the face, as the creator's own openings do. skeleton: default: '' description: >- The opening this frame's words are cut from, word for word as it ran, with only its specifics swapped for ___: the numbers, names, places and the particular thing done. Every other word is the original's, in its order, so another creator could fill it: the words that make the hook work stay, such as I just, POV:, nobody tells you, and I still. Two to four blanks is typical; when blanking would leave almost nothing, blank less, and when a name or a number remains, blank more. Keep it short enough to paint, the hook's opening sentence and not the sentence after it. Write it before on_screen. Empty on a frame that borrows no opening. type: string maxLength: 200 on_screen: type: string maxLength: 200 description: >- The words the card paints over this frame's drawing. On a hook it is the skeleton itself, blanks and all: the template goes on the frame first, and the creator picks a fill or writes their own. On a storyboard beat it is that beat's line. Lettered as the creator letters their own openings; empty means no words. Painted, never drawn, so they can change without a redraw. other_words: default: [] description: >- Three fills of the skeleton from the creator's life, the suggestions the card offers beside the frame for them to bounce off: each is the skeleton with its blanks filled and every other word kept as it is, never a rewrite of it, with ___ left where only they can fill it, and never the original's own line again. previs.reword paints one without a redraw. maxItems: 3 type: array items: type: string minLength: 1 maxLength: 200 seconds: type: number exclusiveMinimum: 0 maximum: 300 description: >- Planned duration of this hook or story beat in seconds. place: default: lower description: >- Where the painted words sit on the frame: upper, a headline above the head; lower, a line under the chin, where a reel's captions sit; middle, for a shot with no face in its middle. On a drawn panel Dally keeps the words clear of the head whichever place is asked: a line that would cover it moves to the band above it. previs.reword moves them. type: string enum: - lower - middle - upper box: default: none description: >- The label behind the painted words: none is white words with a shadow, black is white words on a black label, white is black words on a white label. type: string enum: - black - white - none borrowed_from: maxItems: 3 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: >- Dally-stable content id (UUID). Content is always addressed by the composite (content_id, platform); platform-native ids are never primary keys. platform: type: string enum: - instagram description: >- The platform a row belongs to. v1 supports instagram; more platforms will be added to this enum additively — treat unknown values as new platforms, never as errors. quote: default: null description: >- The words taken from that reel, verbatim: for the reel a skeleton was cut from, the very line it was cut from, the headline on its screen when that is where the hook ran, else the spoken line; for a reel a fill came from, the creator's own line. Dally finds a spoken line's second. Null when nothing is said or written there. anyOf: - type: string minLength: 1 maxLength: 200 - type: 'null' at: default: null description: >- The second of the opening you are borrowing from, as the moments you watched with open name it. Leave null with a quote and Dally fills it from the words. anyOf: - type: number minimum: 0 maximum: 3600 - type: 'null' move: type: string minLength: 1 maxLength: 200 description: >- What you are taking from that reel: for the reel a skeleton came from, its opening as you saw it, what is on screen and what happens, such as the phone held up to the lens; for a reel a fill came from, the thing the creator lived that fills the blank. still: anyOf: - type: string format: uri - type: 'null' description: >- The frame of that reel at the receipt's second, from Dally's media store; null when Dally has not cut that reel's frames, and the card shows the reel's cover instead. required: - content_id - platform - quote - at - move - still description: >- The openings this frame borrows from: at most three reels, the creator's own or the pool's, each with the move you are taking, the spoken line there and its second. Dally shows each under the frame with that reel's frame at that second and keeps them with the pick. Empty when the frame borrows nothing. required: - say - see - skeleton - on_screen - other_words - seconds - place - box - borrowed_from description: >- The four frames as authored, in reading order: A, B, C, D. receipts: maxItems: 12 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: >- Dally-stable content id (UUID). Content is always addressed by the composite (content_id, platform); platform-native ids are never primary keys. platform: type: string minLength: 1 description: >- The platform of the reel this receipt resolved to. required: - content_id - platform additionalProperties: {} description: >- The reels the receipts name, resolved as content cards inside this caller's scope, one per distinct reel, so the card can stage the reel when its receipt is tapped. A reel this caller cannot read is absent, and its receipt shows as words alone. status: type: string enum: - queued - running - ready - failed description: >- queued (the drawing is ordered), running (the provider is drawing), ready (the sheet is stored), failed (error says why). picked_index: anyOf: - type: integer minimum: 0 maximum: 3 - type: 'null' description: >- The zero-based frame the person chose, A=0 to D=3; null until previs.pick records one. verdicts: type: array items: type: object properties: index: type: integer minimum: 0 maximum: 3 description: 'Zero-based frame: A=0, B=1, C=2, D=3.' verdict: type: string enum: - kept - discarded description: >- What the creator last did with this hook: kept, with the idea that was in front, or discarded, which lets the whole hook go. template: anyOf: - type: object properties: format: type: string enum: - '9:16' - '16:9' description: >- The shape of the frame: 9:16 upright, 16:9 wide. layers: maxItems: 24 type: array items: oneOf: - type: object properties: kind: type: string const: picture description: A picture placed in a box. id: type: string minLength: 1 maxLength: 64 description: >- The layer's name within this document; setting is the picture that fills the frame. x: type: number minimum: -50 maximum: 150 description: >- The layer's left edge, as a percent of the frame's width. 'y': type: number minimum: -50 maximum: 150 description: >- How far the layer sits from the edge anchor names, as a percent of the frame's height. w: type: number minimum: 1 maximum: 100 description: >- The layer's width, as a percent of the frame's width. anchor: description: >- The edge y is measured from: top when absent; bottom holds the layer's lower edge still, so longer words grow upward. type: string enum: - top - bottom span: description: >- The seconds the layer holds, from and to; absent on a cover, where every layer is there the whole time. readOnly: true type: array prefixItems: - type: number minimum: 0 - type: number minimum: 0 picture: oneOf: - type: object properties: kind: type: string const: drawn description: >- A panel Dally drew for a previs, cut out of its sheet. url: type: string minLength: 1 description: The drawn sheet's address. panel: type: integer minimum: 0 description: >- Which panel of the sheet, counted from 0 in reading order: A=0, B=1, C=2, D=3. columns: type: integer minimum: 1 maximum: 4 description: How many panels the sheet holds across. rows: type: integer minimum: 1 maximum: 4 description: How many rows of panels the sheet holds. format: type: string enum: - '9:16' - '16:9' description: The shape of one panel. previs_id: description: >- The previs the panel was drawn for, so a kept frame names where it came from. 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)$ required: - kind - url - panel - columns - rows - format - type: object properties: kind: type: string const: frame description: A still cut from a reel at one second. 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 the frame was cut from. at: type: number minimum: 0 description: The second of the reel the frame shows. url: type: string minLength: 1 description: >- The stored frame's address, or its sheet's when sheet is given. sheet: description: >- Where the frame sits on a sheet of many frames; absent for a frame stored alone. type: object properties: tile: type: integer minimum: 1 description: >- Which tile of the sheet this frame is, counted from 1 in reading order. columns: type: integer minimum: 1 maximum: 8 description: How many tiles the sheet holds across. rows: type: integer minimum: 1 maximum: 8 description: How many rows of tiles the sheet holds. tile_width_px: type: integer minimum: 1 description: The width of one tile, in pixels. tile_height_px: type: integer minimum: 1 description: The height of one tile, in pixels. required: - tile - columns - rows - tile_width_px - tile_height_px required: - kind - content_id - at - url - type: object properties: kind: type: string const: owned description: A picture the creator supplied. url: type: string minLength: 1 description: The picture's address. credit: description: >- Who to credit for the picture, when someone is owed it. type: string maxLength: 200 required: - kind - url - type: object properties: kind: type: string const: card description: A flat colour, with no picture at all. colour: type: string pattern: ^#[0-9a-fA-F]{6}$ description: >- The colour as six hex digits after a hash, such as #000000. required: - kind - colour description: What the box shows. h: type: number minimum: 1 maximum: 100 description: >- The box's height, as a percent of the frame's height. fit: type: string enum: - cover - contain description: >- cover fills the box and crops what spills; contain shows the whole picture inside it. required: - kind - id - x - 'y' - w - picture - h - fit - type: object properties: kind: type: string const: text description: Words painted over the frame. id: type: string minLength: 1 maxLength: 64 description: >- The layer's name within this document; setting is the picture that fills the frame. x: type: number minimum: -50 maximum: 150 description: >- The layer's left edge, as a percent of the frame's width. 'y': type: number minimum: -50 maximum: 150 description: >- How far the layer sits from the edge anchor names, as a percent of the frame's height. w: type: number minimum: 1 maximum: 100 description: >- The layer's width, as a percent of the frame's width. anchor: description: >- The edge y is measured from: top when absent; bottom holds the layer's lower edge still, so longer words grow upward. type: string enum: - top - bottom span: description: >- The seconds the layer holds, from and to; absent on a cover, where every layer is there the whole time. readOnly: true type: array prefixItems: - type: number minimum: 0 - type: number minimum: 0 text: type: string maxLength: 400 description: The words, exactly as painted. font: type: string enum: - classic - modern - strong - typewriter - neon - serif description: >- The lettering; classic is the one reels caption in. box: type: string enum: - black - white - none description: >- The label behind the words: black, white, or none for bare words with a shadow. align: type: string enum: - left - center description: >- How the lines sit within the layer's width. size: anyOf: - type: string enum: - s - m - l - xl - type: number minimum: 12 maximum: 240 description: >- How large the words are: one of the four named sizes, or a number of pixels on a frame 1080 wide. required: - kind - id - x - 'y' - w - text - font - box - align - size - type: object properties: kind: type: string const: proof description: >- A comment or message shown as a card, the proof a hook points at. id: type: string minLength: 1 maxLength: 64 description: >- The layer's name within this document; setting is the picture that fills the frame. x: type: number minimum: -50 maximum: 150 description: >- The layer's left edge, as a percent of the frame's width. 'y': type: number minimum: -50 maximum: 150 description: >- How far the layer sits from the edge anchor names, as a percent of the frame's height. w: type: number minimum: 1 maximum: 100 description: >- The layer's width, as a percent of the frame's width. anchor: description: >- The edge y is measured from: top when absent; bottom holds the layer's lower edge still, so longer words grow upward. type: string enum: - top - bottom span: description: >- The seconds the layer holds, from and to; absent on a cover, where every layer is there the whole time. readOnly: true type: array prefixItems: - type: number minimum: 0 - type: number minimum: 0 from: type: string maxLength: 80 description: Who wrote it, as the card names them. at: type: string maxLength: 40 description: >- When it was written, as the card prints it. lines: minItems: 1 maxItems: 6 type: array items: type: string maxLength: 400 description: What they wrote, one bubble a line. tilt: description: >- How many degrees the card leans; level when absent. type: number minimum: -30 maximum: 30 required: - kind - id - x - 'y' - w - from - at - lines description: >- What is on the frame, stacked in list order with the first at the back: pictures, words and proof cards, each in its own box. required: - format - layers - type: 'null' description: >- The document kept in front, the frame with its words exactly as the creator kept them; null for a discarded hook. required: - index - verdict - template description: >- The hooks the creator has judged on the card, newest verdict only; a hook they have not swiped is absent. Every idea of a kept hook stays in frames. revision: type: integer minimum: 1 description: >- The newest revision; pass it as expected_revision to previs.reword so a stale write is refused. revisions: type: array items: type: object properties: revision: type: integer minimum: 1 description: This revision's number. made_by: type: string enum: - chat - card - web description: >- Where it came from: chat (the host from the conversation), card (the person's hand in the frame), web (the Dally web page). what: type: string description: What changed, in the maker's words. forked_from: anyOf: - type: integer - type: 'null' description: >- The earlier revision brought back to make this one; null otherwise. created_at: type: string description: >- When this revision was recorded, as an ISO instant. frames: minItems: 4 maxItems: 4 type: array items: type: object properties: on_screen: type: string maxLength: 200 description: >- The words the card paints over this frame's drawing. On a hook it is the skeleton itself, blanks and all: the template goes on the frame first, and the creator picks a fill or writes their own. On a storyboard beat it is that beat's line. Lettered as the creator letters their own openings; empty means no words. Painted, never drawn, so they can change without a redraw. place: type: string enum: - lower - middle - upper description: Where the words sat. box: type: string enum: - black - white - none description: The label behind the words. required: - on_screen - place - box description: >- The four frames' painted words, place and label as this revision left them, A to D. required: - revision - made_by - what - forked_from - created_at - frames description: >- Every revision, oldest first: the authoring, each reword and each pick, with who made it and what changed. previs.reword with from_revision brings an earlier one back as a new revision. error: anyOf: - type: string - type: 'null' description: >- Why the drawing failed, in the provider's words; null otherwise. result: anyOf: - type: object properties: image_url: type: string format: uri description: >- Where the finished four-frame sheet is stored on Dally's media host. width: type: number description: Pixel width of the stored sheet. height: type: number description: Pixel height of the stored sheet. artist: type: string description: >- Who drew the sheet, named as the provider names it. quality: type: string description: The quality tier the drawing was ordered at. provider: type: string description: The provider the drawing went through. cost_usd: anyOf: - type: number - type: 'null' description: >- What the provider charged for this drawing, in US dollars; null when it did not say. latency_ms: type: number description: >- Milliseconds from the order to the complete image. provider_request_id: anyOf: - type: string - type: 'null' description: >- The provider's own id for the drawing; null when it gave none. usage: type: object propertyNames: type: string additionalProperties: {} description: >- The provider's usage record for the drawing, as it reported it. required: - image_url - width - height - artist - quality - provider - cost_usd - latency_ms - provider_request_id - usage - type: 'null' description: >- The finished drawn sheet and what it cost; null until it is ready. created_at: type: string description: When the previs was made, as an ISO instant. required: - previs_id - kind - title - format - frames - receipts - status - picked_index - verdicts - revision - revisions - error - result - created_at description: >- The stored previs and its current state; dally_show kind previs takes this whole response. show: type: object properties: kind: type: string const: previs description: The dally_show kind that renders the previs. required: - kind description: >- How it is shown: dally_write renders this kind on this very answer with this whole response as its data, so the creator already sees it; do not render it again. 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: - previs - show - request_id example: request_id: req_previs_example previs: previs_id: bc3c7b36-7ac7-433d-82ef-58bc2d1fe1d1 kind: hooks title: The plan that made me stop filming format: '9:16' frames: - say: I spent longer choosing a font than filming. see: >- The creator closes a laptop at a kitchen table, looking quietly amused. skeleton: I spent longer ___ than ___ on_screen: I spent longer ___ than ___ other_words: - I spent longer choosing a font than filming - I spent longer naming the file than filming - I spent longer picking a thumbnail than filming seconds: 4 place: lower box: none borrowed_from: [] - say: I spent longer choosing a font than filming. see: >- The creator closes a laptop at a kitchen table, looking quietly amused. skeleton: Day ___ of ___ on_screen: Day ___ of ___ other_words: - Day three of choosing the font - Day three of not filming - Day three of the same font seconds: 4 place: lower box: none borrowed_from: [] - say: I spent longer choosing a font than filming. see: >- The creator closes a laptop at a kitchen table, looking quietly amused. skeleton: Nobody asked but I ___ on_screen: Nobody asked but I ___ other_words: - Nobody asked but I picked the font - Nobody asked but I named the reel - Nobody asked but I chose the serif seconds: 4 place: lower box: none borrowed_from: [] - say: I spent longer choosing a font than filming. see: >- The creator closes a laptop at a kitchen table, looking quietly amused. skeleton: I finished ___ before I started ___ on_screen: I finished ___ before I started ___ other_words: - I finished the font before I started filming - I finished the plan before I started the reel - I finished the intro card before I started the script seconds: 4 place: lower box: none borrowed_from: [] receipts: [] status: ready picked_index: null verdicts: - index: 2 verdict: discarded template: null revision: 1 revisions: - revision: 1 made_by: chat what: Four hooks authored forked_from: null created_at: '2026-09-10T19:00:00.000Z' frames: - on_screen: I spent longer ___ than ___ place: lower box: none - on_screen: Day ___ of ___ place: lower box: none - on_screen: Nobody asked but I ___ place: lower box: none - on_screen: I finished ___ before I started ___ place: lower box: none result: image_url: >- https://media.withdally.com/generated/previs/7d3f2a1b-4c5e-4f6a-8b9c-0d1e2f3a4b5c/bc3c7b36-7ac7-433d-82ef-58bc2d1fe1d1.png width: 864 height: 1536 artist: openai/gpt-image-2 quality: low provider: openrouter cost_usd: 0.04 latency_ms: 21000 provider_request_id: null usage: {} error: null created_at: '2026-09-10T19:00:00.000Z' show: kind: previs 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. ````