### Preview and install individual skills with npx skills add

Source: https://docs.tastelabs.com/ai-tools/skills

Shows variations of the skills CLI: previewing skills with --list and installing a single skill by path for brand-search or brand-adherence.

```bash
# Preview the skills in the repo before installing
npx skills add Taste-AI/skills --list

# Install a single skill by path
npx skills add github.com/Taste-AI/skills/tree/main/skills/brand-search
npx skills add github.com/Taste-AI/skills/tree/main/skills/brand-adherence
```

--------------------------------

### Install both skills with npx skills add

Source: https://docs.tastelabs.com/ai-tools/skills

Installs both the brand-search and brand-adherence skills into every coding agent the CLI detects on your machine. Run via npx, no global install needed.

```bash
# Install both skills into every coding agent the CLI detects on your machine
npx skills add Taste-AI/skills
```

--------------------------------

### Full example: search, extract, and read design system

Source: https://docs.tastelabs.com/use-cases/find-inspiration

This Python example uses the TasteLabs API to search for a look, submit the top result for extraction, and poll until the design system is ready. It requires an API key and uses the httpx library. The search query is 'dark brutalist developer tools' with depth 'fast' and top_k 6. The script prints each result's URL and identity paragraph, then prints the brand name from the extracted design system.

```python
import httpx
import time

API_KEY = "your-api-key"
BASE = "https://api.tastelabs.com"
HEADERS = {"X-API-Key": API_KEY}

search = httpx.post(
    f"{BASE}/search",
    headers=HEADERS,
    json={"query": "dark brutalist developer tools", "depth": "fast", "top_k": 6},
)
search.raise_for_status()
cards = search.json()["results"]
for card in cards:
    print(card["url"], "-", card["identity_paragraph"][:80])

pick = cards[0]
submit = httpx.post(f"{BASE}/design/submissions", headers=HEADERS, json={"url": pick["url"]})
submit.raise_for_status()
submission_id = submit.json()["submission_id"]

while True:
    r = httpx.get(f"{BASE}/design/submissions/{submission_id}/result", headers=HEADERS)
    if r.status_code == 409:
        time.sleep(3)
        continue
    r.raise_for_status()
    body = r.json()
    if body["status"] in ("completed", "failed"):
        break
    time.sleep(3)

design_system = body["result"]["design_system"]
print(design_system["profile"]["brand_name"])
```

--------------------------------

### Insufficient credits error example

Source: https://docs.tastelabs.com/concepts/errors

Shows the error response for a 402 INSUFFICIENT_CREDITS, including the current balance and required amount.

```json
{
  "detail": {
    "error": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits for this request.",
    "balance": 0,
    "required": 1
  }
}
```

--------------------------------

### GET /design/me

Source: https://docs.tastelabs.com/api-reference/introduction

Example authentication request to the Taste Engine Design API. This endpoint is used to verify API key authentication.

```APIDOC
## GET /design/me

### Description
Example request to verify API key authentication.

### Method
GET

### Endpoint
https://api.tastelabs.com/design/me

### Authentication
API key required in the `X-API-Key` header.

### Request Example
```bash
curl https://api.tastelabs.com/design/me \
  -H "X-API-Key: your-api-key"
```

```

--------------------------------

### Extract a design system with Python (httpx)

Source: https://docs.tastelabs.com/quickstart

Python example using httpx to submit a URL, poll for the result, and print the brand name. Handles 409 NOT_READY responses and failed statuses.

```python
import httpx
import time

API_KEY = "your-api-key"
BASE = "https://api.tastelabs.com"
HEADERS = {"X-API-Key": API_KEY}

def extract_brand(url: str) -> dict:
    submit = httpx.post(f"{BASE}/design/submissions", headers=HEADERS, json={"url": url})
    submit.raise_for_status()
    submission_id = submit.json()["submission_id"]
    print(f"Submitted: {submission_id}")

    while True:
        r = httpx.get(f"{BASE}/design/submissions/{submission_id}/result", headers=HEADERS)
        if r.status_code == 409:
            time.sleep(3)
            continue
        r.raise_for_status()
        body = r.json()
        if body["status"] == "completed":
            return body["result"]["design_system"]
        if body["status"] == "failed":
            raise RuntimeError(body.get("error") or "Extraction failed")
        time.sleep(3)

design_system = extract_brand("https://stripe.com")
print(design_system["profile"]["brand_name"])
```

--------------------------------

### Extract a design system with TypeScript (fetch)

Source: https://docs.tastelabs.com/quickstart

TypeScript example using fetch to submit a URL, poll for the result, and print the brand name. Handles failed statuses and uses a 3-second polling interval.

