REST API Reference

GET /v1 No key

Index of every endpoint, with the current version.

Returns version string, endpoints string[]

Example

curl "https://api.auricartisan.com/v1"

GET /v1/health No key

Liveness probe. Always cheap, never touches storage.

Returns ok boolean, time ISO-8601

Example

curl "https://api.auricartisan.com/v1/health"

GET /v1/ready No key

Readiness probe — reports whether each backing store is bound.

Use this in a deploy gate. /v1/health says the process is up; this says it can actually serve.

Returns ready boolean, checks object

Example

curl "https://api.auricartisan.com/v1/ready"

GET /v1/methods/:tool

The algorithms a given tool supports.

Parameters

Example

curl "https://api.auricartisan.com/v1/methods/harmony" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/formats No key

Every export format, across every exportable resource.

Example

curl "https://api.auricartisan.com/v1/formats"

GET /v1/tiers No key

Rate limit and monthly quota for each tier.

Example

curl "https://api.auricartisan.com/v1/tiers"

GET /v1/metrics No key

Prometheus exposition of process-level counters.

Example

curl "https://api.auricartisan.com/v1/metrics"

GET /v1/status No key

Human-readable status page.

Example

curl "https://api.auricartisan.com/v1/status"

GET /v1/catalog No key

This catalogue as JSON — every endpoint with its parameters and examples.

Machine-readable and generated from the same source as the OpenAPI spec, so a client can build its own reference or validate coverage.

Example

curl "https://api.auricartisan.com/v1/catalog"

GET /v1/docs No key

Interactive reference (Redoc).

Example

curl "https://api.auricartisan.com/v1/docs"

GET /v1/openapi.yaml No key

The OpenAPI 3.0.3 document.

Example

curl "https://api.auricartisan.com/v1/openapi.yaml"

POST /v1/color/convert

Convert one colour between the common spaces.

For the full 63-space registry with white-point control, use /v1/science/convert.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/color/convert" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"color":"#c9a227","to":"lab"}'

POST /v1/color/contrast

WCAG contrast ratio between two colours, with pass/fail at each level.

wcag carries aa_normal, aa_large, aaa_normal and aaa_large; delta_e is { method, value } for the formula deltaE picks.

Request body

Returns fg object, bg object, contrast_ratio number, delta_e object, wcag object

Example

curl -X POST "https://api.auricartisan.com/v1/color/contrast" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"fg":"#767676","bg":"#ffffff"}'

GET /v1/science/spaces

Every colour space the platform knows, with provenance.

Sixty-three spaces across RGB working spaces, CIE spaces, perceptual and appearance models, HDR containers, print and video. Ask for full=true to get primaries, transfer curves and the XYZ matrices.

Parameters

Example

curl "https://api.auricartisan.com/v1/science/spaces?category=perceptual" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/science/spaces/:key

One colour space in full, including its conversion matrices.

Parameters

Errors UNKNOWN_SPACE (404) — No space with that key. The response suggests near matches.

Example

curl "https://api.auricartisan.com/v1/science/spaces/oklch" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/science/convert

Convert a colour into any registry space, or several at once.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/science/convert" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"color":"#c9a227","to":["lab","oklch","display-p3"]}'

POST /v1/science/dossier

One colour rendered in every space at once, plus its colour temperature.

The full lab readout. Expensive relative to convert — reach for it when you want everything, not when you want three spaces.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/science/dossier" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"color":"#c9a227"}'

POST /v1/science/delta-e

Perceptual difference between two colours.

Returns CIE76, CIE94, CIEDE2000 and CMC together, with a plain-language band. CIEDE2000 is the headline figure and is verified against the Sharma reference set.

Request body

Returns delta_e number, band string, metrics object

Example

curl -X POST "https://api.auricartisan.com/v1/science/delta-e" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"from":"#c9a227","to":"#d3af37"}'

POST /v1/science/temperature

Correlated colour temperature from a colour, or the colour of a temperature.

Send color to measure, or kelvin to render. Always returns Duv alongside the CCT — beyond about ±0.05 the colour is too far from the Planckian locus for a temperature to describe it, and meaningful says so.

Request body

Returns cct_kelvin number, duv number, meaningful boolean, tint string

