{"openapi":"3.1.0","info":{"title":"UI Polish API","version":"1.0.0","summary":"React components and design rules for coding agents, as JSON.","description":"Read-only access to the UI Polish component registry and design rules: the same content the MCP server at https://uipolish.com/mcp serves. Components and rules need no key. Pro blocks need a UI Polish Pro license key, sent as `Authorization: Bearer <key>` (or `?key=<key>`). Every error is JSON with a stable `code`, a `message` and a `hint`.","contact":{"name":"UI Polish","email":"support@uipolish.com","url":"https://uipolish.com/contact"},"license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"https://uipolish.com"}],"externalDocs":{"description":"Docs","url":"https://uipolish.com/docs"},"tags":[{"name":"components","description":"React components with their code and guides."},{"name":"rules","description":"Design rules, design tokens and the pre-ship checklist."}],"security":[{},{"licenseKey":[]},{"licenseKeyQuery":[]}],"paths":{"/api/components":{"get":{"operationId":"listComponents","tags":["components"],"summary":"List every component","description":"Every component's name, one-line summary, version, and kit (agent, for the components for AI products). Use a name with getComponent.","responses":{"200":{"description":"The components.","content":{"application/json":{"schema":{"type":"object","required":["components"],"properties":{"components":{"type":"array","items":{"$ref":"#/components/schemas/ComponentSummary"}}}}}}}}}},"/api/components/{name}":{"get":{"operationId":"getComponent","tags":["components"],"summary":"Get one component's code and guide","description":"The component's files (React and CSS module), the files of the components it depends on, and its guide: when to use it, every state, motion and accessibility. Write each file at its path, after installing the listed packages. Pro blocks need a license key.","parameters":[{"name":"name","in":"path","required":true,"description":"Component name from listComponents.","schema":{"type":"string","enum":["accordion","agent-console","agent-settings","agent-task","agent-workspace","ai-chat-app","alert","approvals-inbox","authorize","avatar","background-run","badge","batch-progress","billing","breadcrumbs","button","checkbox","chip","code-block","code-input","combobox","command-palette","connections","copy-field","data-table","date-picker","dialog","diff-stat","diff-view","drawer","dropdown-menu","empty-state","file-changes","file-upload","inline-edit","kbd","knowledge-base","list","markdown","merge-status","message-thread","model-picker","nav-rail","number-input","onboarding","pagination","phone-input","pipeline","plan-approval","popover","pricing","progress","prompt-input","radio-group","reasoning","research-progress","response-actions","run-history","scroll-area","search-field","segmented-control","select","settings","sidebar","sign-in","skeleton","slider","sources","stat","switch","tabs","team-members","text-field","theme-toggle","toast","tool-approval","tool-steps","tooltip","turn-summary","usage-meter","voice-input","voice-session"]}},{"name":"stack","in":"query","required":false,"description":"Target stack. Only react (CSS modules).","schema":{"type":"string","enum":["react"],"default":"react"}},{"name":"tailwind","in":"query","required":false,"description":"true for a Tailwind CSS v4 project: each CSS module comes inside Tailwind's components layer, so utility classes override it. Set up the bridge once from GET /api/rules/tailwind.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The component.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentDetail"}}}},"400":{"description":"Unsupported stack (code unsupported_stack), or tailwind not true or false (code invalid_parameter).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"The license key wasn't accepted (code license_invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"A Pro block requested without a license key (code license_required). Includes checkout_url.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"No component with that name (code component_not_found). Includes available names.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"License keys can't be checked right now (code license_check_unavailable). Retry after the Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/theme":{"get":{"operationId":"getTheme","tags":["rules"],"summary":"A color theme from one hue","description":"The --ui-* accent, the text on it and in it, optionally tinted grays and accent primary buttons, light and dark, with every text color solved for contrast. Paste the css after tokens.css.","parameters":[{"name":"hue","in":"query","required":false,"description":"OKLCH hue, 0–360 (262 blue, the default; 25 red; 150 green).","schema":{"type":"number","minimum":0,"maximum":360}},{"name":"tint","in":"query","required":false,"description":"Grays: 0 neutral, 1 a hint of the hue (default), 2 tinted.","schema":{"type":"integer","enum":[0,1,2]}},{"name":"brand","in":"query","required":false,"description":"Primary buttons in the accent (default true).","schema":{"type":"boolean"}},{"name":"format","in":"query","required":false,"description":"css for the stylesheet alone.","schema":{"type":"string","enum":["css"]}}],"responses":{"200":{"description":"The theme.","content":{"application/json":{"schema":{"type":"object","required":["css","vars"],"properties":{"css":{"type":"string"},"vars":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"400":{"description":"hue or tint isn't valid (code invalid_parameter).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/rules":{"get":{"operationId":"listRuleTopics","tags":["rules"],"summary":"List rule topics","description":"The design-rule topics, plus tokens (the --ui-* design tokens as CSS), checklist (yes/no checks before calling UI done) and tailwind (setup for Tailwind CSS v4 projects).","responses":{"200":{"description":"The topics.","content":{"application/json":{"schema":{"type":"object","required":["topics"],"properties":{"topics":{"type":"array","items":{"$ref":"#/components/schemas/RuleTopic"}}}}}}}}}},"/api/rules/{topic}":{"get":{"operationId":"getRule","tags":["rules"],"summary":"Get the rules for one topic","description":"Concrete values for one topic, as Markdown (tokens is CSS). Read the topic before writing UI that touches it.","parameters":[{"name":"topic","in":"path","required":true,"description":"Topic from listRuleTopics.","schema":{"type":"string","enum":["antipatterns","foundations","motion","spacing","states","surfaces","typography","tokens","checklist","tailwind"]}}],"responses":{"200":{"description":"The rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rule"}}}},"404":{"description":"No such topic (code topic_not_found). Includes available topics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"licenseKey":{"type":"http","scheme":"bearer","description":"A UI Polish Pro license key. Only needed for Pro blocks."},"licenseKeyQuery":{"type":"apiKey","in":"query","name":"key","description":"The license key as a query parameter, for clients that can't send headers."}},"schemas":{"ComponentSummary":{"type":"object","required":["name","title","summary","type","access","version","docs_url"],"properties":{"name":{"type":"string","description":"Identifier for getComponent.","examples":["button"]},"title":{"type":"string","examples":["Button"]},"summary":{"type":"string"},"kit":{"type":"string","enum":["agent"],"description":"Set on the agent kit: components for AI products."},"type":{"type":"string","enum":["component","block","template"],"description":"A block is a whole screen composed from components; a template is a working app composed from components and blocks."},"access":{"type":"string","enum":["free","pro"],"description":"pro needs a UI Polish Pro license key."},"version":{"type":"string","examples":["0.1.0"]},"docs_url":{"type":"string","format":"uri"}}},"ComponentFile":{"type":"object","required":["component","path","content"],"properties":{"component":{"type":"string","description":"The component this file belongs to."},"path":{"type":"string","description":"Relative path to write it at, e.g. button/button.tsx."},"target":{"type":"string","description":"A template's own files only: the path from the project root, e.g. app/(app)/chat/page.tsx. Write it there instead of under the components directory."},"content":{"type":"string"}}},"ComponentDetail":{"allOf":[{"$ref":"#/components/schemas/ComponentSummary"},{"type":"object","required":["dependencies","packages","guide","files","install"],"properties":{"dependencies":{"type":"array","items":{"type":"string"},"description":"Components it imports, in the order to write them."},"packages":{"type":"array","items":{"type":"string"},"description":"npm packages to install first, as name@range (e.g. @base-ui/react@^1.9.0)."},"guide":{"type":"string","description":"The component's guide, in Markdown."},"files":{"type":"array","items":{"$ref":"#/components/schemas/ComponentFile"},"description":"Dependencies' files first, then its own."},"install":{"type":"string","description":"How to add the files to a project."}}}]},"RuleTopic":{"type":"object","required":["topic","url"],"properties":{"topic":{"type":"string"},"url":{"type":"string","format":"uri"}}},"Rule":{"type":"object","required":["topic","format","content"],"properties":{"topic":{"type":"string"},"format":{"type":"string","enum":["markdown","css"]},"content":{"type":"string"}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint","docs"],"properties":{"code":{"type":"string","description":"Stable identifier to branch on.","enum":["not_found","method_not_allowed","component_not_found","topic_not_found","unsupported_stack","invalid_parameter","license_required","license_invalid","license_check_unavailable"]},"message":{"type":"string","description":"What went wrong."},"hint":{"type":"string","description":"How to fix the request."},"docs":{"type":"string","format":"uri"},"available":{"type":"array","items":{"type":"string"},"description":"Valid names or topics, on a not-found error."},"checkout_url":{"type":"string","format":"uri","description":"Where to get UI Polish Pro, on license errors."},"license_docs":{"type":"string","format":"uri"},"price_usd":{"type":"number"}}}}}}}}