---
title: "Plan a walkthrough"
method: POST
path: "/storyboards"
tags: ["storyboards"]
---

# Plan a walkthrough

`POST /storyboards`

## Request

- Base URL: `https://api.gogoscreen.com/api/v1`
- URL: `https://api.gogoscreen.com/api/v1/storyboards`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Open a live website, work out how to show what the hint asks for, and prove every step by doing it. The result is a storyboard: beats with a screenshot each, which `renders.createFromStoryboard` turns into a video. PLANNING IS FREE and holds no video time, but an account must still afford the shortest video the plan could become. Steps are budgeted from the length; `lengthFit.adjusted` says when the plan was cut to fit. Answers 202 with a `Location`; poll until `state` is terminal. One plan at a time per account.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `background` string: What sits around the recording: `studio` (the default) puts the whole window on a quiet backdrop, `none` lets it fill the frame. Ids from catalog.renderOptions.
  - `captionStyle` string: How burned-in captions look, as an id from `catalog.renderOptions.captionStyles`. It only reaches the frame on a look template that burns captions (`captioned`); on any other template the choice is recorded and nothing is drawn. Omit for the catalogue default.
  - `capture` string: The shape of the recording: a computer window or a phone view.
  - `credentials` object: A demo account to sign in with, and the page it signs in on. Kept encrypted for this storyboard's session, so its render can sign in again, and deleted at most two hours after their last use.
    - `additionalLoginOrigins` string[]: Other exact https origins this account's sign-in may pass through, e.g. ["https://login.example.com"] for a single sign-on provider on its own host. At most 5. Nothing else — not a redirect, a link or a sibling subdomain — is ever approved on its own: a sign-in that moves to an origin not listed here stops before the account is typed. Ordinary same-origin sign-ins need none.
    - `loginUrl` string, required: REQUIRED whenever credentials are given: the page this demo account signs in on, e.g. https://app.example.com/login. Any origin — a product commonly signs in on a different host from its marketing site, and this is what tells the run where the app itself lives. Must be https; checked by the same guard as the site address. Its origin is the only place the account is typed unless `additionalLoginOrigins` names others.
    - `password` string, required
    - `username` string, required
  - `hint` string, required: What to show, in a sentence: "show the invoice creation flow". "demo my app" produces a demo of nothing in particular.
  - `language` string
  - `maxSeconds` integer: The ceiling an Auto video may grow to, 1–600 seconds.
  - `orientation` string
  - `targetSeconds` integer: A fixed length, 1–600 seconds. Omit for Auto, which sizes itself to what it finds and is capped by `maxSeconds`.
  - `templateId` string: A saved or system template id from catalog.renderOptions.
  - `url` string, required: The page to start from. Public addresses only; a private or link-local address is refused.
  - `voiceId` string

## Response `200`

The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.

- object
  - `created` boolean, required
  - `resource` object, required
    - `artifactsExpired` boolean, required: The work succeeded but its files were deleted at the end of the retention period.
    - `cancellable` boolean, required
    - `cost` object, required
      - `secondsCharged` number, nullable, required
      - `secondsReserved` number, required
      - `watermark` boolean, required
    - `createdAt` string, date-time, nullable, required
    - `error` object, nullable, required
      - `code` string, required
      - `reason` string, nullable, required
      - `retryable` boolean, required
      - `terminal` boolean, required
    - `expiresAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `id` string, required
    - `idempotencyKey` string, nullable, required
    - `internalStatus` string, required: A finer-grained status word. Informational; branch on `state`.
    - `kind` string, required: walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation
    - `pollAfterMs` number, nullable, required: Wait this long before polling again; null once the state is terminal.
    - `progress` object, nullable, required: HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw.
      - `at` string, nullable, required: When it was reported. A reading that has stopped moving means the work has, not that the bar is broken.
      - `percent` number, required: 0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.
      - `stage` string, required: A short label for the current step. Show it; do not branch on it.
    - `requestId` string, nullable, required
    - `result` object, nullable, required
      - `artifacts` object[], required
        - `bytes` number, nullable, required
        - `expiresAt` string, date-time, nullable, required
        - `sha256` string, nullable, required
        - `type` string, required
        - `url` string, nullable, required
      - `durationSeconds` number, nullable, required
    - `stage` string, nullable, required
    - `startedAt` string, date-time, nullable, required
    - `state` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required: The five public states. Poll until one of succeeded/failed/cancelled.

## Other responses

- `202`: The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.
- `400`: `validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `hint_required` — Say what to show, in a sentence. · `hint_too_long` — That description of what to show is too long. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `url_malformed` — That address could not be read as a URL. · `login_url_invalid` — That login page address is not one this API will fetch. · `login_url_required` — Credentials need the address of the page they sign in on. · `login_origins_invalid` — Additional sign-in addresses must be a short list of https addresses this API will fetch. · `idempotency_key_unscoped` — An idempotency key needs an account to belong to. · `options_invalid` — Those render options are not valid. · `template_unknown` — No such template. The catalogue is at GET /api/v1/catalog/render-options. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `capture_unknown` — No such capture shape. The catalogue is at GET /api/v1/catalog/render-options. · `capture_incompatible` — Phone view only makes a portrait video. Pick a portrait orientation or a computer capture. · `avatar_unknown` — No such presenter. The catalogue is at GET /api/v1/catalog/render-options. · `avatar_unavailable` — The presenter circle is not available on this deployment. Make the video without one. · `caption_style_unknown` — No such caption style. The catalogue is at GET /api/v1/catalog/render-options. · `language_unknown` — No such language. The catalogue is at GET /api/v1/catalog/render-options. · `voice_language` — That voice does not speak the chosen language. Pick a voice listed for it. · `background_unknown` — No such background. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use "Talk to a person": support can allow a site by name.
- `401`: `unauthorized` — Authentication is required.
- `402`: `insufficient_seconds` — You do not have enough video time left. Buy more time to keep going.
- `403`: `forbidden_scope` — This credential does not carry the scope this operation needs.
- `404`: `not_found` — No such resource.
- `409`: `idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `storyboard_in_flight` — There is already a plan being made on this account. Wait for it, or cancel it.
- `413`: `payload_too_large` — That request body is too large.
- `415`: `unsupported_media_type` — That content type is not supported.
- `429`: `rate_limited` — Too many requests. Try again shortly. · `anon_lifetime_cap` — That session has planned as many videos as it may. · `origin_daily_cap` — That website has been planned as many times today as it may be.
- `500`: `internal_error` — Something went wrong. Try again.
- `503`: `budget_exhausted` — Planning is paused for today. Try again tomorrow. · `abuse_check_unavailable` — Planning is temporarily unavailable. · `queue_unavailable` — That work cannot be queued right now. Try again shortly. · `vault_unavailable` — Credentials cannot be stored right now. Try again shortly.

---

[API](https://skmtc.dev/gogoscreen/apis/gogoscreen-api.md) · [All operations](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/revisions/2fd812319d75?raw)