Example

curl -X POST "https://api.auricartisan.com/v1/science/temperature" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"color":"#fff5e1"}'

GET /v1/science/illuminants

Standard reference illuminants with their chromaticities.

Example

curl "https://api.auricartisan.com/v1/science/illuminants" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/science/metrics

The difference formulae, their options, and when to use each.

Example

curl "https://api.auricartisan.com/v1/science/metrics" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/palette/generate

Generate a palette from a seed colour.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/palette/generate" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"method":"triadic","hue":45,"saturation":0.7,"lightness":0.55,"count":5}'

POST /v1/palette/evaluate

Score a palette for harmony, contrast and accessibility.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/palette/evaluate" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"palette":{"colors":[{"rgb":[201,162,39]},{"rgb":[29,42,62]},{"rgb":[255,252,247]}]}}'

POST /v1/palette/export

Render a palette into a design-tool format (ASE, GPL, ACO, …).

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/palette/export" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"format":"css","data":{"colors":[{"rgb":[201,162,39]},{"rgb":[29,42,62]}]}}'

POST /v1/palette/from-image

Extract a palette from an uploaded image.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/palette/from-image" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"image":"iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAIAAAB7QOjdAAAAD0lEQVR42mM4uUhdVssOAAlsAhhwGF0kAAAAAElFTkSuQmCC","count":2}'

POST /v1/palette/png

Generate a palette and render it as a PNG swatch strip.

Takes the generator's fields, as POST /v1/palette/generate does, rather than a list of colours.

Request body

Returns image/png

Example

curl -X POST "https://api.auricartisan.com/v1/palette/png" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"method":"triadic","hue":45,"count":5}'

POST /v1/harmony/generate

Build a harmony set (complementary, triadic, analogous, …) from a base colour.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/harmony/generate" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"method":"triadic","hue":45,"saturation":0.7,"lightness":0.55}'

POST /v1/harmony/classify

Identify which harmony an existing set of colours follows.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/harmony/classify" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"colors":["#FF0000","#00FF00","#0000FF"]}'

POST /v1/harmony/export

Export a harmony set.

Returns the file itself; add ?envelope=json to get it wrapped in JSON.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/harmony/export" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"format":"css","data":{"harmony_id":"brand","colors":[{"hex":"#c9a227","role":"base"},{"hex":"#1d2a3e","role":"complement"}]}}'

POST /v1/gradient/generate

Interpolate a gradient between colours, in a chosen space.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/gradient/generate" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"colors":["#c9a227","#1d2a3e"],"steps":7,"interpolation":"oklab"}'

POST /v1/gradient/export

Export a gradient as CSS, SVG or JSON.

Returns the file itself; add ?envelope=json to get it wrapped in JSON.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/gradient/export" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"format":"css","data":{"colors":[{"hex":"#c9a227","position":0},{"hex":"#1d2a3e","position":1}]}}'

POST /v1/gradient/png

Render a gradient as a PNG.

Request body

Returns image/png

Example

curl -X POST "https://api.auricartisan.com/v1/gradient/png" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"stops":["#c9a227","#1d2a3e"]}'

POST /v1/shade/scale

Build a tint/shade scale from one colour.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/shade/scale" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"color":"#c9a227","steps":9}'

POST /v1/shade/export

Export a shade scale.

Returns the file itself; add ?envelope=json to get it wrapped in JSON.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/shade/export" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"format":"css","data":{"steps":[{"hex":"#c9a227","token":"500"}]}}'

POST /v1/tokens/generate

Turn one seed colour into a complete, contrast-checked token system.

Ramps are stepped in OKLCH so every hue is perceptually even, chroma follows a gamut-aware envelope so the light and dark ends stay distinct, and the foreground roles are measured rather than assumed — --color-on-primary is whichever of white or ink actually clears 4.5:1.

Request body

Returns meta object, contrast array, out_of_gamut string[], tokens array

Example

curl -X POST "https://api.auricartisan.com/v1/tokens/generate" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"seed":"#c9a227","name":"Auric","harmony":"analogous"}'

POST /v1/tokens/export

Render a token deck for a specific platform.

