marketing.sources.create

Scan a website

POST/marketing/sources

Operation: marketing.sources.create
MCP tool: marketing_sources_create

Read a public website and keep what it found — the pages, the words and the pictures — as a versioned manifest a marketing video can be built from. Scanning costs no video time; the EXPORT is what charges. Answers 202 with a Location pointing at the source; poll it until state is terminal, then marketing.generations.create to turn it into a project. One scan at a time per account.

curl -X POST "https://api.gogoscreen.com/api/v1/marketing/sources" \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "url": "<url>" }'

A request to this operation.

At a glance

Fact	Detail
Scopes	`marketing:write`
Credentials	a signed in dashboard session or an API key.
Rate limit	20 requests a minute per credential, in the `expensive` 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`. The key is also written to the record this creates, so a retry cannot leave two behind. How idempotency works.
Long work	Answers `202` and queues a `marketing.source_scan`. Poll `/marketing/sources/{id}` until `state` is terminal, or subscribe to a webhook. This kind can be cancelled while it runs. Jobs and polling.
MCP tool	`marketing_sources_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
url	string	Required	The website to read. Public addresses only.max 4096 characters
demo	object	Optional	A demo account to sign in with, so the scan can see pages behind a login: { loginUrl, username, password, targetUrls[] }. Encrypted at rest and deleted after the scan.any keys

Response

This operation documents 2 success statuses. A first call answers 202. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

200 OK

The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.

200 OK body
Name	Type	Description
created	boolean
dispatched	boolean	Whether the job has started. False means it is accepted and will start shortly; it is not a failure.
operationId	string	The scan attempt. Poll the SOURCE, not this: a source has many scans and one current manifest.
resource	object	any keys

200 OK headers
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.

202 Accepted

The work was queued. Poll the resource at Location. A retry with the same Idempotency-Key answers this again, with the same body and the same Location, plus Idempotent-Replayed: true.

202 Accepted body
Name	Type	Description
created	boolean
dispatched	boolean	Whether the job has started. False means it is accepted and will start shortly; it is not a failure.
operationId	string	The scan attempt. Poll the SOURCE, not this: a source has many scans and one current manifest.
resource	object	any keys

202 Accepted headers
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.
`Location`	Where to read this marketing.source_scan, e.g. `/api/v1/marketing/sources/{id}`. Present on the replay too.

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
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.
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.
source_refresh_url_mismatch	400	A refresh named a different address from the one the source was created with. Allowing it would silently replace a customer's site with another.	Refresh with the original address, or create a new source for the new one.
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.
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.
website_demo_invalid	400	The demo login sent with a scan is not a valid shape.	Send a username, a password and the login page address together, or none of them.
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_owner_not_found	404	The account a scan is being run for does not exist.	Nothing a caller can change. Quote `requestId` to support.
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.
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.
source_export_in_flight	409	A source delete was asked for while an export is still being cut from one of its versions.	Cancel the export, then delete the source.
source_idempotency_conflict	409	That idempotency key was already used on this account with a different scan.	Use a fresh key for a different scan.
source_inspection_busy	409	A scan is already running on this account. One at a time.	Poll the running scan until its state is terminal, or cancel it, then start the new one.
source_inspection_stopping	409	A scan is still shutting down after a cancel.	Wait a moment and try again.
source_owner_unavailable	409	The account cannot start new work, because it is blocked or scheduled for deletion.	Resolve the account's state, then retry.
source_deleted	410	The website source has been deleted. It still reads `state: "cancelled"`.	Scan the site again with `marketing.sources.create`.
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.