```typescript
const API_KEY = "your-api-key";
const BASE = "https://api.tastelabs.com";

async function extractBrand(url: string) {
  const submit = await fetch(`${BASE}/design/submissions`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ url }),
  });
  const { submission_id } = await submit.json();
  console.log(`Submitted: ${submission_id}`);

  while (true) {
    const r = await fetch(`${BASE}/design/submissions/${submission_id}/result`, {
      headers: { "X-API-Key": API_KEY },
    });
    if (r.ok) {
      const body = await r.json();
      if (body.status === "completed") return body.result.design_system;
      if (body.status === "failed") throw new Error(body.error ?? "Failed");
    }
    await new Promise((res) => setTimeout(res, 3000));
  }
}

const ds = await extractBrand("https://stripe.com");
console.log(ds.profile.brand_name);
```

--------------------------------

### Manually copy skills to Claude Code and Codex directories

Source: https://docs.tastelabs.com/ai-tools/skills

Manual installation by copying skill folders into agent-specific skills directories. Shows commands for Claude Code (~/.claude/skills/) and Codex (~/.agents/skills/).

```bash
# Claude Code (project- or user-scoped)
cp -r skills/brand-search ~/.claude/skills/
cp -r skills/brand-adherence ~/.claude/skills/

# Codex
cp -r skills/brand-search ~/.agents/skills/
cp -r skills/brand-adherence ~/.agents/skills/
```

--------------------------------

### Check brand adherence with Python (httpx)

Source: https://docs.tastelabs.com/use-cases/brand-adherence

Python example using httpx to create a brand adherence job, poll until completion, and fetch the verdict. Requires an API key and uses the TasteLabs API endpoints. Prints the score and recommendations.

```python
import httpx
import time

API_KEY = "your-api-key"
BASE = "https://api.tastelabs.com"
HEADERS = {"X-API-Key": API_KEY}

def check_adherence(reference_url: str, source_url: str) -> dict:
    created = httpx.post(
        f"{BASE}/judge/brand-adherence",
        headers=HEADERS,
        json={"reference_url": reference_url, "source_url": source_url},
    )
    created.raise_for_status()
    job_id = created.json()["job_id"]
    print(f"Job created: {job_id}")

    while True:
        job = httpx.get(f"{BASE}/judge/brand-adherence/{job_id}", headers=HEADERS)
        job.raise_for_status()
        body = job.json()
        if body["status"] == "completed":
            break
        if body["status"] == "failed":
            raise RuntimeError(body.get("error") or "Adherence job failed")
        time.sleep(5)

    verdict = httpx.get(
        f"{BASE}/judge/brand-adherence/{job_id}/result", headers=HEADERS
    )
    verdict.raise_for_status()
    return verdict.json()

verdict = check_adherence("https://stripe.com", "https://staging.example.com")
print(f"Score: {verdict['score']:.2f}")
for item in verdict["recommendations"]:
    print(f"- {item}")
```

--------------------------------

### GET /submissions/{id}/download

Source: https://docs.tastelabs.com/api-reference/endpoint/download-submission

Downloads the bundle manifest for a completed submission. The submission must be completed; otherwise, a 409 NOT_READY error is returned. Authentication is optional.

```APIDOC
## GET /submissions/{id}/download

### Description
Downloads the bundle manifest for a completed submission. The submission must be completed; otherwise, a 409 NOT_READY error is returned. Authentication is optional.

### Method
GET

### Endpoint
/submissions/{id}/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The `submission_id` returned when the submission was created.

### Response
#### Success Response (200)
- **submission_id** (string) - The submission identifier.
- **extraction_id** (string or null) - The extraction identifier.
- **files** (array of SubmissionManifestEntry) - A flat list of the files that make up a completed extraction.
  - **path** (string) - Relative path to write the file to, e.g. `crawl/html.html`.
  - **url** (string or null, uri) - Download URL, for files stored as artifacts.
  - **content** (string or null) - Inline file contents, for files generated from the result.

#### Response Example
{
  "submission_id": "sub_2f9a1c7b",
  "extraction_id": "ext_8d3e5a10",
  "files": [
    {
      "path": "guidelines.json",
      "content": "{\n  \"profile\": { ... }\n}"
    },
    {
      "path": "crawl/html.html",
      "url": "https://storage.example.com/..."
    },
    {
      "path": "crawl/screenshot.jpeg",
      "url": "https://storage.example.com/..."
    }
  ]
}

#### Error Responses
- **404** - The resource was not found or is not accessible with these credentials.
  - Example: { "detail": { "error": "NOT_FOUND", "message": "Submission not found" } }
- **409** - The extraction has not completed yet. Keep polling.
  - Example: { "detail": { "error": "NOT_READY", "message": "Submission is extracting" } }
- **500** - An unexpected server error occurred. The body is plain text.
  - Example: Internal Server Error

### Security
- Optional: ApiKeyAuth (header: X-API-Key) or no authentication.
```