Ten targets, from CSS custom properties to Jetpack Compose. Pass raw: true to get the file itself rather than a JSON envelope.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/tokens/export" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"format":"css","tokens":[{"name":"--color-primary","value":"#c9a227"}]}'

GET /v1/tokens/formats

The ten token export targets.

Example

curl "https://api.auricartisan.com/v1/tokens/formats" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/accessibility/check

Check a foreground/background pair against WCAG 2.2 and APCA.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/accessibility/check" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"fg":"#767676","bg":"#ffffff"}'

POST /v1/accessibility/recommend

Suggest the nearest accessible alternative to a failing pair.

Keeps hue, moves lightness — so the fix still looks like the brand. target chooses which half of the pair is allowed to move, not the level: set the level with minRatio.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/accessibility/recommend" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"fg":"#c9a227","bg":"#ffffff","target":"foreground","minRatio":4.5}'

POST /v1/accessibility/from-image

Audit the colour contrast present in an image.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/accessibility/from-image" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"image":"iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAIAAAB7QOjdAAAAD0lEQVR42mM4uUhdVssOAAlsAhhwGF0kAAAAAElFTkSuQmCC"}'

GET /v1/analyzer/stages

What the analyzer can be asked for, and how much of it a markup-only run can answer.

The vocabulary, generated from the tool's own stage table so the two cannot drift. Each stage carries markup, which is the honest boundary: full is answered completely from the page source, partial is answered more narrowly and says so in incomplete[], and none needs a rendered page and is refused rather than returned empty. Contrast and the accessibility engine are none — without layout and computed styles they would be confidently wrong, which is the one failure an accessibility product cannot ship.

Returns checks_per_token number, always_on string[], stage_ids string[], stages object[], sections object[], notes string[]

Example

curl "https://api.auricartisan.com/v1/analyzer/stages" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/analyzer/inspect

Audit one page from its markup. No browser, no rendering.

Fetches the URL and runs the checks a page SOURCE can answer: structure, the project model, SEO and metadata, response-header security, the sitemap, responsive signals. scope names the stages you want — ask for one and you get one; dependencies are added for you and echoed back under scope.added_by_dependency. There is deliberately no overall score: several categories are never measured here, and scoring a subset as though it were the whole is how a metadata-only run once reported 92 from six checks that never ran. unscored_categories names what was left out and category_scores carries only what was measured. A stage needing a render is refused with RENDER_REQUIRED; palette and media are answered narrowly and say so in incomplete[].

Request body

Returns url string, final_url string, scope object, score null, unscored_categories string[], category_scores object, section_index object[], sections object, incomplete object[]

Example

curl -X POST "https://api.auricartisan.com/v1/analyzer/inspect" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com","scope":["seo","security"]}'

POST /v1/analyzer/render

Turn a report into a document.

Takes a report — the one /v1/analyzer/inspect returned, or one you stored — and renders it. html is a self-contained document; pdf is laid out server-side from text and rules only, so non-Latin content will not appear in it. Markdown is not offered: the developer and client reports are built by a browser module that resolves page elements as it loads, so it cannot run here. The tool still writes both from a saved report without rescanning.

Request body

Returns text/html | application/pdf

Example

curl -X POST "https://api.auricartisan.com/v1/analyzer/render" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"report":{"url":"https://example.com/"},"format":"html"}'

GET /v1/vision/models

The colour-vision deficiency models available.

Example

curl "https://api.auricartisan.com/v1/vision/models" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/vision/simulate

Simulate how a colour appears under a vision deficiency.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/vision/simulate" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"color":"#c9a227","model":"brettel-deutan","severity":1}'

GET /v1/vision/conditions

Every documented vision condition, and what can simulate it.

Parameters

Example

curl "https://api.auricartisan.com/v1/vision/conditions?kind=color" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/vision/conditions/:slug

One condition, with its severity, prevalence and a worked example.

Parameters

Errors UNKNOWN_CONDITION (404) — The slug names no condition in the catalogue.

Example

curl "https://api.auricartisan.com/v1/vision/conditions/deuteranopia" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/vision/matrices

The CVD matrices, for applying the transform yourself.

Example

curl "https://api.auricartisan.com/v1/vision/matrices" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/vision/palette

