> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tastelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract a brand

> How an extraction runs, from submission to result

A **submission** is one extraction job for a URL. You create it, the engine processes it asynchronously, and when it finishes it produces an extraction (referenced by `extraction_id`) whose output is the [design system](/concepts/design-system).

## Creating submissions

There are two ways to submit work:

* **Single URL**: [`POST /design/submissions`](/api-reference/endpoint/create-submission) with a `url`.
* **Map mode**: `POST /design/submissions?map=true` treats `url` as a domain root, discovers the site's pages, and submits each one as its own extraction. The response shape changes to reflect the multiple URLs discovered. Use `max_urls` to cap discovery; the server clamps it to **200**.

### Submission options

The single-URL request accepts a few options:

* **`force`**: re-run extraction even when a cached result exists.
* **`enable_deep_analysis`**: run additional, slower analysis steps for a higher-fidelity result.

## Status and progress

Each submission has a top-level `status`: `accepted`, `queued`, `crawling`, `extracting`, `completed` and `failed`

It also reports a finer-grained `current_step` as the workflow streams:

```
crawling → design_extract_ai → profiling → finalizing → persisting → completed | failed
```

Track progress with [`GET /design/submissions/{id}`](/api-reference/endpoint/get-submission) for a single submission, or [`GET /design/submissions`](/api-reference/endpoint/list-submissions) for a paginated list.

### Filtering the list

The list is deduplicated by URL and returns the newest submissions first. Narrow it with:

* **`status`**: one lifecycle status.
* **`q`**: free-text search over the source URL (a case-insensitive substring).
* **`api_key_id`**: only submissions created with one API key. Useful for separating environments that share an account.

Alongside the page, `total` counts everything matching the filter and `totals` breaks that down into `completed`, `failed`, and `in_progress`. The four in-progress statuses fold into `in_progress`, so the three buckets sum to `total`. Both counts ignore pagination, which makes them safe to render as a summary without walking every page.

Each item also reports `credits_consumed` (net of any refund) and `api_key_name`, so you can attribute spend without a second call.

## Polling for the result

Extraction is asynchronous, so poll [`GET /design/submissions/{id}/result`](/api-reference/endpoint/get-submission-result):

* **`200`**: may contain a partial `design_system` while the workflow runs. Keep polling until `status` is `completed` or `failed`.
* **`409` (`NOT_READY`)**: no checkpoint has landed yet. Retry shortly.
* **`404`**: the submission doesn't exist or isn't accessible to the caller.

Read `result.design_system` once `status` is `completed`. See [The design system](/concepts/design-system) for the structure.

The full design system is a large payload. Add `?sections=colors,typography` to return only the sections you need, which keeps polling responses small. See [Requesting only the sections you need](/concepts/design-system#requesting-only-the-sections-you-need).

## Downloading the whole extraction

An extraction is more than its design system: it also has the captured HTML and CSS, the screenshot, and every logo, image, and icon the design system references. [`GET /design/submissions/{id}/download`](/api-reference/endpoint/download-submission) returns a manifest listing all of them as one flat file tree, so you can write the extraction to disk in one pass.

Every entry has a relative `path` and exactly one source:

* **`content`**: inline text to write at that path. This is how `guidelines.json` (the design system) arrives.
* **`url`**: a file to download to that path, such as `crawl/html.html` or `crawl/screenshot.jpeg`.

Assets are mirrored to the engine's storage before the manifest is built, so the URLs keep working even after the origin site changes. The submission must be `completed`: an in-progress one returns `409 NOT_READY`. Like the result endpoint, authentication is optional, so a public extraction can be downloaded without a key.

## Caching and freshness

Results are cached and reused across submissions. When a request is served from a previous extraction for the URL, `cache_hit` is `true`.

To know when the data was actually extracted (its freshness), read `completed_at`. It is on the submission envelope, on [`GET /design/submissions/{id}`](/api-reference/endpoint/get-submission), the `/result` endpoint, and the list.

On a cache hit, `completed_at` points to the **original** extraction, not the time you sent the request, so a cached result may have been extracted earlier. On a fresh run, it is the moment the extraction just completed. While a submission is still running, `completed_at` is `null`.

Set `force: true` on the request to bypass the cache and run a fresh extraction. That fresh result then becomes the cached result other callers get for the URL.

## Visibility and sharing

By default a result is private to its owner. Use [`PATCH /design/submissions/{id}/visibility`](/api-reference/endpoint/update-visibility) with `{ "is_public": true }` to make it public. Public results can be read from `GET /design/submissions/{id}/result` without authentication, which makes extractions shareable. Only the owner can change visibility.