--------------------------------

### Error format example

Source: https://docs.tastelabs.com/concepts/errors

Shows the standard error envelope with a machine-readable error code and human-readable message.

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

--------------------------------

### GET /design/me

Source: https://docs.tastelabs.com/api-reference/endpoint/get-current-user

Returns the identity and role associated with the authenticated API key. Use this endpoint to verify the current user's details.

```APIDOC
## GET /design/me

### Description
Returns the identity and role associated with the authenticated API key.

### Method
GET

### Endpoint
/design/me

### Parameters
#### Headers
- **X-API-Key** (string) - Required - API key issued by the Taste Engine. Create one in the dashboard at https://engine.tastelabs.com/app/api-keys.

### Response
#### Success Response (200)
- **user_id** (string, uuid) - Required - The unique identifier of the user.
- **email** (string or null) - Optional - The email address of the user; null when authenticated with an API key.
- **role** (string or null) - Optional - The role of the user; null when authenticated with an API key.

#### Response Example
{
  "user_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "email": "you@example.com",
  "role": "user"
}

#### Error Responses
- **401 Unauthorized** - The API key is missing, invalid, or expired. Response body example: {"detail": {"error": "UNAUTHORIZED", "message": "Bearer token or X-API-Key required"}}
- **500 Internal Server Error** - An unexpected server error occurred. The body is plain text. Example: "Internal Server Error"
```

--------------------------------

### Check brand adherence with TypeScript (fetch)

Source: https://docs.tastelabs.com/use-cases/brand-adherence

TypeScript example using fetch to create a brand adherence job, poll until completion, and fetch the verdict. Requires an API key and uses the TasteLabs API endpoints. Logs the score and recommendations.

```typescript
const API_KEY = "your-api-key";
const BASE = "https://api.tastelabs.com";
const HEADERS = { "X-API-Key": API_KEY, "Content-Type": "application/json" };

async function checkAdherence(referenceUrl: string, sourceUrl: string) {
  const created = await fetch(`${BASE}/judge/brand-adherence`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ reference_url: referenceUrl, source_url: sourceUrl }),
  });
  const { job_id } = await created.json();
  console.log(`Job created: ${job_id}`);

  while (true) {
    const job = await fetch(`${BASE}/judge/brand-adherence/${job_id}`, {
      headers: HEADERS,
    });
    const body = await job.json();
    if (body.status === "completed") break;
    if (body.status === "failed") throw new Error(body.error ?? "Failed");
    await new Promise((res) => setTimeout(res, 5000));
  }

  const verdict = await fetch(`${BASE}/judge/brand-adherence/${job_id}/result`, {
    headers: HEADERS,
  });
  return verdict.json();
}

const verdict = await checkAdherence(
  "https://stripe.com",
  "https://staging.example.com"
);
console.log(`Score: ${verdict.score}`);
for (const item of verdict.recommendations) console.log(`- ${item}`);
```

--------------------------------

### GET /design/submissions/{id}/download

Source: https://docs.tastelabs.com/api-reference/endpoint/download-submission

Downloads the submission bundle for a completed extraction. Returns a manifest of all files, including guidelines.json, HTML, CSS, screenshot, and referenced assets. Authentication is optional, and the submission must be completed.

```APIDOC
## GET /design/submissions/{id}/download

### Description
Returns a manifest of every file that makes up a completed extraction, so you can save the whole thing to disk: `guidelines.json` (the design system, inline in `content`), the captured HTML, CSS, and screenshot, and the logos, media, and icons referenced by the design system.

Each entry names a relative `path` and carries either inline `content` or a `url` to download. Assets are mirrored to the engine's own storage first, so the URLs stay valid even when the origin site changes.

### Method
GET

### Endpoint
/design/submissions/{id}/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the submission.

### Response
#### Success Response (200)
Returns a manifest of files. Each entry contains:
- **path** (string) - Relative path of the file.
- **content** (string) - Inline content of the file (e.g., for guidelines.json).
- **url** (string) - URL to download the file (for assets).

#### Response Example
{
  "files": [
    {
      "path": "guidelines.json",
      "content": "{ ... }"
    },
    {
      "path": "screenshot.png",
      "url": "https://storage.tastelabs.com/..."
    }
  ]
}

### Error Handling
- **409 NOT_READY** - Returned if the submission is not yet completed.
```

--------------------------------

### GET /search/similar

Source: https://docs.tastelabs.com/api-reference/endpoint/find-similar-brands