Run a whole palette through many conditions in one call.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/vision/palette" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"colors":["#D3AF37","#2E8B57"],"conditions":["deuteranopia","tritanopia"]}'

POST /v1/vision/audit

Find which pairs in a palette stop being distinguishable.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/vision/audit" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"colors":["#B22222","#228B22"],"conditions":["deuteranopia"]}'

POST /v1/vision/simulate-image

Simulate a vision deficiency on the dominant colours of an image.

Returns JSON, not an image: the image is reduced to at most eight dominant colours, and each is returned before and after the simulation, with its weight.

Request body

Returns image object, model string, severity number, note string, dominant object[]

Example

curl -X POST "https://api.auricartisan.com/v1/vision/simulate-image" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"image":"iVBORw0KGgoAAAANSUhEUgAAAAIAAAABCAIAAAB7QOjdAAAAD0lEQVR42mM4uUhdVssOAAlsAhhwGF0kAAAAAElFTkSuQmCC","model":"brettel-deutan"}'

POST /v1/ishihara/plate

Generate an Ishihara test plate as structured data.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/ishihara/plate" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"figure":"74","axis":"deutan","size":400}'

POST /v1/ishihara/png

Render an Ishihara plate as a PNG.

Takes the same body as POST /v1/ishihara/plate.

Request body

Returns image/png

Example

curl -X POST "https://api.auricartisan.com/v1/ishihara/png" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"figure":"74","axis":"deutan","size":400}'

GET /v1/usage

Durable per-day, per-endpoint history for your key.

Parameters

Example

curl "https://api.auricartisan.com/v1/usage" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/usage/me

Your tier, limits and month-to-date quota consumption.

Example

curl "https://api.auricartisan.com/v1/usage/me" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/usage/live

The last 100 individual calls, with rolling latency and error stats.

Answers "what is happening right now" where /v1/usage answers "how much have I used". Pass the returned cursor back as since to poll incrementally.

Parameters

Returns cursor number, stats object, events array

Example

curl "https://api.auricartisan.com/v1/usage/live" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/usage/stream SSE

The same live feed, pushed over Server-Sent Events.

Emits hello on connect with current stats, usage per request, and heartbeat every 15 s. Connections are capped at 10 minutes; EventSource reconnects on its own.

Example

curl "https://api.auricartisan.com/v1/usage/stream" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/jobs

The async job types this deployment can run.

Example

curl "https://api.auricartisan.com/v1/jobs" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/jobs/:type

Queue a long-running job and get an id back immediately.

The body is the parameter set for the chosen job type, so its shape varies — GET /v1/jobs documents what each type accepts. Poll /v1/jobs/id/:id or follow /v1/jobs/id/:id/stream.

Parameters

Example

curl -X POST "https://api.auricartisan.com/v1/jobs/palette-batch" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"count":500}'

GET /v1/jobs/id/:id

Poll one job.

Parameters

Example

curl "https://api.auricartisan.com/v1/jobs/id/<id>" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/jobs/id/:id/stream SSE

Follow a job to completion over SSE instead of polling.

Parameters

Example

curl "https://api.auricartisan.com/v1/jobs/id/<id>/stream" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/webhooks/events No key

Event types you can subscribe to.

Public: it is a static list of event names, useful for deciding whether the API fits before you buy.

Example

curl "https://api.auricartisan.com/v1/webhooks/events"

GET /v1/webhooks

List your webhook subscriptions.

Example

curl "https://api.auricartisan.com/v1/webhooks" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/webhooks

Subscribe a URL to one or more events.

Deliveries are signed; verify the signature header before trusting a payload.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/webhooks" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com/hook","events":["job.succeeded"]}'

GET /v1/webhooks/:id

Fetch one subscription.

Parameters

Example

curl "https://api.auricartisan.com/v1/webhooks/<id>" \
  -H "x-api-key: $AURIC_API_KEY"

DELETE /v1/webhooks/:id

Revoke a subscription.

Parameters

Example

curl -X DELETE "https://api.auricartisan.com/v1/webhooks/<id>" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/graphql No key

GraphQL playground.

Example

curl "https://api.auricartisan.com/v1/graphql"

POST /v1/graphql

Run a GraphQL query against the same resolvers as the REST surface.

