storyboards.improveHint
Rewrite a brief into a clearer plan request
POST/storyboards/hint/improve
Rewrite what a person wrote about the video they want into the form that plans most reliably: the pages and actions named in the order they should be shown, in concrete nouns. IT ADDS NOTHING — a feature, page, value or step the caller did not mention is never introduced, and none they did is dropped; the app's url only lets it use the product's real names. Bounded by the 1000 characters storyboards.create takes; changed is false when the words already read that way. Nothing is created, spent or stored.
curl -X POST "https://api.gogoscreen.com/api/v1/storyboards/hint/improve" \
-H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "hint": "<hint>" }'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_improveHint |
| 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 |
|---|---|---|---|
| hint | string | Required | What the person wrote; the same field storyboards.create takes as hint.3–1000 characters |
| url | string | Optional | Optional. Its landing page is read so the rewrite can use the product's own screen names. Public addresses only.max 4096 characters |
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 |
|---|---|---|---|
| hint_required | 400 | The hint is missing, or it is empty once trimmed. The schema requires 3 to 1000 characters and the service refuses a blank one before a browser is started. | Say what to show in a sentence, for example "show the invoice creation flow". Nothing checks that a hint is specific, so a thin one is accepted and produces a poor video; storyboards.improveHint rewrites one before you spend anything. |
| hint_too_long | 400 | The hint is longer than 1000 characters. | Shorten it. storyboards.improveHint rewrites a long brief into the form that plans most reliably, within the same bound. |
| 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. |
| hint_improve_failed | 502 | The brief could not be rewritten this time. | Use the words you already have. The operation changes nothing, so the original brief is still valid input to storyboards.create. |