Palette API Reference

All Palette endpoints are served under the /api/v1/palette prefix via the gateway.

Endpoints

Tokens

Method	Path	Description
GET	/api/v1/palette/tokens	List tokens (filter: ?category=, ?group=, ?tag=)
POST	/api/v1/palette/tokens	Create token
GET	/api/v1/palette/tokens/:idOrName	Get token by ID or name (includes usage info)
PUT	/api/v1/palette/tokens/:idOrName	Update token
DELETE	/api/v1/palette/tokens/:idOrName	Delete token

Components

Method	Path	Description
GET	/api/v1/palette/components	List components (filter: ?status=, ?category=, ?tag=)
POST	/api/v1/palette/components	Create component
GET	/api/v1/palette/components/:idOrName	Get component with resolved relations
PUT	/api/v1/palette/components/:idOrName	Update component
POST	/api/v1/palette/components/:idOrName/props	Add a prop to a component
POST	/api/v1/palette/components/:idOrName/variants	Add a variant to a component
POST	/api/v1/palette/components/:idOrName/examples	Add an example to a component
DELETE	/api/v1/palette/components/:idOrName	Delete component

Patterns

Method	Path	Description
GET	/api/v1/palette/patterns	List patterns (filter: ?category=, ?tag=)
POST	/api/v1/palette/patterns	Create pattern
GET	/api/v1/palette/patterns/:idOrName	Get pattern with resolved relations
PUT	/api/v1/palette/patterns/:idOrName	Update pattern
POST	/api/v1/palette/patterns/:idOrName/steps	Add a step to a pattern
DELETE	/api/v1/palette/patterns/:idOrName	Delete pattern

Standards

Method	Path	Description
GET	/api/v1/palette/standards	List standards (filter: ?category=, ?tag=)
POST	/api/v1/palette/standards	Create standard
GET	/api/v1/palette/standards/:idOrName	Get standard by ID or name
DELETE	/api/v1/palette/standards/:idOrName	Delete standard

Accessibility Rules

Method	Path	Description
GET	/api/v1/palette/a11y	List a11y rules (filter: ?category=, ?severity=, ?tag=)
POST	/api/v1/palette/a11y	Create a11y rule
GET	/api/v1/palette/a11y/:idOrName	Get a11y rule (includes component usage)
DELETE	/api/v1/palette/a11y/:idOrName	Delete a11y rule

Search & Export

Method	Path	Description
GET	/api/v1/palette/search?q=<term>	Full-text search across all collections (filter: ?kind=)
GET	/api/v1/palette/export?format=css|json|tailwind	Export tokens in specified format

Examples

Create a Token

curl -X POST http://localhost:3000/api/v1/palette/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "name": "primary-blue",
    "category": "color",
    "value": "#0066FF",
    "dark": "#3399FF",
    "cssVariable": "--color-primary",
    "tailwindKey": "primary",
    "group": "brand",
    "description": "Primary brand color"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4",
    "name": "primary-blue",
    "category": "color",
    "value": { "default": "#0066FF", "dark": "#3399FF" },
    "cssVariable": "--color-primary",
    "tailwindKey": "primary",
    "group": "brand",
    "description": "Primary brand color",
    "created": "2026-03-05T12:00:00.000Z",
    "updated": "2026-03-05T12:00:00.000Z"
  }
}

Create a Component

curl -X POST http://localhost:3000/api/v1/palette/components \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Button",
    "status": "stable",
    "category": "actions",
    "description": "Primary action button",
    "props": [
      { "name": "variant", "type": "string", "required": true, "description": "Visual style" }
    ],
    "variants": [
      { "name": "primary", "description": "Primary action" },
      { "name": "secondary", "description": "Secondary action" }
    ],
    "tokens": ["a1b2c3d4"],
    "tags": ["core", "action"]
  }'

Add a Prop to a Component

curl -X POST http://localhost:3000/api/v1/palette/components/Button/props \
  -H "Content-Type: application/json" \
  -d '{
    "name": "size",
    "type": "\"sm\" | \"md\" | \"lg\"",
    "required": false,
    "default": "md",
    "description": "Button size"
  }'

Export Tokens as CSS

curl "http://localhost:3000/api/v1/palette/export?format=css"

Response:

{
  "success": true,
  "data": {
    "format": "css",
    "output": ":root {\n  --color-primary: #0066FF;\n}"
  }
}

Search the Design System

curl "http://localhost:3000/api/v1/palette/search?q=button&kind=component"

Response:

{
  "success": true,
  "data": {
    "query": "button",
    "count": 1,
    "results": [
      {
        "kind": "component",
        "id": "x9y8z7w6",
        "name": "Button",
        "description": "Primary action button",
        "score": 12.5
      }
    ]
  }
}

Response Envelope

All responses follow the standard envelope format:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Token not found"
  }
}