Useful when one round trip should answer several questions — convert a colour, check its contrast and simulate it at once.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/graphql" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"{ colorContrast(fg: \"#000\", bg: \"#fff\") { ratio wcag { aaNormal } } }"}'

GET /v1/admin/keys Admin

List issued API keys.

Example

curl "https://api.auricartisan.com/v1/admin/keys" \
  -H "x-admin-key: $AURIC_ADMIN_KEY"

POST /v1/admin/keys Admin

Issue a key. The secret is shown once and stored only as a hash.

Request body

Example

curl -X POST "https://api.auricartisan.com/v1/admin/keys" \
  -H "x-admin-key: $AURIC_ADMIN_KEY" \
  -H "content-type: application/json" \
  -d '{}'

GET /v1/admin/keys/:id Admin

Fetch one key record (never the secret).

Parameters

Example

curl "https://api.auricartisan.com/v1/admin/keys/<id>" \
  -H "x-admin-key: $AURIC_ADMIN_KEY"

DELETE /v1/admin/keys/:id Admin

Revoke a key immediately.

Parameters

Example

curl -X DELETE "https://api.auricartisan.com/v1/admin/keys/<id>" \
  -H "x-admin-key: $AURIC_ADMIN_KEY"

GET /v1/color/atlas

Browse the 8,192-colour atlas under a filter.

A finite catalogue, so matched is how many of the 8,192 qualify -- a real total, not a scan rate. hue_from/hue_to wrap, so hue_from=340&hue_to=20 is the reds. Page with offset; the summary record is the default and full=true adds the vision simulations and labels.

Parameters

Returns matched number, share_of_atlas number, next_offset number|null, colors object[]

Example

curl "https://api.auricartisan.com/v1/color/atlas?min_contrast_on_white=4.5&sort=chroma&order=desc&limit=5" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/color/atlas/stats

What the atlas actually contains.

Counted from the records: hue occupancy, the lightness spread, the label vocabulary, and how much of the catalogue is usable as text on white or on black -- which is the question a designer reaching for a colour is really asking.

Returns readable_as_text object, hue_distribution object[], lightness_distribution object[], labels object

Example

curl "https://api.auricartisan.com/v1/color/atlas/stats" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/color/atlas/:id

Resolve one sample, whole.

Takes the numeric id or a hex the atlas contains. For a colour that is NOT in the atlas, use POST /v1/color/nearest.

Parameters

Returns color object

Errors INVALID_INPUT (400) — No sample with that id or hex.

Example

curl "https://api.auricartisan.com/v1/color/atlas/0" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/color/nearest

The catalogued colours closest to one you already have.

This is what makes the atlas useful on a real brand: give it your hex and get the nearest sampled colours with all their metadata. Distance is CIE76 in Lab -- a straight walk over the whole atlas in about a millisecond -- and the response names the metric rather than leaving you to assume it.

Request body

Returns metric string, matches object[]

Example

curl -X POST "https://api.auricartisan.com/v1/color/nearest" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"color":"#D3AF37","count":5}'

GET /v1/accessibility/corpus

Browse the five-million-pair corpus under a filter, with a cursor.

Records are derived from a seed, not fetched from a table, so paging costs arithmetic. Read scanned and hit_rate alongside records: 88% of the corpus fails AA for body text, so twenty-four AAA pairs may represent seven hundred looked at. When truncated is true the scan budget ran out before the page filled -- follow next_cursor rather than assuming the filter is empty.

Parameters

Returns count number, scanned number, hit_rate number, next_cursor number|null, exhausted boolean, truncated boolean, records object[]

Example

curl "https://api.auricartisan.com/v1/accessibility/corpus?level=AAA&limit=5" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/accessibility/corpus/stats

The measured distribution of contrast across the corpus.

Counted, not asserted -- it walks a deterministic prefix, so the same sample always returns the same numbers. This is the endpoint that says most colour pairs are unusable, which a "5,000,000 combinations" claim hides.

Parameters

Returns sample number, mean_contrast_ratio number, share_at_least object, share_failing_aa_body number, distribution object[]

Example

curl "https://api.auricartisan.com/v1/accessibility/corpus/stats?sample=50000" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/accessibility/corpus/:record_id

