Taste Engine

https://docs.tastelabs.com
Admin
Taste Engine is an API and toolset for extracting structured design systems from URLs, searching...
Tokens:55,268
Snippets:418
Trust Score:6.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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 /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.
```

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

### 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"
```

```

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

### 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:
```

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

### 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);
```

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

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

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

### 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}")
```

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

### 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."
  }
}
```

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

### 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/
```

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

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

```

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

### 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}`);
```

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

### 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}'
```
Tokens:
Raw