Returns brands from the corpus that look like one of your completed extractions, as the same result cards as POST /search. Runs synchronously, consumes credits, and requires a completed submission.

```APIDOC
## GET /search/similar

### Description
Returns brands from the corpus that look like one of your completed extractions, as the same result cards as POST /search. Runs synchronously, consumes credits, and requires a completed submission.

### Method
GET

### Endpoint
https://api.tastelabs.com/search/similar

### Parameters
#### Query Parameters
- **submission_id** (string) - Required - A completed submission of yours whose visual neighbours you want.
- **top_k** (integer) - Optional - Maximum number of results to return. Minimum: 1, Maximum: 30, Default: 18.

### Response
#### Success Response (200)
- **results** (array) - Nearest visual neighbours, closest first. Each item is a BrandSearchCard.

#### Response Example
{
  "results": [
    {
      "brand": "example-brand",
      "score": 0.95
    }
  ]
}

#### Error Responses
- **401** - Unauthorized
- **402** - Insufficient Credits
- **404** - No completed extraction for that submission.
- **500** - Internal Error
- **502** - Search Failed
```

--------------------------------

### GET /search/submissions

Source: https://docs.tastelabs.com/api-reference/endpoint/list-searches

Returns your past searches and similarity lookups, newest first. Free: listing history costs no credits. Search results themselves are not stored, only the request and its outcome.

```APIDOC
## GET /search/submissions

### Description
Returns your past searches and similarity lookups, newest first. Free: listing history costs no credits. Search results themselves are not stored, only the request and its outcome.

### Method
GET

### Endpoint
https://api.tastelabs.com/search/submissions

### Parameters
#### Query Parameters
- **kind** (string) - Optional - Filter to query searches or similarity lookups. Enum: search, similar.
- **status** (string) - Optional - Filter by outcome. Enum: completed, failed, in_progress.
- **depth** (string) - Optional - Filter query searches by depth. Enum: fast, deep.
- **q** (string) - Optional - Free-text filter over the query text.
- **api_key_id** (string) - Optional - Only searches made with one API key. Useful for separating environments that share an account.
- **limit** (integer) - Optional - Maximum number of searches to return. Minimum: 1, Maximum: 100, Default: 20.
- **offset** (integer) - Optional - Number of searches to skip, for pagination. Minimum: 0, Default: 0.

### Response
#### Success Response (200)
- **submissions** (array) - Past searches, newest first.
- **total** (integer) - Total searches matching the filter, ignoring pagination.
- **total_by_status** (object) - Counts by outcome under the other filters, ignoring pagination, so a status picker can label its options.
- **limit** (integer) - Maximum number of searches returned.

#### Response Example
{
  "submissions": [],
  "total": 0,
  "total_by_status": {},
  "limit": 20
}

#### Error Responses
- **401** - Unauthorized
- **500** - Internal Error
```

--------------------------------

### Request design system sections with curl

Source: https://docs.tastelabs.com/concepts/design-system

Use the `sections` query parameter with `GET /design/submissions/{id}/result` to retrieve only the design system sections you need. The parameter accepts a comma-separated list; repeating the parameter overrides the previous value. A section name not in the allowed list returns a 422 error.

```bash
curl "https://api.tastelabs.com/design/submissions/SUBMISSION_ID/result?sections=colors,typography" \
  -H "X-API-Key: your-api-key"
```

--------------------------------

### OpenAPI definition for Get submission

Source: https://docs.tastelabs.com/api-reference/endpoint/get-submission

The OpenAPI specification for the GET /design/submissions/{id} endpoint, detailing the request parameters, response schemas, and error handling.