Resolve one record by id or index.

The citation endpoint. Put acc_2j in a report and anyone can recover the same two colours from the seed, without being handed a database. Accepts either the record id or a bare corpus index.

Parameters

Returns record object, cite string, recompute string

Errors INVALID_INPUT (400) — The id does not parse, or the index is outside the corpus.

Example

curl "https://api.auricartisan.com/v1/accessibility/corpus/acc_2j" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/accessibility/map

The whole territory of foreground colour a background leaves you.

For each hue, the lightness at which the most saturated colour of that hue just reaches the target on this ground. territory_pct is the share of the slice that qualifies -- which is how one background gets compared with another, rather than with a threshold. A null lightness means that hue never reaches the target at any lightness, which is a real answer and worth surfacing.

Request body

Returns ground string, polarity string, contours object[]

Example

curl -X POST "https://api.auricartisan.com/v1/accessibility/map" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ground":"#1D2A3E","targets":[4.5,7]}'

POST /v1/accessibility/picks

A ready set of foregrounds that clear a target on one background.

Walks the hue circle, takes each hue to its boundary lightness, then steps margin past it so rounding cannot land a pick under the target. Hues that still cannot make it are dropped and counted, because a set whose promise is that everything in it works has to keep that promise.

Request body

Returns count number, dropped number, picks object[]

Example

curl -X POST "https://api.auricartisan.com/v1/accessibility/picks" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ground":"#1D2A3E","target":4.5,"count":12}'

POST /v1/accessibility/audit

Audit a palette against one background, with a fix for each failure.

The fix keeps the hue and moves the lightness onto the contour, so a corrected brand colour still looks like the brand. Where a hue cannot reach the target on that ground at all, it says so instead of returning a colour that does not work.

Request body

Returns verdict string, passing number, failing number, results object[]

Example

curl -X POST "https://api.auricartisan.com/v1/accessibility/audit" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ground":"#1D2A3E","colors":["#D3AF37","#4A5568","#F7FAFC"],"target":4.5}'

GET /v1/gradient/library

Browse the 8,192-gradient collection under a filter.

A finite catalogue, so matched is a real total rather than a scan rate. The filter worth reaching for is banding: about one gradient in five steps visibly somewhere, and that is the thing a thumbnail cannot show you.

Parameters

Returns matched number, share_of_collection number, next_offset number|null, gradients object[]

Example

curl "https://api.auricartisan.com/v1/gradient/library?banding=smooth&sort=score&order=desc&limit=5" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/gradient/library/stats

What the collection contains, counted rather than asserted.

The headline is the banding split: how much of a generated set actually steps smoothly. Also the scheme, complexity, interpolation-space and easing tallies.

Returns banding object[], scheme object[], interpolation_space object[]

Example

curl "https://api.auricartisan.com/v1/gradient/library/stats" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/gradient/library/:id

One gradient, whole.

Parameters

Returns gradient object

Errors INVALID_INPUT (400) — The id is not a row in the collection.

Example

curl "https://api.auricartisan.com/v1/gradient/library/0" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/gradient/analyse

Measure a gradient you already have: will it band, and where?

Samples the ramp, converts each sample to OKLab, and measures the perceptual distance between consecutive samples. The verdict is the WORST step against the AVERAGE one -- a ratio, so it does not move when you ask for more samples. The thresholds are not invented: measured across 3,000 gradients the generator had already labelled, that ratio runs a median of 1.55 for the ones it calls smooth and 5.09 for the ones it calls a step risk. worst_transition_at says WHERE, which is the part you can act on.

Request body

Returns banding string, step_ratio number, delta_e_mean number, delta_e_max number, worst_transition_at number, note string

Example

curl -X POST "https://api.auricartisan.com/v1/gradient/analyse" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"stops":["#001a33","#003d66","#ffcc00"]}'

GET /v1/harmony/library

Browse the 8,192-harmony collection under a filter.

A finite catalogue, so matched is a real total rather than a scan rate. The filter worth reaching for is min_contrast: only about a quarter of the collection contains a pair that carries body text, which is the thing a row of swatches cannot show you.

Parameters

