Brand API

Check an adherence job's live status and progress. Lightweight; use this to poll. Poll after verify_brand_adherence until `status` is "completed", then call get_brand_adherence_result. Stop on "failed" and read `error` for the reason. In-progress statuses: "accepted", "extracting", "judging". Returns: {job_id, status, current_step, reference_url, candidate_url, cache_hit, is_public, accepted_at, completed_at, error}. `current_step` names the pipeline stage in progress (e.g. "waiting_for_extractions", "judging_scene"). Does NOT include the verdict; use get_brand_adherence_result for that.

poll_brand_adherence

Check an extraction's live status and progress. Lightweight; use this to poll. Poll after extract_brand until `status` is "completed", then call get_brand_extraction_result. Stop on "failed" and read `error` for the reason. In-progress statuses: "accepted", "queued", "crawling", "extracting". Returns: {submission_id, status, current_step, source_url, cache_hit, extraction_id, credits_consumed, accepted_at, completed_at, error}. `current_step` names the pipeline stage in progress (e.g. "crawling", "design_extract_ai"). Does NOT include the brand system; use get_brand_extraction_result for that.

poll_brand_extraction

Extract the brand system of a website from its URL. Use the result to replicate a site, build new on-brand pages or whole websites that follow the brand, or find visually similar brands. Starts an asynchronous extraction job and returns immediately. Typical flow: 1. extract_brand(url) -> returns a `brand_submission_id`. 2. poll_brand_extraction(brand_submission_id) -> poll until `status` is "completed" (or "failed"). 3. get_brand_extraction_result(brand_submission_id) -> read the brand system. Pass sections=["colors", "typography"] to extract only those sections. Pass sections=["brand_assets"] for hosted, judged campaign images and semantic labels from external sources. Enabled full extractions include this section. Dependencies still run when needed; layout-dependent selections may take similar time to a full extraction. Omit sections to extract the full brand, which is required for search_similar_brands. Caching: a recent full extraction of the same URL can be reused, including for a selective request (only requested sections are returned). Selective results are stored for retrieval but never used as cache sources. poll_brand_extraction reports `cache_hit: true` on reuse. A cache hit is faster but NOT free -- every extract_brand consumes 2 credits, cache hit or not. Pass force=true to force a fresh re-extraction (also billed). To re-read a result you have already paid for without spending again, call get_brand_extraction_result with its existing brand_submission_id (or find it via list_brand_extractions) instead of submitting the URL again. Local pages: a server on localhost is not reachable from the Taste Engine. Expose it over the Tastelabs SSH tunnel (steps in the server instructions) and pass the printed http://crawl-<uuid> URL. Tunnel aliases are never cached, so each call re-extracts whatever is published behind the alias. Returns: {submission_id, status, source_url, accepted_at}. `submission_id` is the brand_submission_id to pass to the other tools. `status` begins as "accepted" and advances through queued/crawling/extracting.

extract_brand

Fetch the verdict of a brand-adherence job: the score, the recommendations, and the fixes. Call this once poll_brand_adherence reports `status: "completed"`. Mid-run it can return a partial verdict (components the run has not produced yet stay null or empty, and `status` reports how far along the job is); early in a run it returns an error telling you to keep polling instead. Reading the verdict: - `score`: one 0-1 blend of the judge and the deterministic checks, published in 0.05 steps. The judge scores identical inputs up to 0.08 apart; treat a difference smaller than that as variance, not as a real change. - `recommendations`: the judge's recommendation strings, worst-first, with exact target values to apply. - `fixes`: the deterministic verifier's fix objects, worst-first, capped at 20.

get_brand_adherence_result

Fetch the extracted brand system for a completed extraction. Call this only once poll_brand_extraction reports `status: "completed"`. If the extraction is still running it returns an error telling you to keep polling poll_brand_extraction, since the result is not ready yet. Prefer `sections` to keep responses small: the full brand system is often 10-30k tokens, so request only the sections you will actually read (e.g. sections=["colors", "typography"] for palette + type). Omit `sections` to return all originally requested sections. This filter only narrows the stored result; it cannot add sections omitted from extract_brand.sections. Top-level response: submission metadata (submission_id, extraction_id, status, source_url, cache_hit, completed_at, sections, ...) plus `result`, which has `result.artifacts` and `result.design_system` (the brand system). Top-level `sections` records the original selection, or null for a full extraction. `result.artifacts`: captured files, each {url, path, content_type}: `html`, `css`, `screenshot`, `full_page_screenshot` (any may be null). For replication or visual understanding, fetch `full_page_screenshot.url` (or `screenshot.url`) to see the rendered page and `html`/`css` for the exact markup. `result.design_system` is the brand system. Its sections are the values accepted by `sections`; optional ones (data_display, structure, icons) appear only when detected.

get_brand_extraction_result

Read a past search and its stored result cards without spending credits. Returns search metadata plus `results`, the same cards returned by the original search. Works for both search and similar-search history entries. `results` is null when no cards were stored (a run that has not completed, a failed run, or a search predating result storage), and [] when a completed search matched nothing. Only the owner can read the search; missing or inaccessible submissions return not found.

get_search_result

List the caller's brand-adherence jobs, most recent first. Use this to find an existing adherence_job_id (the `job_id` field on each item, e.g. to re-read a verdict without paying again) or to review verification history. Narrow with `status`; paginate via limit/offset. Returns: {jobs: [...]}. Each item has the same fields as poll_brand_adherence.

list_brand_adherence_jobs

List the caller's extractions, most recent first (deduplicated by URL + pipeline). Use this to find an existing brand_submission_id (the `submission_id` field on each item, e.g. to re-read a result) or to review extraction history. Narrow with `status` and/or `search` (URL substring); paginate via limit/offset. Returns: {submissions: [...], total, totals: {status: count}, limit, offset}. Each item in `submissions` has the same fields as poll_brand_extraction.

list_brand_extractions

Look up the design dimensions closest to a described design choice. Searches a design rubric where each dimension pairs a recognizable AI-generated-design anti-pattern (slop_excerpt) with what good and great look like on the same dimension. Use it while designing or reviewing UI to check whether a choice is an AI-slop tell and what to do instead. Synchronous. Free — costs no credits.

lookup_slop

Search the brand corpus by aesthetic, described in natural language. Runs synchronously and returns ranked result cards, no polling. Each card has {url, brand_name, identity_paragraph, tags, palette, typography, screenshot_url}; fetch the screenshot url to see the brand. Results come from the curated corpus, not from your own extractions; to work with one (replicate it, build on-brand pages), extract it via extract_brand(url). page_type, industry, hue, and layout are optional hard filters, each matched against the fixed set of values listed on its own parameter: every result must satisfy every filter given, on top of the query's own aesthetic match. A value outside that set is rejected as invalid input before the search runs (no credit charged). Costs 1 credit (fast) or 2 credits (deep), refunded if the search fails. Keep the returned `search_id`: pass it to get_search_result to read these results again for free.

search_brands