```yaml
openapi: 3.1.0
info:
  title: Taste Engine Design API
  version: 1.0.0
  description: >-
    Public REST API for the Taste Engine. Submit a URL, extract a structured
    design system from any website, search the brand corpus by aesthetic, and
    ground prompts in real brand profiles.


    All requests are authenticated with an API key sent in the `X-API-Key`
    header. Create one directly in the Engine dashboard at
    https://engine.tastelabs.com/app/api-keys.
  contact:
    name: Taste Engine Support
    email: support@thetaste.ai
servers:
  - url: https://api.tastelabs.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Account
    description: Identity of the authenticated API key holder.
  - name: Submissions
    description: >-
      Create and track extraction jobs, then retrieve the resulting design
      system.
  - name: Prompts
    description: Rewrite prompts grounded in an extracted brand profile.
  - name: Search
    description: >-
      Find brands in the curated corpus by describing an aesthetic, or by
      similarity to one of your own extractions.
  - name: Brand adherence
    description: >-
      Judge how well a page adheres to a reference site's brand: submit a pair
      of URLs, poll the job, then read the verdict.
paths:
  /design/submissions/{id}:
    get:
      tags:
        - Submissions
      summary: Get submission
      description: >-
        Returns the current status of a single submission, including which step
        it is on.
      operationId: getSubmission
      parameters:
        - $ref: '#/components/parameters/SubmissionId'
      responses:
        '200':
          description: The submission status view.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    SubmissionId:
      name: id
      in: path
      required: true
      description: The `submission_id` returned when the submission was created.
      schema:
        type: string
  schemas:
    Submission:
      type: object
      description: Status view of a single submission.
      properties:
        submission_id:
          type: string
        status:
          $ref: '#/components/schemas/SubmissionStatus'
        source_url:
          type: string
          format: uri
        current_step:
          type: string
          description: Name of the step currently running.
        step_started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        cache_hit:
          type: boolean
          description: >-
            Whether the result was served from cache. When `true`,
            `completed_at` reflects the original extraction, not this request.
        extraction_id:
          type:
            - string
            - 'null'
        accepted_at:
          type: string
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the extraction completed: the freshness of the result. On a
            cache hit (`cache_hit` is `true`) this is the original extraction,
            not the current request, so it may predate this request. `null`
            while the submission is still running.
        error:
          type:
            - string
            - 'null'
          description: Error message when status is `failed`.
        credits_consumed:
          type:
            - integer
            - 'null'
          description: >-
            Net credits this submission consumed. `null` when metering was off,
            and `0` once a failed submission has been refunded.
        credit_ref_id:
          type:
            - string
            - 'null'
          description: Reference to the credit charge for this submission.
        api_key_name:
          type:
            - string
            - 'null'
          description: >-
            Name of the API key that created the submission. `null` for
            dashboard submissions and when metering was off at submission time.
        batch_id:
          type:
            - string
            - 'null'
          description: Identifier of the batch run this submission belongs to.
        batch_label:
```

--------------------------------

### OpenAPI specification for GET /judge/brand-adherence/{job_id}

Source: https://docs.tastelabs.com/api-reference/endpoint/get-brand-adherence-job

YAML OpenAPI 3.1.0 specification for the endpoint. Defines the GET operation, parameters, response schemas, and security requirements. Use this to generate client code or documentation.

```yaml
openapi: 3.1.0
info:
  title: Taste Engine Design API
  version: 1.0.0
  description: >-
    Public REST API for the Taste Engine. Submit a URL, extract a structured
    design system from any website, search the brand corpus by aesthetic, and
    ground prompts in real brand profiles.


    All requests are authenticated with an API key sent in the `X-API-Key`
    header. Create one directly in the Engine dashboard at
    https://engine.tastelabs.com/app/api-keys.
  contact:
    name: Taste Engine Support
    email: support@thetaste.ai
servers:
  - url: https://api.tastelabs.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Account
    description: Identity of the authenticated API key holder.
  - name: Submissions
    description: >-
      Create and track extraction jobs, then retrieve the resulting design
      system.
  - name: Prompts
    description: Rewrite prompts grounded in an extracted brand profile.
  - name: Search
    description: >-
      Find brands in the curated corpus by describing an aesthetic, or by
      similarity to one of your own extractions.
  - name: Brand adherence
    description: >-
      Judge how well a page adheres to a reference site's brand: submit a pair
      of URLs, poll the job, then read the verdict.
paths:
  /judge/brand-adherence/{job_id}:
    get:
      tags:
        - Brand adherence
      summary: Get brand-adherence job
      description: >-
        Returns the live status of a brand-adherence job. `status` advances
        through `accepted`, `extracting`, and `judging` before reaching
        `completed` or `failed`; `current_step` names the pipeline stage in
        progress.


        Poll this endpoint, then read the verdict from `GET
        /judge/brand-adherence/{job_id}/result` once `status` is `completed`. On
        `failed`, `error` carries the reason.
      operationId: getBrandAdherenceJob
      parameters:
        - $ref: '#/components/parameters/AdherenceJobId'
      responses:
        '200':
          description: The job's status view.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdherenceJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    AdherenceJobId:
      name: job_id
      in: path
      required: true
      description: >-
        Brand-adherence job identifier, as returned by `POST
        /judge/brand-adherence`.
      schema:
        type: string
  schemas:
    AdherenceJob:
      type: object
      description: Status view of a single brand-adherence job.
      properties:
        job_id:
          type: string
        user_id:
          type: string
        status:
          $ref: '#/components/schemas/AdherenceStatus'
        reference_url:
          type: string
          format: uri
        source_url:
          type: string
          format: uri
        current_step:
          type:
            - string
            - 'null'
          description: >-
            Name of the pipeline stage currently running, e.g.
            `waiting_for_extractions`, `judging_scene`.
        step_started_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        cache_hit:
          $ref: '#/components/schemas/AdherenceCacheHit'
        is_public:
          type: boolean
        api_key_name:
          type:
            - string
            - 'null'
          description: >-
            Name of the API key that created the job, when one was used. `null`
            for dashboard runs.
        accepted_at:
          type: string
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: '`null` while the job is still running.'
        error:
          type:
            - string
            - 'null'
          description: Error message when status is `failed`.
      required:
        - job_id
```