Returns matched number, share_of_collection number, next_offset number|null, harmonies object[]

Example

curl "https://api.auricartisan.com/v1/harmony/library?family=polyadic&sort=contrast&order=desc&limit=5" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/harmony/library/stats

What the collection contains, counted rather than asserted.

The headline is with_an_aa_pair: how much of a generated set of colour schemes actually contains two members that can be used as text on each other. Also the method, family and size tallies.

Returns with_an_aa_pair object, method object[], family object[], color_count object[]

Example

curl "https://api.auricartisan.com/v1/harmony/library/stats" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/harmony/library/:id

One harmony, whole, with the derivation that reproduces it.

Records are not stored: each is computed from the manifest seed and its index, so the response carries the seed and batch that recompute it. That is what makes a harmony id citable rather than a row number.

Parameters

Returns harmony object

Errors INVALID_INPUT (400) — The id names no harmony in the collection.

Example

curl "https://api.auricartisan.com/v1/harmony/library/har_0" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/harmony/identify

Name the scheme the colours you already have form.

Takes 2-12 colours and matches their hue pattern against all 23 schemes. Anchored on each colour in turn, so the answer does not depend on the order you send them in -- which also matters because several schemes' canonical angles are written relative to their MIDDLE member. Schemes that are the same shape on the hue circle and differ only in lightness or saturation (shades and monochromatic_5; triad_shifted and triadic) come back together in ties rather than one being chosen for you.

Request body

Returns verdict string, best_match object, ties string[], candidates object[], hue_offsets number[], min_pair_contrast number, carries_body_text boolean

Example

curl -X POST "https://api.auricartisan.com/v1/harmony/identify" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"colors":["#FF0000","#00FF00","#0000FF"]}'

GET /v1/palette/library

Browse five million generated palettes under a filter.

Palettes are derived from a seed, not stored -- the expanded form would be 3.9 GB. Nothing can walk five million inside a request, so a filtered browse SCANS: it reports scanned, hit_rate, and the two flags that matter. exhausted means the collection really ended. truncated means the scan budget ran out first, which is NOT the same thing -- a rare filter legitimately returns an empty page with a cursor, and a client that stops there stops short of the first match.

Parameters

Returns scanned number, hit_rate number, next_cursor number|null, exhausted boolean, truncated boolean, palettes object[]

Example

curl "https://api.auricartisan.com/v1/palette/library?carries_body_text=true&limit=5" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/palette/library/stats

What the collection looks like, measured on a stated sample.

Five million palettes cannot be counted inside a request, so this measures 70 runs of 600 consecutive palettes spread across the collection and reports the sample size with every figure. The headline: about 55% of these contain a pair that carries body text -- far more than a harmony collection, because five random colours differ in lightness where five hue rotations do not.

Returns measured_on object, with_an_aa_pair object, method object[], character object[]

Example

curl "https://api.auricartisan.com/v1/palette/library/stats" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/palette/library/:id

One palette, whole, with the derivation that reproduces it.

Records are computed from the manifest seed and their index, so the response carries the seed and batch that recompute them. A palette id is a claim anyone can check rather than a row somebody could edit.

Parameters

Returns palette object

Errors INVALID_INPUT (400) — The id names no palette in the collection.

Example

curl "https://api.auricartisan.com/v1/palette/library/pal_0" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/personalize/vocabulary

Everything a brief may name, with the ranges the engine really imposes.

The 18 style profiles with the chroma, lightness and saturation windows each one applies, the five intents, the 19 hue relationships and their offsets, the 17 type systems, and the gradient and poster catalogues. Read this before writing a brief: it is why neon cannot return a pastel.

Returns styles array, intents string[], relationships array, type_systems array, limits object

Example

curl "https://api.auricartisan.com/v1/personalize/vocabulary" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/personalize/presets

The 17 briefs the tool ships, in request shape.

Each brief can be posted straight to any endpoint in this group.

Returns count integer, presets array

Example

curl "https://api.auricartisan.com/v1/personalize/presets" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/personalize/pool

Grow a working set of colours from seeds and a brief.

The generator searches WITHIN a pool, so the pool decides how wide the search is. This is that growth step alone, for a caller who wants to inspect or edit the colours before sweeping them. The response also returns the brief resolved to numbers: what a style plus a warmth actually means to the engine.

