storyboards.suggest

Five things to show

POST/storyboards/suggestions

Operation: storyboards.suggest
MCP tool: storyboards_suggest

Read the app's own landing page and answer five concrete briefs a demo video of it could be made from — the sort of sentence storyboards.create takes as its hint ("Show how an invoice is created and sent"), grounded in what the page really says. Nothing is created or spent, and the answer is cached for a day per site. If the site cannot be read or no suggestions can be made, the list is empty and reason says why, never an error: write your own hint when there are none. The page's words are data, not instructions.

curl -X POST "https://api.gogoscreen.com/api/v1/storyboards/suggestions" \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "<url>" }'

A request to this operation.

At a glance

Fact	Detail
Scopes	`storyboards:write`
Credentials	a signed in dashboard session or an API key.
Rate limit	20 requests a minute per credential, in the `expensive` class.
Idempotency	Not applicable. This operation changes nothing.
MCP tool	`storyboards_suggest`
Always sets	`Cache-Control: private, no-store`

Request body

A JSON body is required. Unknown fields are refused rather than ignored, so a typo is a 400 validation_failed rather than a setting that silently did nothing.

Name	Type	Required	Description
url	string	Required	The app's address, as `storyboards.create` takes it. Public only: a private or link-local address is refused by name and never fetched.max 4096 characters

Response

Answers 200. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

200 OK

Five things to show

200 OK body
Name	Type	Description
cached	boolean	True when this came from the day-long cache for this site.
reason	string \| null	Why the list is empty; null when it is not.one of: site_unreadable, site_empty, model_unavailable, model_unusable
suggestions	string[]	Up to five briefs, most obvious first. Empty when `reason` says why.

200 OK headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

Code	Status	When it happens	What to do
site_not_allowed	400	The website is a major public platform (a social network, search engine, marketplace or big portal) or a site about a sensitive topic (adult content, gambling, drugs, weapons, hate or violence). `details.reason` says which: `public_platform` or `sensitive_topic`. A sign-in address on a sensitive-topic site is refused too, and so is a sign-in that lands on a refused site.	Use your own product's website. No time was used. If you think your site was refused by mistake, write to support@gogoscreen.com or open a ticket with "Talk to a person": support can allow a site by name.
url_bare_host	400	The hostname has no dot, so it is a single label that would resolve through local search domains to something internal.	Use a full public hostname, for example https://example.com.
url_credentials	400	The address carried a username or a password in the URL, which would be logged and stored.	Remove them from the URL and use the `credentials` object, which is encrypted at rest, used once and deleted. When a storyboard is planned first, it is kept encrypted for that session and deleted at most two hours after its last use.
url_dns	400	The hostname could not be resolved.	Check the spelling and that the name is public. A name that only resolves inside your own network will never resolve here.
url_invalid	400	The address is not one this API will fetch, for a reason the more specific codes do not cover.	Send an absolute public http or https URL.
url_malformed	400	The address could not be parsed as a URL.	Send an absolute URL including the scheme.
url_private	400	The address resolves to a private, loopback, link local, carrier grade NAT or IPv4 mapped IPv6 address. This API will not fetch inside a network.	Point at a publicly reachable address. There is no way to opt out of this guard.
url_scheme	400	The address used a scheme other than http or https.	Use https.
validation_failed	400	The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.	Read `details.issues`. Each entry carries a `path`, a `message` and a machine readable `code`. Fix every named field and send the request again; the same body always fails the same way.
unauthorized	401	No credential was presented, or the key is unknown, revoked or expired, or an `X-API-Key` header carried something that is not an API key. `details.reason` says which.	Send `Authorization: Bearer gsk_live_…`. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in `Authorization`, never in `X-API-Key`.
forbidden_scope	403	The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. `keys.` and `assistant.` are user only and can never be called by a key.	`details.requiredScopes` and `details.missingScopes` name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When `details.allowedActors` is present, no key can call this operation at all.
not_found	404	No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.	Check the id. Do not treat this as a permissions problem.
payload_too_large	413	The request body is over the transport's limit: 256 kb over HTTP, 1 mb over MCP.	Send less. `details.limit` carries the limit. Version 1 has no upload operations, so a body this size is usually a mistake.
unsupported_media_type	415	The request carried a body whose `Content-Type` is not `application/json`, whose charset is not utf-8, or whose `Content-Encoding` this API does not decode. A body nobody can read would otherwise be silently discarded.	Send `Content-Type: application/json` and utf-8 bytes. `details` names the charset, encoding or content type that was objected to.
rate_limited	429	The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. `details.scope` is `minute`, `day` or `account`, or `global` when the product's own daily cap on voice previews is spent.	Wait the `Retry-After` seconds and retry. `details.limit` and `details.resetAt` say what was hit and when it reopens. The `RateLimit-*` headers on every answer let a client pace itself before it gets here.
internal_error	500	An unhandled failure inside this API. The original message is logged and never answered.	Retry once, then quote `requestId` to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.