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

# Introduction

> Authenticate and call the Taste Engine Design API

The Taste Engine Design API extracts a structured design system from any website. You submit a URL, the engine crawls and analyzes the page, and you retrieve a design system describing its colors, typography, spacing, and components, plus the raw artifacts used to produce it.

When you don't have a URL yet, the [search endpoints](/concepts/brand-search) work the other way round: describe an aesthetic and get back matching brands from the corpus. And once you have built something, the [brand-adherence endpoints](/concepts/brand-adherence) score how well it follows the reference brand.

Each endpoint group is powered by one of three subsystems: the **Extractor**, the **Search**, and the **Verifier**. See [How the engine works](/concepts/architecture) for what runs behind each group.

## Base URL

All endpoints are served from a single base URL:

```
https://api.tastelabs.com
```

## Authentication

Every request is authenticated with an API key sent in the `X-API-Key` header:

```bash theme={null}
curl https://api.tastelabs.com/design/me \
  -H "X-API-Key: your-api-key"
```

Create an API key directly in the [Engine dashboard](https://engine.tastelabs.com/app/api-keys).

<Note>
  `GET /design/submissions/{id}/result`, `GET /design/submissions/{id}/download`, and `GET /judge/brand-adherence/{job_id}/result` are the only endpoints where authentication is optional. With a valid key, you can read your own private results; without one, only results that have been made public are returned.
</Note>

A key may also carry an optional expiration date. An expired or invalid key returns `401 UNAUTHORIZED`. See [Authentication](/concepts/authentication) for the full model.

## Errors

Errors nest a consistent envelope under `detail`, with a machine-readable `error` code and a human-readable `message`:

```json theme={null}
{
  "detail": {
    "error": "NOT_FOUND",
    "message": "Submission not found."
  }
}
```

| Status | Code           | Meaning                                                           |
| ------ | -------------- | ----------------------------------------------------------------- |
| 401    | `UNAUTHORIZED` | The API key is missing, invalid, or expired.                      |
| 403    | `FORBIDDEN`    | The key is valid but is not allowed to call this endpoint.        |
| 404    | `NOT_FOUND`    | The resource was not found or is not accessible.                  |
| 409    | `NOT_READY`    | The result is not ready yet. Keep polling.                        |
| 422    | (validation)   | The request payload failed validation. `detail` lists the issues. |
| 500    |                | An unexpected server error occurred. The body is plain text.      |
| 502    |                | A search failed. The credit is refunded, so retrying is safe.     |
| 503    |                | Search is at capacity. Retry after the `Retry-After` header.      |

For polling guidance and the full breakdown, see [Errors & status codes](/concepts/errors).

## Typical flow

Extraction runs asynchronously. Submit a URL, then poll the result endpoint until the job finishes.

<Steps>
  <Step title="Submit a URL">
    Call [`POST /design/submissions`](/api-reference/endpoint/create-submission) with the URL to extract. You receive a `submission_id` and a `202 Accepted` response.

    ```bash theme={null}
    curl -X POST https://api.tastelabs.com/design/submissions \
      -H "X-API-Key: your-api-key" \
      -H "Content-Type: application/json" \
      -d '{"url": "https://stripe.com"}'
    ```
  </Step>

  <Step title="Poll for the result">
    Call [`GET /design/submissions/{id}/result`](/api-reference/endpoint/get-submission-result) until the status is `completed` or `failed`. While the job runs you may receive a `200` with a partial result, or a `409 NOT_READY` before the first checkpoint lands.

    ```bash theme={null}
    curl https://api.tastelabs.com/design/submissions/SUBMISSION_ID/result \
      -H "X-API-Key: your-api-key"
    ```
  </Step>

  <Step title="Read the design system">
    On success, `result.design_system` contains the extracted design system and `result.artifacts` links to the captured source artifacts.
  </Step>
</Steps>

## Learn more

<CardGroup cols={2}>
  <Card title="Extract a brand" icon="arrows-rotate" href="/concepts/submissions">
    Statuses, polling, caching, and map mode.
  </Card>

  <Card title="The design system" icon="swatchbook" href="/concepts/design-system">
    The structure of `result.design_system`.
  </Card>

  <Card title="Brand search" icon="magnifying-glass" href="/concepts/brand-search">
    Find brands by aesthetic or by similarity, synchronously.
  </Card>

  <Card title="Brand adherence" icon="scale-balanced" href="/concepts/brand-adherence">
    Score how well a page follows a reference brand.
  </Card>
</CardGroup>

<Tip>
  Need help or a higher rate limit? Reach out at [support@thetaste.ai](mailto:support@thetaste.ai).
</Tip>