Request body

Returns brief object, pool string[], profile object

Example

curl -X POST "https://api.auricartisan.com/v1/personalize/pool" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"colors":["#0F172A","#D3AF37"],"styles":["luxe","editorial"],"target":24}'

POST /v1/personalize/score

Rank a palette you already have, on the search’s own six scores.

Preference, harmony, diversity, contrast, style fit and accessibility — the same scorers the search ranks by, so a palette from a brand book can be measured against the brief you care about. Omit relationship and every hue geometry is tried and the best-fitting reported, which is the answer to what a palette actually is.

Request body

Returns score object, measured_as object, best_pair object, alternatives array

Example

curl -X POST "https://api.auricartisan.com/v1/personalize/score" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"palette":["#0F172A","#F8FAFC","#D3AF37","#14B8A6"],"styles":["tech","minimal"]}'

POST /v1/personalize/palettes

Search: N candidates in, the best K out, each with its breakdown.

The response reports what the sweep DID, not only what it kept — how many candidates were sampled, how many survived de-duplication, and where the cut fell. Contrast and colour-vision are WEIGHTS in the score, never filters: a candidate that reads badly is ranked down, not discarded, so kept does not mean the accessible ones.

Request body

Returns brief object, sweep object, palettes array

Example

curl -X POST "https://api.auricartisan.com/v1/personalize/palettes" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"colors":["#0F172A","#D3AF37"],"styles":["luxe","editorial"],"intent":"brand","depth":400,"keep":12}'

POST /v1/personalize/system

One brief in, an entire design system out.

The sweep, then from its leader: gradients, type pairings, UI colour pairs with WCAG and APCA measured, poster compositions, and a production token deck with tonal ramps, synced light/dark/high-contrast themes and a contrast matrix. include trims the response and skips the work, not just the serialisation.

Request body

Returns leader object, palettes array, gradients array, typography array, ui_pairs array, posters array, tokens object

Example

curl -X POST "https://api.auricartisan.com/v1/personalize/system" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"colors":["#0F172A","#D3AF37"],"styles":["tech","minimal"],"intent":"ui","include":["tokens","ui_pairs"]}'

GET /v1/shade/library

Browse 8,192 measured shade scales under a filter.

Every scale carries three measurements a token ramp lives or dies by: whether it runs one way, how even its steps are, and whether any step can carry text on any other. All 8,192 are monotonic and all can carry text -- what actually separates them is evenness, and only 8.2% are clean.

Parameters

Returns matched number, share_of_collection number, next_offset number|null, scales object[]

Example

curl "https://api.auricartisan.com/v1/shade/library?evenness=even&sort=span&order=desc&limit=5" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/shade/library/stats

What the collection contains, counted rather than asserted.

The headline is the evenness split. Monotonicity and text-carrying are 100% here, which is worth knowing precisely because it means neither is a useful filter -- evenness is.

Returns evenness object[], monotonic object, carries_body_text object, method object[]

Example

curl "https://api.auricartisan.com/v1/shade/library/stats" \
  -H "x-api-key: $AURIC_API_KEY"

GET /v1/shade/library/:id

One scale, whole, with every measurement.

Parameters

Returns scale object

Errors INVALID_INPUT (400) — The id names no scale in the collection.

Example

curl "https://api.auricartisan.com/v1/shade/library/shade_000000" \
  -H "x-api-key: $AURIC_API_KEY"

POST /v1/shade/evaluate

Measure a scale you already have: does it work as a token ramp?

Runs the collection's own three measurements against your steps. A scale fails in one of three ways and each has a different fix, so the response says which: it TURNS ROUND (two steps read as the same tone), its steps are LUMPY (the largest is several times the average, which is what makes a scale feel arbitrary in use), or its extremes are too close to set text between (a surface ramp, not a text scale).

Request body

Returns verdict string, notes string[], monotonic boolean, step_ratio number, evenness string, usable_span number, text_pairs object

Example

curl -X POST "https://api.auricartisan.com/v1/shade/evaluate" \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"steps":["#FFFFFF","#E0E0E0","#A0A0A0","#606060","#202020"]}'