API reference

Use the same audience research, design tokens and reference checks as the web app. Public endpoints need no account or API key.

Qloo supplies taste data. QlooVibe maps it to design tokens using a published rule table. The mapping is a design hypothesis, not a prediction of how people will respond to an interface.

`POST /api/vibe`

Describe what you are building, or provide project Markdown, to compare up to three supported style directions. Each has a named font pair, color palette, CSS, an implementation brief and its evidence.

curl · Bash

curl -sS -X POST 'https://qloovibe.ibnweb3lab.workers.dev/api/vibe' \
  -H 'content-type: application/json' \
  --data '{"audience":"fans of Slowdive, Aesop, A24"}'

audience or seeds: Supply a nonblank audience description of 2–300 characters naming 1–5 things people love, or an explicit array of 1–5 names. Each name must be 2–60 characters. Separate names with commas, semicolons or newlines; put names containing these delimiters in quotes. Words such as “and” and symbols such as “&” stay within a name. Explicit seeds take priority and preserve punctuation within names.
project or project_markdown · optional string, 20–8000 characters: Send the complete project description or the actual text of a README.md, design.md or specification. Use project or project_markdown, not both. The hosted service cannot open local file paths. Optional source_name is a filename only. Explicit audience names can accompany the project context. A language model proposes audience names from it; each name is checked against Qloo and only exact matches are kept. The response lists the proposed names under audience.suggested_seeds and marks audience.source as model_suggested. All design vocabulary still comes from Qloo; the model picks only the starting names. A long sentence that Qloo cannot match as one name is treated the same way. Explicit names always win.
fresh · optional boolean: Set to true to bypass the provider cache. Otherwise, provider responses may be reused for up to 6 hours; the trace identifies cached requests.

For ambiguous names, add a type hint: Apple (brand). Supported types are brand, artist, movie, tv_show, book, videogame, podcast and person. Aliases include film, tv, show and game.

Successful responses include an id, seeds, trace and caveats. With enough evidence, they also include tokens and a copyable agent_brief. The directions array contains each supported option: id, name, fonts, tokens, rationale and agent_brief. Use the chosen option’s exports. Top-level tokens and agent_brief alias the first direction for compatibility. Fonts and palettes are QlooVibe interpretations, not Qloo-validated design choices. Default dimensions are labelled; entirely default briefs are withheld.

`POST /api/check`

Check named artists, brands, films and other references against the same audience.

curl · Bash

curl -sS -X POST 'https://qloovibe.ibnweb3lab.workers.dev/api/check' \
  -H 'content-type: application/json' \
  --data '{"audience":"Slowdive, Aesop","candidates":["Bon Iver","Metallica"]}'

Uses the same audience fields and optional fresh flag. candidates is required: an array of 1–12 nonblank names, each 2–60 characters. Duplicate names are checked once.

Each result includes the resolved name, affinity, comparison baseline, gap and verdict: strong, ok, weak, off-audience or unknown. The baseline is the median of Qloo’s top references for that audience and entity type, up to 10 results. Verdict thresholds are heuristic. Missing data stays unknown; it is never a zero score.

`POST /api/audit`

After your agent builds the UI, send its code and the chosen direction's brief. The audit runs plain code checks: no model and no Qloo call.

curl · Bash

curl -sS -X POST 'https://qloovibe.ibnweb3lab.workers.dev/api/audit' \
  -H 'content-type: application/json' \
  --data '{"code":"body{font-family:Inter;color:#123456}","reference":"--qv-text:#211813; --qv-font-body: Figtree, sans-serif;"}'

code is up to 200,000 characters. reference is the direction's agent_brief, css_qv or css_shadcn. The result has status (pass or needs_changes), per-check results and findings with a suggested fix. Checks: colours outside the direction's palette, fonts outside its pair, starter-template fonts, Tailwind default colour classes, purple gradients, generic filler copy, low use of the direction's variables and scattered corner radii. The marker lists are published in /api/rules under audit.

A pass means no failures were found in the checks that could run. Read warnings and any not_applicable results. It does not measure design quality, layout or whether an audience will like the page.

Read the response status

An HTTP 200 means the request was processed. Always inspect the JSON status and any caveats before using the result.

complete: Enough data was returned for the requested result. Read the evidence and any default token labels.
partial: Some data or names could not be included, or an entity matched only the closest available name. Inspect unresolved, caveats and individual result notes.
insufficient_evidence: No supported design direction or fit verdict could be produced. A brief has no tokens in this state. Try more specific names, or retry if the provider was unavailable.

422 means invalid JSON or input outside the limits above. 429 means too many requests: wait the number of seconds in the Retry-After header. 500 means an unexpected server error; retry later. Error bodies use {"error":{"code":"…","message":"…"}}.

Provider work has a 25-second deadline. Requests can return partial or insufficient evidence when the provider is slow or unavailable.

Connect an MCP client

Use the design_project MCP prompt to guide your coding agent through reading Markdown, comparing styles and applying your choice. The resource qloovibe://workflow/project-design describes the same workflow. For direct file access, use the local stdio bridge described in the repository’s docs/MCP.md. The stateless Streamable HTTP endpoint is https://qloovibe.ibnweb3lab.workers.dev/mcp. For Claude Code:

claude mcp add --transport http qloovibe https://qloovibe.ibnweb3lab.workers.dev/mcp

design_brief(seeds? | audience? | project?): Returns the brief plus its full evidence. Provide at least one input. Best: seeds, 3–5 names the audience loves, which your agent infers from the user's project or design.md. Fallback: project, the description or design.md text, from which a language model proposes the names and Qloo verifies them.
check_audience_fit(candidates, audience? | seeds? | project?): Returns reference scores and qualified fit verdicts. Optional exact audience seeds override parsing.
get_rule_table(): Returns the versioned tag-to-token mapping.

MCP tools use the same name and input limits as the REST endpoints. Design and reference-check tools share the REST rate budget. A limited MCP tool returns isError: true, error code rate_limited, and retry_after: 60, with a Retry-After header; initialization, tool discovery and rule-table reads remain available. Unexpected errors include a correlation ID for server logs. Successful tool responses still require checking the result status.

Read-only endpoints

GET /api/vibe/{id}: Retrieve a saved brief by its returned ID. Briefs expire after 7 days. Missing, expired or unsaved briefs return 404.
GET /api/rules: Inspect all mapping rules, defaults and filtering criteria.
GET /api/benchmark: Read the stored Qloo-versus-LLM vocabulary comparison. Returns 404 if no benchmark has been stored. It does not measure design quality.
GET /health: Check server availability and whether provider bindings are configured. Configuration does not guarantee the external provider is reachable.
GET /openapi.json: Download the machine-readable endpoint specification.

Return to the app