API Reference

Roast Taste API

A native design collaborator for AI coding agents. Roast holds briefs, tracks progress across iterations, adapts how it delivers critique, and closes sessions when the design meets the goal. 13 MCP tools. One taste layer.

Base URL https://designroast.cc

Authentication

Authenticate all API requests by providing your API key as a Bearer token in the Authorization header. Keep your keys secure — do not expose them in client-side code or browser applications.

header requirements

Authorization: Bearer {your_api_key}
Content-Type: application/json

POST /api/roast

Evaluates a layout, a raw design file, or structured tokens payload against our comprehensive taste corpus of beautiful human interfaces. Returns grade breakdowns, design mismatch diffs, or structured aesthetic verdicts.

Request Body Parameters

Parameter	Type	Description
inputrequired	object	The payload to evaluate. Must contain nested `type` and `value` fields. • `input.type` (string): One of `"url"`, `"image"`, or `"tokens"`. • `input.value` (string \| object): The live URL string, the base64 screenshot image string, or raw JSON design token structure.
mode	string	Controls the structure of the Taste Engine response output. • `"diff"` (Default): Returns terse, actionable structural fixes, industry mismatch flags, and CSS adjustments. • `"score"`: Returns numerical grades across typography, spacing, colors, hierarchy, and industry alignment. • `"profile"`: Generates a complete design profile with identity analysis, dimension scores, industry alignment audit, slop report, and forward direction.
context	string	Optional. Industry or domain context (e.g. `"fintech dashboard"`) to activate industry alignment checks. Also accepts supplementary styling instructions (e.g. `"Match Linear's dark mode"`).

request schema payload

{
  "input": {
    "type": "url" | "image" | "tokens",
    "value": "string" | { ... }
  },
  "mode": "diff" | "score" | "profile",
  "context": "string"
}

Session Tools

Start a design review session, iterate across versions, and close when the goal is met. Sessions hold the brief, track score progression, and adapt critique based on how the agent responds.

Tool	Description
roast_start_session	Start a design review session. Collects the brief, captures v1 screenshot, evaluates against goals, and returns structured critique. Required: `brief` (object with `critical_signals`), `url` (string).
roast_iterate	Continue a session with a new iteration. Captures new screenshot, evaluates delta against history, tracks what resolved and what persisted. Required: `session_id` (string), `url` (string).
roast_close_session	Close a session. Returns final report with score progression, agent response pattern, and goal achievement status. Required: `session_id` (string).

Evaluation Tools

One-off evaluations for URLs, images, and design files. Use these for quick audits outside of a session context.

Tool	Description
roast_url	Screenshot and evaluate any live URL for visual hierarchy, spacing, and contrast issues.
roast_image	Evaluate a base64-encoded PNG, JPEG, or WebP screenshot directly.
roast_figma	Evaluate a Figma frame from a URL with ?node-id= — fetches and analyzes via Figma API.
roast_tokens	Evaluate a design token JSON object for structural, mathematical, and semantic issues.

Integration Examples

Auditing live websites, layout screenshots, or raw design variables requires selecting the correct payload structure. Explore our three payload evaluation types below:

Evaluates a public live landing page by parsing layout structures, styling files, elements alignments, and contrast scores in real-time.

curl example: url evaluation

curl -X POST https://designroast.cc/api/roast \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": { "type": "url", "value": "https://example.com" },
      "mode": "score"
    }'

Sends a screen capture or local mockup image directly as a base64 encoded string to audit layout layouts and spacing balances.

curl example: image evaluation

curl -X POST https://designroast.cc/api/roast \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": { "type": "image", "value": "data:image/png;base64,iVBORw0KGgo..." }
    }'

Audits raw token systems directly, ensuring typography, primary colors palettes, and padding structures hold visual harmony.

curl example: token evaluation

curl -X POST https://designroast.cc/api/roast \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": { 
        "type": "tokens", 
        "value": { "colors": { "primary": "#000" }, "spacing": "4px" } 
      }
    }'