API Reference

The ColoursUI REST API is organized around resources. All requests use JSON and require authentication via bearer token.

Base URL

https://api.coloursui.com/v1

ℹ️Note

All API requests must include the Content-Type: application/json header. Responses are always JSON unless otherwise specified (e.g., file downloads).

Endpoints

POST/v1/palettes

Generate a new colour palette

base_colorharmonycount

GET/v1/palettes/:id

Retrieve a saved palette

GET/v1/palettes/:id/contrast

Check WCAG contrast ratios for a palette

idlevel

POST/v1/tokens/export

Export design tokens in a target format

palette_idformatprefix

GET/v1/tokens/:id/status

Get token export job status

POST/v1/themes

Create a theme from palette and token set

palette_idtokensname

GET/v1/workspaces

List all workspaces

org_idlimit

Response Format

All responses follow a standard envelope:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Codes

Code	Meaning
400	Bad Request — Invalid parameters
401	Unauthorized — Invalid or missing API key
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn't exist
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error

Pagination

List endpoints support cursor-based pagination via limit and cursor query parameters. The response includes a next_cursor field when more results are available.