--------------------------------

### GET /judge/brand-adherence

Source: https://docs.tastelabs.com/api-reference/endpoint/list-brand-adherence-jobs

Lists the caller's brand-adherence jobs, most recent first. Filter by status; paginate with limit and offset.

```APIDOC
## GET /judge/brand-adherence

### Description
Lists the caller's brand-adherence jobs, most recent first. Filter by `status`; paginate with `limit` and `offset`.

### Method
GET

### Endpoint
/judge/brand-adherence

### Parameters
#### Query Parameters
- **status** (AdherenceStatus) - Optional - Filter by lifecycle status. A job is stored as `accepted`, `completed`, or `failed`; `extracting` and `judging` are live states seen only when polling a single job, so filtering by them returns an empty list. Possible values: `accepted`, `extracting`, `judging`, `completed`, `failed`.
- **q** (string) - Optional - Free-text search over both sides' URLs.
- **limit** (integer) - Optional - Maximum jobs to return. Minimum: 1, Maximum: 100, Default: 50.
- **offset** (integer) - Optional - Number of jobs to skip, for pagination. Minimum: 0, Default: 0.

### Response
#### Success Response (200)
The caller's jobs, most recent first. Returns an object with the following properties:
- **jobs** (array of AdherenceJob) - Required - List of jobs.
- **total** (integer) - Total jobs matching the filter, ignoring pagination.
- **limit** (integer) - The limit used for pagination.
- **offset** (integer) - The offset used for pagination.

#### Response Example
{
  "jobs": [
    {
      "job_id": "string",
      "user_id": "string",
      "status": "accepted",
      "reference_url": "string",
      "source_url": "string",
      "current_step": "string",
      "step_started_at": "string",
      "updated_at": "string",
      "cache_hit": true
    }
  ],
  "total": 0,
  "limit": 50,
  "offset": 0
}

#### Error Responses
- **401** - Unauthorized
- **403** - Forbidden
- **500** - Internal Error
```

--------------------------------

### Codex: Add taste-engine MCP server

Source: https://docs.tastelabs.com/ai-tools/mcp

Exports the API key as an environment variable and adds the taste-engine MCP server. Replace YOUR_API_KEY with a real key from the dashboard.

```bash
export TASTE_ENGINE_API_KEY=YOUR_API_KEY

codex mcp add taste-engine \
  --url https://mcp.tastelabs.com/mcp \
  --bearer-token-env-var TASTE_ENGINE_API_KEY
```

--------------------------------

### GET /design/submissions/{id}/result

Source: https://docs.tastelabs.com/api-reference/introduction

Polls for the result of a submission. Returns a partial result or a 409 NOT_READY status until the job completes.

```APIDOC
## GET /design/submissions/{id}/result

### Description
Polls for the result of a submission. Returns a partial result or a 409 NOT_READY status until the job completes.

### Method
GET

### Endpoint
https://api.tastelabs.com/design/submissions/{id}/result

### Parameters
#### Path Parameters
- **id** (string) - Required - The submission ID.

### Request Example
```bash
curl https://api.tastelabs.com/design/submissions/SUBMISSION_ID/result \
  -H "X-API-Key: your-api-key"
```

### Response
#### Success Response (200 OK)
- **result.design_system** (object) - The extracted design system.
- **result.artifacts** (array) - Links to captured source artifacts.

#### Response Example
(Not provided in source)

```

--------------------------------

### Search for brands with POST /search

Source: https://docs.tastelabs.com/use-cases/find-inspiration

Call the search endpoint with a natural-language query. Use depth: "fast" while exploring; switch to "deep" when shortlisting. Requires an API key.

```bash
curl -X POST https://api.tastelabs.com/search \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "moody, grainy portfolio with a weird custom cursor", "top_k": 6}'
```

--------------------------------

### GET /design/submissions/{id}

Source: https://docs.tastelabs.com/api-reference/endpoint/get-submission

Returns the current status of a single submission, including which step it is on. Use the submission ID returned when the submission was created.

