marketing.revisions.create
Rework a project
POST/marketing/projects/{id}/revisions
Save a new version of a project: different words, different scenes, different music, a different speed or look, or a restore of an earlier version. expectedRevisionId is a compare-and-set against the project's CURRENT revision — if somebody else saved in the meantime it is 409 revision_conflict with the id that won, and nothing is written. Parts the customer has locked are not moved by a re-plan. Every version is kept, so every change is undoable.
curl -X POST "https://api.gogoscreen.com/api/v1/marketing/projects/<id>/revisions" \
-H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "expectedRevisionId": "<expectedRevisionId>" }'At a glance
| Fact | Detail |
|---|---|
| Scopes | marketing:write |
| Credentials | a signed in dashboard session or an API key. |
| Rate limit | 120 requests a minute per credential, in the write class. |
| Idempotency | Required. Send an Idempotency-Key header; a retry with the same key and the same body returns the stored answer with Idempotent-Replayed: true. How idempotency works. |
| MCP tool | marketing_revisions_create |
| Always sets | Cache-Control: private, no-store |
| Verified email | Required. An account whose email address is not verified meets 403 email_unverified before the operation runs. |
| Marketing videos | Required. An account without marketing videos enabled meets 403 feature_disabled before the operation runs. |
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 |
|---|---|---|---|
| expectedRevisionId | string | Required | The revision you are changing. A compare-and-set: 409 if it is no longer current.format: uuid |
| copy | object | Optional | The words, by role.any keys |
| locks | object | Optional | The parts to pin against a re-plan.any keys |
| music | object | Optional | any keys |
| narration | object | boolean | null | Optional | |
| restoreRevisionId | string | Optional | Restore an earlier version as a NEW one; the history is never rewritten.format: uuid |
| scenes | object | Optional | Which picture fills which slot.any keys |
| speed | number | Optional | at most 4; greater than 0 |
| style | object | Optional | any keys |
201 Created
Rework a project
| Name | Type | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| currentRevisionId | string | |||||||||||||||||||||||||||||||
| revision | object | |||||||||||||||||||||||||||||||
9 fields inside revision
| ||||||||||||||||||||||||||||||||
| Header | Meaning |
|---|---|
Cache-Control | Always private, no-store. |
Idempotent-Replayed | Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done. |
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 |
|---|---|---|---|
| edit_not_understood | 400 | A sentence sent to the deterministic editor was not understood whole. Nothing is half applied, so the project is unchanged. | details says why, and names the vocabulary the editor does take. Rewrite the sentence within it, or make the change with marketing.revisions.create instead. |
| expected_revision_required | 400 | A save arrived without expectedRevisionId, so it could have landed on words the caller never saw. | Read the project, send its current revision id as expectedRevisionId, and handle revision_conflict when somebody else saved first. |
| idempotency_key_required | 400 | A mutating operation arrived over HTTP with no Idempotency-Key header. It is refused before the body is parsed, so a caller missing both learns about both at once. | Add an Idempotency-Key header of up to 128 characters, unique to this request. Over MCP the same value goes in the idempotencyKey tool argument. |
| invalid_revision | 400 | The revision document sent does not satisfy the design it names. | details.errors says why. Fix each one and save again. |
| unknown_template | 400 | The marketing design named does not exist. | Read GET /catalog/marketing/templates and send an id it lists. |
| unsupported_duration | 400 | The design does not offer that length. | details.durations lists what it does offer. Pick one of those. |
| unsupported_format | 400 | The design does not offer that shape. | details.formats lists what it does offer. Pick one of those. |
| 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. |
| source_not_found | 404 | No website source of that id belongs to this account. | Check the id. A source belonging to another account answers the same way. |
| source_version_not_found | 404 | No such version of that website source. | Read the source to see which versions exist, then name one of those. |
| conflict | 409 | The request conflicts with the state the resource is in, and no more specific code applies. | Re-read the resource and decide from its current state. Retrying the same request unchanged will not help. |
| export_in_flight | 409 | A project delete or another export was asked for while an export of that project is still running. | Wait for it, or cancel it with marketing.exports.cancel, then retry. |
| gallery_example | 409 | A project delete was asked for while one of its exports is published as a gallery example. | Nothing a caller can change. Ask support to unpublish the example first. |
| idempotency_conflict | 409 | That idempotency key has already been used on this operation with a different request body. | Use a fresh key for a different request. A key stands for one intent, not for one attempt. |
| idempotency_in_progress | 409 | The first request under that key is still being worked. Two concurrent identical requests both reach the store and one of them is told this. | Wait the Retry-After seconds, which is 2, and send exactly the same request again with the same key. Do not change the body and do not mint a new key. |
| missing_required_footage | 409 | The design needs footage the recording this project was made from does not have. | details.reasons says which. Choose a design that fits the recording, or make a recording that covers the missing beats. |
| revision_conflict | 409 | expectedRevisionId is no longer the project's current revision, so somebody else saved first. Nothing was written. | details.currentRevisionId is the revision that won. Re-read the project, rebase the change on it, and save again. |
| source_kind_mismatch | 409 | The project was made from a different kind of source than the one being used, for example a walkthrough render where a scanned website is expected. | Use the source the project was built from, or start a new project of the right kind. |
| source_not_ready | 409 | The source has not published a manifest yet, or a walkthrough project's render no longer has its clean source kept. | Poll the source until state is succeeded. For a walkthrough project, make the render again. |
| source_unreadable | 409 | The scanned website could not be read: it answered nothing usable, or its content was empty. | Check the address loads in a browser without a sign in, then scan again. |
| source_version_mismatch | 409 | The version named belongs to a different website source. | Send a version number from the source you are naming. |
| source_deleted | 410 | The website source has been deleted. It still reads state: "cancelled". | Scan the site again with marketing.sources.create. |
| source_expired | 410 | The website source is past its retention window. | Scan the site again. Projects already built from it keep the version they were built from. |
| source_version_expired | 410 | That manifest version has been cleaned up. | Scan the site again and build from the new version. |
| 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. |
| campaign_copy_overflow | 422 | Words sent for a marketing scene do not fit the frame the design draws them in. The fit is measured, not guessed. | Shorten the fields details.fields names, then send the revision again. marketing.generations.preflight answers the same refusal before anything is created. |
| campaign_logo_aspect_unsupported | 422 | The logo's aspect ratio is not one any design can place. | Supply a logo closer to square or to a standard wordmark shape. |
| campaign_speed_breaks_music_ending | 422 | At the revision's saved playback speed the music would no longer end with the film. | details.missing says what to put right. Save a new revision at a speed the music bed can end on, then export that. |
| campaign_speed_breaks_narration_fit | 422 | At the revision's saved playback speed a spoken line would no longer fit the shot it belongs to. | details.missing says what to put right. Shorten the line or save the revision at a slower speed, then export that. |
| campaign_visuals_insufficient | 422 | The design needs more pictures than the scanned source has. | details says how many are needed and which scenes are short. Scan a richer page, refresh the source, or choose a design with fewer picture slots. |
| 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. |
| storage_unavailable | 503 | File storage could not be reached, so no signed URL could be created. | Back off and retry. The file itself is unaffected. |