Reference
Glossary
Every term these docs use, defined once. The words are the ones the server uses, so a term here is a term you will meet in a field name or an error code.
What the API makes
Two things, and they are named consistently everywhere: a walkthrough and a marketing video.
| Term | Definition |
|---|---|
| Walkthrough | A video of GogoScreen working through a real website, not a mockup. It is made in two steps, a storyboard and then a render. This is one of the two things this API makes. |
| Storyboard | The plan for a walkthrough. GogoScreen visits the site, works out how to show what the brief asked for, and checks every step on the real site. The result is a list of beats with a screenshot each. Planning reserves no video time. POST /storyboards starts one. |
| Beat | One step of a storyboard: what it clicks, where it goes, what it types, and the narration for it. When you turn a storyboard into a video you may rewrite a beat's narration or hide it altogether; everything else about a beat is the plan's own and is not accepted from a caller. |
| Render | The recording itself: the storyboard's beats performed on the real site, narrated, edited and made into an MP4. This is what spends the account's video time. POST /renders plans and records in one call; POST /storyboards/{id}/renders records a plan you have already seen. |
| Hint | The one sentence brief that tells GogoScreen what to show, for example "show how an invoice is created and sent". It is required and it must be between 3 and 1000 characters; nothing checks that it is specific, and it is the single biggest influence on whether the video is any good. storyboards.improveHint rewrites a thin one into a clearer form before you spend anything. |
| Marketing video | The other thing this API makes: a designed promotional film built from a website or from a walkthrough you already have. The chain is source, then generation, then project with a revision, then export. |
| Marketing source | A website read from its live pages and kept as a versioned manifest: its pages, its words and its pictures. Scanning costs no video time. A project built from one keeps the version it was built from, so a later scan never changes a film that already exists. |
| Generation | The step that turns a scanned source into a project: AI reads the manifest, plans the scenes and writes the words. It costs no video time, though the account must be able to afford the film it would produce. It answers a project and its first revision. |
| Project | An editable marketing video. It has a design, a source it was built from, and a current revision. Nothing is charged for holding one. |
| Revision | One saved version of a project: its scenes, its copy, its music, its speed and its look. Every version is kept, so every change is undoable. A save names the revision it is changing with expectedRevisionId, and a save that lands on a revision somebody else has already replaced is 409 revision_conflict with nothing written. |
| Export | Cutting one revision into a finished file, with its cover image, captions and transcript. This is the marketing operation that spends video time. Time is reserved at the delivered length and settled when the file is made. |
| Brand kit | The brand a marketing video signs with: the name on the pill, the accent colour, the default closing line, and optionally a palette, a font, a copy language and a tone. It is replaced rather than merged. Its copy is checked against the house rule that the designs set type with no en dash, no em dash, no spaced hyphen and no double hyphen; a hyphen inside a word is fine. |
| Template | Two different things, and the context says which. A saved render template is a named set of walkthrough options this account stores so it does not have to send them every time. A marketing template, also called a design, is one of the authored film designs a project is built in, and it is the thing that decides which shapes, lengths and audio modes an export may ask for. |
| Catalogue | The read only lists of what may be asked for: voices, plans, render options and marketing designs. Under /catalog, behind the catalog:read scope, which reveals nothing about the account. |
| Quote | A priced answer that creates nothing and spends nothing. renders.quote prices walkthrough options, marketing.exports.quote prices an export. Both are reads despite being POSTs, because the request is a body rather than a query string. |
Video time
| Term | Definition |
|---|---|
| Seconds wallet | The account's video time, in whole seconds, held in three buckets: plan seconds bought as a monthly plan which expire, pay as you go seconds which do not, and free seconds granted at signup. availableSeconds is the one number a reservation is judged against. |
| Reserved seconds | Time held while a job runs, so a balance of sixty seconds cannot start twenty videos. It is taken out of the buckets when the job is queued and it is not a charge. cost.secondsReserved on the job envelope. |
| Charged seconds | What the job actually cost, settled when it finishes: the finished file's measured length, which can be less than was reserved, with the difference returned. cost.secondsCharged is null until it settles, and it is 0 for a job that failed or was cancelled. Nothing is charged for a video you cannot download. |
| Spend order | Plan seconds, then pay as you go, then free. The time that expires soonest goes first, which loses the customer the least, and it means free seconds are spent last. |
| Watermark | The free tier mark burned into a file any of whose seconds came out of the free bucket. Because free seconds are spent last, a video that paid time covers whole is never watermarked. cost.watermark on the job envelope says whether a particular job carries it, and renders.quote answers it before anything is started. |
The API surface
| Term | Definition |
|---|---|
| Operation | One thing this API can do, described once. The HTTP route, the MCP tool where an API key may call it, and the OpenAPI document all come from that one description, which is why they cannot disagree. There are 71 of them. |
| Actor | Who is calling, resolved from the credential before anything else happens. Two kinds: api_key, which carries exactly the scopes it was issued with, and user, a person signed in to the dashboard, which carries every scope. Some operations accept only one kind: keys.* and assistant.* are user only. |
| Scope | A permission a key carries, and a promise to the account about what a credential handed to somebody else can do. There are 14, and 2 of them can spend the account's seconds. An operation that declares two scopes needs both, never either. |
| Rate class | Which per minute budget an operation draws on, declared where the operation is described rather than decided by its verb: read 600, write 120, charge 20, expensive 20 a minute per credential. Each class is its own budget. |
| Job | Any piece of work that takes long enough to poll. There are 6 kinds, and every one of them answers the same envelope with the same 5 states: queued, running, succeeded, failed, cancelled. |
| Job envelope | The one shape a job is reported in: its state, how far it has got, what it cost, what it produced and how long to wait before asking again. Each kind has its own status words; the envelope is the single translation of all of them. |
| Artifact | A file a finished job produced, listed in result.artifacts with a type, a short lived signed URL, an expiry, a size and a sha256. Fetch the URL directly; bytes are never proxied through this API. |
| Idempotency key | A string you choose, up to 128 characters, that stands for one intent. Sent as the Idempotency-Key header on every mutating call, it guarantees that a retry returns the first answer instead of doing the work twice. Claims last 24 hours. |
| Replay | The stored answer to a request that was already made under this key, returned with Idempotent-Replayed: true. Same status, same body, same Location. Nothing new was created and nothing new was charged. |
| Cursor | An opaque string naming the last item of a page, sent back to get the next one. Pages are 1 to 100 rows, 20 by default on most lists and 100 on a few, and a nextCursor of null is the end of the walk. Do not parse one and never build one. |
| Request id | The id of one request, on every error body as requestId. It is the only handle support can trace a failure by, and it is the only way to find the original error message, which is logged and never sent. |
| Deprecation | An operation on its way out answers a Deprecation header and a Sunset header on every response, so a client that never reads these pages still finds out. The two use different date formats on purpose. |
Webhooks
| Term | Definition |
|---|---|
| Event | One terminal transition, announced to the endpoints that asked for it. There are 16 types and every name is a promise that never changes meaning. There is no event for queued or running: those are what GET is for. |
| Delivery | One attempt to post one event to one endpoint. Deliveries are at least once, with 6 attempts on an exponential backoff, so the same event id can arrive more than once. Dedupe on the event id, not on the delivery id. |
| Endpoint | An address you registered for us to post events to, with its own signing secret. The address is checked when you register it and again on every delivery attempt, and a delivery only goes to an address that passed the check. |
| Signing secret | The whsec_ value returned once when an endpoint is registered. Every delivery carries an HMAC over the timestamp and the raw body, keyed by it. Verify against the raw bytes, before anything parses them. |
MCP
| Term | Definition |
|---|---|
| MCP | The Model Context Protocol. GogoScreen runs a hosted server at https://api.gogoscreen.com/mcp, and a stdio bridge for hosts that cannot send a header. Both speak to the same operations with the same key. |
| MCP tool | One operation, as a tool an agent can call. The name is the operation id with dots replaced by underscores, so renders.create is renders_create. Path parameters are ordinary fields, the schema is strict, and every mutating tool takes an extra idempotencyKey because MCP has no headers. |
| Structured content | The tool result. It is the same body the HTTP operation returns, and the text block is that body as JSON. A refusal is isError: true with the same error envelope, so there is one vocabulary and not two. |