```APIDOC
## GET /design/submissions/{id}

### Description
Returns the current status of a single submission, including which step it is on.

### Method
GET

### Endpoint
/design/submissions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The `submission_id` returned when the submission was created.

### Response
#### Success Response (200)
- **submission_id** (string) - The unique identifier of the submission.
- **status** (SubmissionStatus) - The current status of the submission.
- **source_url** (string, uri) - The URL of the source website.
- **current_step** (string) - Name of the step currently running.
- **step_started_at** (string, date-time) - Timestamp when the current step started.
- **updated_at** (string, date-time) - Timestamp of the last update.
- **cache_hit** (boolean) - Whether the result was served from cache. When `true`, `completed_at` reflects the original extraction, not this request.
- **extraction_id** (string or null) - The identifier of the extraction.
- **accepted_at** (string, date-time) - Timestamp when the submission was accepted.
- **completed_at** (string or null, date-time) - When the extraction completed: the freshness of the result. On a cache hit (`cache_hit` is `true`) this is the original extraction, not the current request, so it may predate this request. `null` while the submission is still running.
- **error** (string or null) - Error message when status is `failed`.
- **credits_consumed** (integer or null) - Net credits this submission consumed. `null` when metering was off, and `0` once a failed submission has been refunded.
- **credit_ref_id** (string or null) - Reference to the credit charge for this submission.
- **api_key_name** (string or null) - Name of the API key that created the submission. `null` for dashboard submissions and when metering was off at submission time.
- **batch_id** (string or null) - Identifier of the batch run this submission belongs to.
- **batch_label** (string) - Label of the batch run this submission belongs to.

#### Response Example
{
  "submission_id": "string",
  "status": "pending",
  "source_url": "https://example.com",
  "current_step": "extracting",
  "step_started_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "cache_hit": false,
  "extraction_id": null,
  "accepted_at": "2024-01-01T00:00:00Z",
  "completed_at": null,
  "error": null,
  "credits_consumed": 1,
  "credit_ref_id": "string",
  "api_key_name": "string",
  "batch_id": null,
  "batch_label": "string"
}

### Error Responses
- **401** - Unauthorized: missing or invalid API key.
- **403** - Forbidden: insufficient permissions.
- **404** - Not Found: submission not found.
- **500** - Internal Server Error.
```

--------------------------------

### Add taste-engine MCP server to Codex

Source: https://docs.tastelabs.com/ai-tools/mcp

Use this command to add the Taste Engine MCP server to Codex by URL. No token is required; complete sign-in when prompted.

```bash
codex mcp add taste-engine --url https://mcp.tastelabs.com/mcp
```

--------------------------------

### Set up SSH tunnel for localhost submission

Source: https://docs.tastelabs.com/concepts/submissions

Run these commands to expose a localhost server (default port 3000) to Tastelabs via SSH tunnel. The tunnel closes when ssh exits or the deadline passes; a submission against a closed tunnel fails with 'Page not reachable'. Keep ssh running across iterations and re-run if it expires.

```bash
SERVER_PORT=3000
CRAWL_ID=crawl-$(uuidgen)
# Print the URL to submit.
echo "Crawl URL: http://$CRAWL_ID"
# Open the SSH tunnel.
ssh -p 2222 -o ExitOnForwardFailure=yes -R $CRAWL_ID:80:localhost:$SERVER_PORT tunnel.tasting.dev deadline=3600s
```

--------------------------------

### GET /judge/brand-adherence/{job_id}

Source: https://docs.tastelabs.com/api-reference/endpoint/get-brand-adherence-job

Returns the live status of a brand-adherence job. Poll this endpoint to track progress through the pipeline stages, then read the verdict once the job is completed.

