Skip to main content
POST
Start Brand Extraction

Authorizations

Authorization
string
header
required

API key from Settings > Developer > REST API

Headers

Moda-Version
enum<string>
default:2026-05-01

Calendar-dated API version pin. New integrations should pin 2026-05-01 to opt into the newest response shapes. For back-compat the server also accepts requests with no header and resolves them to the current default (today: 2026-04-12); that default advances on each sunset date. Any unsupported value returns 400 unsupported_version.

Available options:
2026-04-12,
2026-05-01
Example:

"2026-05-01"

Body

application/json

Request body for POST /v1/brand-kits/extractions — read a website's brand, keep no kit.

url
string
required

Company website URL or domain, e.g. 'stripe.com'.

Required string length: 1 - 2048
idempotency_key
string | null

A retried start with the same key returns the first job instead of starting another. Same-key reuse with a different payload is a 409 idempotency_conflict.

Maximum string length: 200

Response

Successful Response

A website → brand extraction, as returned by start (202) and by the status poll.

job_id
string
required

Extraction job id; poll GET /v1/brand-kits/extractions/{job_id}.

status
enum<string>
required

queued → running → completed or failed. Only the last two are final.

Available options:
queued,
running,
completed,
failed
message
string
required

Human-readable progress or outcome.

error
string | null

Failure reason when status is failed.

code
string | null

Machine-readable failure when status is failed: scrape_failed (the site could not be read or yielded nothing), extraction_timeout or extraction_failed.

retry_after_seconds
integer | null

Suggested wait before the next poll; null once the job is final.

extraction
Extraction · object | null

The brand, once status is completed: company_name, company_url, company_description, tagline, brand_values, brand_tone_of_voice, colors, fonts, logos (each image with a file_id and a signed url), screenshot ({file_id, url, captured_at, source_url} or null) and personality ({tone, energy} or null) — the brand fields of a kit read, with no kit created. URLs are signed at each poll. The files are kept for 24 hours: a file_id attached to a brand kit in that window stays with the kit; any other stops resolving after it (URLs already signed keep working until they lapse).

replayed
boolean | null

true when an idempotency key replayed the first start.