---
title: "Start a marketing project"
method: POST
path: "/marketing/projects"
tags: ["marketing"]
---

# Start a marketing project

`POST /marketing/projects`

## Request

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

Make an editable marketing video from something this account already has: a finished WALKTHROUGH render (`renderId`), or a scanned WEBSITE (`source`). The project opens at its first revision, which you can rework with `marketing.revisions.create` and cut with `marketing.exports.create`. Nothing is charged here — the export is what spends video time. A walkthrough project needs its render's clean source to still be kept; 409 `source_not_ready` says it is not.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `durationSeconds` integer: The length the first revision opens at. Must be one the design offers, from `catalog.marketing.templates.list`; the six-second edition is retired and is refused here.
  - `format` 'portrait' | 'landscape' | 'square' | 'four-five', required
  - `renderId` string, uuid: A finished walkthrough render of this account's. Exclusive with `source`.
  - `review` object: Website projects only: the approved copy and scene choices.
  - `source` object: A scanned website this project is made from. Exclusive with `renderId`.
    - `kind` 'website', required: Always `website`. The only source kind this field takes.
    - `manifestHash` string: The manifest's sha256, as `marketing.sources.get` answers it. Pins the exact scan this was planned against.
    - `sourceId` string, uuid, required: The `id` of a scanned source from `marketing.sources.list`.
    - `version` integer, required: Which manifest version of that source — `marketing.sources.get` answers the current one.
  - `templateId` string, required: A design id from catalog.marketing.templates.list.
  - `title` string

## Response `201`

Start a marketing project

- object
  - `project` object, required
    - `createdAt` string, date-time, nullable, required
    - `currentRevisionId` string, nullable, required
    - `id` string, required
    - `marketingSourceId` string, nullable, required
    - `sourceKind` 'walkthrough' | 'website', required
    - `sourceRenderId` string, nullable, required
    - `status` string, required
    - `templateId` string, required
    - `templateVersion` string, required
    - `title` string, required
    - `updatedAt` string, date-time, nullable, required
  - `revision` object, nullable, required
    - `createdAt` string, date-time, nullable, required
    - `document` object, required: The revision's own document: the scenes, the copy, the music and the timing. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.
    - `id` string, required
    - `locks` object, required: The parts of this revision the customer has locked. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.
    - `number` number, required
    - `parentRevisionId` string, nullable, required
    - `projectId` string, required
    - `restoredFromRevisionId` string, nullable, required
    - `seed` number, required

## Other responses

- `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. · `unknown_template` — No such design. The catalogue is at GET /api/v1/catalog/marketing/templates. · `unsupported_format` — That design does not offer that shape. `details.formats` lists what it does. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `invalid_revision` — That revision is not valid. `details.errors` says why. · `expected_revision_required` — Name the revision you are changing, so a save cannot land on words you never saw. · `edit_not_understood` — That change was not understood whole, so nothing was changed. `details` says why and what this editor does take.
- `401`: `unauthorized` — Authentication is required.
- `403`: `forbidden_scope` — This credential does not carry the scope this operation needs.
- `404`: `not_found` — No such resource. · `source_not_found` — No such source. · `source_version_not_found` — No such version of that website source.
- `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. · `source_not_ready` — That source is not ready to be used yet. · `source_unreadable` — That source could not be read. · `missing_required_footage` — That design needs footage this recording does not have. `details.reasons` says which. · `revision_conflict` — That revision is no longer the project's current one. · `export_in_flight` — An export of that project is still running. · `gallery_example` — One of that project's exports is published as a gallery example. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source.
- `410`: `source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted.
- `413`: `payload_too_large` — That request body is too large.
- `415`: `unsupported_media_type` — That content type is not supported.
- `422`: `campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place.
- `429`: `rate_limited` — Too many requests. Try again shortly.
- `500`: `internal_error` — Something went wrong. Try again.
- `503`: `storage_unavailable` — File storage is temporarily unavailable.

---

[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)