```APIDOC
## GET /judge/brand-adherence/{job_id}

### Description
Returns the live status of a brand-adherence job. `status` advances through `accepted`, `extracting`, and `judging` before reaching `completed` or `failed`; `current_step` names the pipeline stage in progress.

Poll this endpoint, then read the verdict from `GET /judge/brand-adherence/{job_id}/result` once `status` is `completed`. On `failed`, `error` carries the reason.

### Method
GET

### Endpoint
/judge/brand-adherence/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - Brand-adherence job identifier, as returned by `POST /judge/brand-adherence`.

### Response
#### Success Response (200)
- **job_id** (string) - The job identifier.
- **user_id** (string) - The user identifier.
- **status** (AdherenceStatus) - The current status of the job. Possible values: `accepted`, `extracting`, `judging`, `completed`, `failed`.
- **reference_url** (string, uri) - The reference site URL.
- **source_url** (string, uri) - The source site URL.
- **current_step** (string, nullable) - Name of the pipeline stage currently running, e.g. `waiting_for_extractions`, `judging_scene`.
- **step_started_at** (string, date-time, nullable) - Timestamp when the current step started.
- **updated_at** (string, date-time, nullable) - Timestamp of the last update.
- **cache_hit** (AdherenceCacheHit) - Cache hit information.
- **is_public** (boolean) - Whether the job is public.
- **api_key_name** (string, nullable) - Name of the API key that created the job, when one was used. `null` for dashboard runs.
- **accepted_at** (string, date-time) - Timestamp when the job was accepted.
- **completed_at** (string, date-time, nullable) - Timestamp when the job completed. `null` while the job is still running.
- **error** (string, nullable) - Error message when status is `failed`.

#### Response Example
```json
{
  "job_id": "string",
  "user_id": "string",
  "status": "accepted",
  "reference_url": "https://example.com/reference",
  "source_url": "https://example.com/source",
  "current_step": "waiting_for_extractions",
  "step_started_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "cache_hit": {},
  "is_public": true,
  "api_key_name": "my-api-key",
  "accepted_at": "2023-01-01T00:00:00Z",
  "completed_at": null,
  "error": null
}
```

### Error Responses
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **500** - Internal Error
```

--------------------------------

### Connect Taste Engine MCP server with Claude Code

Source: https://docs.tastelabs.com/ai-tools/skills

Run this command to connect the Taste Engine MCP server to Claude Code over HTTP. The skills only work once the MCP server is connected; if tools are not visible, the server is not connected.

```bash
claude mcp add --transport http taste-engine https://mcp.tastelabs.com/mcp
```

--------------------------------

### GET /searches

Source: https://docs.tastelabs.com/api-reference/endpoint/list-searches

Retrieves a list of past searches. Each search includes metadata such as query, depth, filters, status, result count, latency, and credit usage.

```APIDOC
## GET /searches

### Description
Returns a list of past searches made by the authenticated user. Each search includes metadata such as query, depth, filters, status, result count, latency, and credit usage.

### Method
GET

### Endpoint
/searches

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - The number of items to skip before starting to collect the result set.

### Response
#### Success Response (200)
- **items** (array of SearchSubmission) - List of past searches.
- **offset** (integer) - The offset used for pagination.

#### Response Example
```json
{
  "items": [
    {
      "id": "string",
      "kind": "search",
      "query": "string",
      "depth": "fast",
      "filters": {},
      "query_tags": {},
      "status": "string",
      "result_count": 0,
      "latency_ms": 0,
      "credit_ref_id": "string",
      "credits_consumed": 0,
      "api_key_name": "string",
      "created_at": "2023-01-01T00:00:00Z",
      "completed_at": "2023-01-01T00:00:00Z"
    }
  ],
  "offset": 0
}
```

### Error Responses
#### Unauthorized (401)
- **detail.error** (string) - Machine-readable error code, e.g., `UNAUTHORIZED`.
- **detail.message** (string) - Human-readable explanation.

#### InternalError (500)
- The body is plain text, e.g., `Internal Server Error`.

### Authentication
- **ApiKeyAuth** (apiKey) - Header: `X-API-Key` - API key issued by the Taste Engine. Create one in the dashboard at https://engine.tastelabs.com/app/api-keys.

```

--------------------------------

### Serve static files with Python HTTP server

Source: https://docs.tastelabs.com/concepts/submissions

Use this command to serve static files on localhost port 3000 when you don't have a server running. Adjust the port if needed.

```bash
python3 -m http.server 3000
```

--------------------------------

### Extract a design system with cURL and jq

Source: https://docs.tastelabs.com/quickstart

Bash script using cURL and jq to submit a URL, poll for the result, and print the design system. Uses environment variables for API key and base URL.

```bash
export API_KEY="your-api-key"
export BASE="https://api.tastelabs.com"

# 1. Submit
SUBMISSION_ID=$(curl -s -X POST $BASE/design/submissions \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://stripe.com"}' | jq -r '.submission_id')

# 2. Poll the result endpoint
while true; do
  RESP=$(curl -s $BASE/design/submissions/$SUBMISSION_ID/result -H "X-API-Key: $API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status // empty')
  { [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; } && break
  sleep 3
done

# 3. Read the design system
echo "$RESP" | jq '.result.design_system'
```

--------------------------------

### Add taste-engine MCP server to other clients

Source: https://docs.tastelabs.com/ai-tools/mcp

JSON configuration for clients that support MCP OAuth. Add a streamable HTTP server with no auth headers, then complete sign-in in the browser when prompted.

```json
{
  "mcpServers": {
    "taste-engine": {
      "type": "http",
      "url": "https://mcp.tastelabs.com/mcp"
    }
  }
}
```