MOmoda
brand-kits

Start Brand Extraction

Changed on

Read a website's brand in the background WITHOUT creating a brand kit.

For callers that keep the kit themselves and use Moda only to extract it. Runs the same extraction as POST /v1/brand-kits with url (15-32 s cold), so it is a job: 202 with a job_id now, then poll GET /v1/brand-kits/extractions/{job_id} until status is completed (the brand rides along as extraction) or failed. Nothing is added to the team's brand kits, drive or library. The logo and screenshot files are kept for 24 hours so their URLs can be served: attach a file_id to a kit in that window (logo_file_ids on create, or POST /v1/brand-kits/{id}/images) and the kit keeps the file. Otherwise the file_id stops resolving after that; URLs already signed keep working until they lapse, so download what you keep. Needs brand_kits:write because it spends the extraction. Honors idempotency_key. Not metered.

post/brand-kits/extractions

Request

  • Base URL
    https://api.moda.app/v1
  • URL
    https://api.moda.app/v1/brand-kits/extractions
  • Auth
    HTTP bearer

Headers

Moda-Version'2026-04-12' | '2026-05-01'
Example: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.

Request body

urlstring required

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

idempotency_keystring nullable

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.

Response

Successful Response

job_idstring required

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

status'queued' | 'running' | 'completed' | 'failed' required

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

messagestring required

Human-readable progress or outcome.

errorstring nullable

Failure reason when status is failed.

codestring nullable

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_secondsinteger nullable

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

extractionobject nullable

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

replayedboolean nullable

true when an idempotency key replayed the first start.

Changes