Skip to API content
Birdor API v1

API reference · v1

List palettes

Read Birdor palette colors and usage labels. Requires a live tools.read credential; there is no anonymous access and every admitted call consumes one monthly unit. API key headers are alternatives; a site session needs workspace selection instead. Pending/unknown outcomes retain reserved units. Catalog HEAD and unsupported methods return405 with Allow/no-store before admission. New client retries are new admissions; trace/Idempotency-Key do not deduplicate them. Rate headers reflect the stricter workspace/actor bound; ingress limits are separate.

GET/v1/colors/palettes

Access requirements

Health, metadata, changelog and waitlist routes are public. Catalog reads (GET /v1/tools, /v1/tools/{id}, /v1/colors/*) and POST /v1/tools/query require a tools.read credential; POST /v1/run/* requires tools.run. There is no anonymous access to these routes: send an API key (Bearer OR X-API-Key) from your server, or use the HttpOnly main-site session plus workspace selection and same-origin Origin. Never combine credentials. Every admitted call is metered. Ingress and workspace/actor minute/month limits are separate; waitlist has its own policy.

Implemented interfaces and development screens do not imply public production availability, paid access or a completed payment integration. Confirm access with Birdor before connecting an application. No paid Pro service, activation or cross-device sync is currently delivered. We are validating one repeatable task before building a paid offer.

Parameters

FieldDescription
AuthorizationstringOptionalBearer tools.read API key for third-party servers; alternatively X-API-Key or the site session. One credential is required.
X-API-KeystringOptionalAlternative to Authorization; never send both API key headers or combine key and site session.
X-Birdor-Workspace-IDstringOptionalRequired with the HttpOnly site session; optional and matching with API key.

Request example

1. Set the base URL

Request example
curl --request GET "$BIRDOR_API_BASE_URL/v1/colors/palettes" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $BIRDOR_API_KEY"

Examples are copied only; this page does not send API requests.

Responses

Illustrative response. Values vary by environment and time.

200Success
HTTP 200
{
  "ok": true,
  "data": [
    {
      "id": "birdor-blue",
      "label": "Birdor Blue",
      "hex": "#3b82f6",
      "usage": "Primary accent color for actions and highlights.",
      "sampleTextOnColor": "Birdor"
    },
    {
      "id": "birdor-ink",
      "label": "Birdor Ink",
      "hex": "#0f172a",
      "usage": "Primary background color for dark mode.",
      "sampleTextOnColor": "Calm tools."
    }
  ],
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
414Query string exceeds4096 characters before admission
HTTP 414
{
  "ok": false,
  "code": "QUERY_TOO_LONG",
  "message": "Query string too long",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
429Ingress limit exceeded before admission
HTTP 429
{
  "ok": false,
  "code": "INGRESS_RATE_LIMITED",
  "message": "Ingress request limit exceeded",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
503Ingress protection or route dependency unavailable
HTTP 503
{
  "ok": false,
  "code": "INGRESS_UNAVAILABLE",
  "message": "Ingress protection unavailable",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
400Invalid parameters/JSON body, or INVALID_REQUEST_BODY on stream read failure before admission; shared trace envelope
HTTP 400
{
  "ok": false,
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
401Missing, expired, revoked, rotated or invalid credential; there is no anonymous access
HTTP 401
{
  "ok": false,
  "code": "UNAUTHENTICATED",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
403Scope, workspace/project/member policy or site Origin denied
HTTP 403
{
  "ok": false,
  "code": "FORBIDDEN",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-09-26T00:00:00.000Z"
}
Error handling

Example response fields

Fields shown in this example; optional fields can be omitted. Array rows describe the first example element.

okboolean
Application success flag.
dataarray
Endpoint-specific result.
data[].idstring
Resource identifier.
data[].labelstring
Display label.
data[].hexstring
Hex color.
data[].usagestring
Suggested use.
data[].sampleTextOnColorstring
Sample text.
request_idstring
Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
timestampstring
Response creation timestamp.