API Reference

Roast Taste API

Welcome to the Roast developer reference. Integrate our Taste Engine directly into your AI coding agents, background CI/CD test runners, or visual generators to audit and correct design system tokens in real-time.

Base URL https://roast-production-be62.up.railway.app

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 and CSS adjustments. • `"score"`: Returns numerical grades across typography, spacing, colors, etc. • `"profile"`: Generates a complete `DESIGN.md` specification and gap analysis.
context	string	Optional. Supplementary prompt instructions or brand guidelines (e.g. `"Match Linear's dark mode aesthetic exactly"`) to calibrate engine audits.

request schema payload

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

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://roast-production-be62.up.railway.app/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://roast-production-be62.up.railway.app/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://roast-production-be62.up.railway.app/api/roast \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": { 
        "type": "tokens", 
        "value": { "colors": { "primary": "#000" }, "spacing": "4px" } 
      }
    }'