Integration · Setup

REST API Color conversion and contrast checks from your own code

The API answers JSON over HTTPS with the same color engine as the site. It needs a key from a Specialist plan. This guide makes a first request and turns a failing pair into a passing one; the reference documents every endpoint.

Open the API reference Set it up
  1. 01Create a key
  2. 02Keep it out of your code
  3. 03Make a first request
Version
v1
Needs
A Specialist plan
Cost
1,000,000 credits a month on Specialist
Checked

Before you start

What you need

  • A Specialist plan. Apprentice and Artisan plans have no API access.
  • curl, Node.js 18 or later, or Python 3 to run the examples.
  • A safe place for the key, such as an environment variable or your platform’s secret store.

Setup

Step by step

  1. Create a key

    In the dashboard, open API Keys and create one. The full key is shown once, so copy it then. An account can hold up to ten active keys and revoke any of them.

  2. Keep it out of your code

    Put the key in an environment variable. The examples on this page read it from there.

    Shell

    # macOS and Linux
export AURIC_API_KEY="aa_your_key"

# Windows PowerShell
$env:AURIC_API_KEY = "aa_your_key"

  3. Make a first request

    Send the key in the x-api-key header. This converts the color to OKLCH.

    curl

    curl -X POST https://api.auricartisan.com/v1/color/convert \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"color":"#3959DA","to":"oklch"}'

    The response

    {
  "input": {
    "rgb": [57, 89, 218],
    "hex": "#3959da"
  },
  "to": "oklch",
  "value": [0.5200949117697137, 0.20040190508504732, 267.94419335549696]
}

    You should see: The JSON below, and an x-credits-cost header saying the call cost 1 credit. Without a key, the API answers 401 with UNAUTHENTICATED.

A first task

Check a pair, then get one that passes

Two calls: the first measures gray text on white against WCAG 2.2, the second asks for the nearest text color that reaches 4.5:1. The responses are the API’s own, from running these requests.

1. Check the pair

curl

curl -X POST https://api.auricartisan.com/v1/accessibility/check \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fg":"#8A8A8A","bg":"#FFFFFF","standard":"WCAG 2.2"}'

JavaScript (Node.js 18+)

const res = await fetch("https://api.auricartisan.com/v1/accessibility/check", {
  method: "POST",
  headers: { "x-api-key": process.env.AURIC_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ fg: "#8A8A8A", bg: "#FFFFFF", standard: "WCAG 2.2" }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(JSON.stringify(await res.json()));

Python 3 (standard library)

import json, os, urllib.request

req = urllib.request.Request(
    "https://api.auricartisan.com/v1/accessibility/check",
    data=json.dumps({"fg": "#8A8A8A", "bg": "#FFFFFF", "standard": "WCAG 2.2"}).encode(),
    headers={"x-api-key": os.environ["AURIC_API_KEY"], "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req) as res:
    print(json.dumps(json.load(res)))

The response

{
  "fg": [138, 138, 138],
  "bg": [255, 255, 255],
  "standard": "WCAG 2.2",
  "result": {
    "standard": "WCAG 2.2",
    "contrast_ratio": 3.45,
    "1.4.3_AA_normal": false,
    "1.4.3_AA_large": true,
    "1.4.6_AAA_normal": false,
    "1.4.6_AAA_large": false,
    "1.4.11_non_text": true,
    "pass_level": "AA-large",
    "2.4.11_focus_not_obscured": null,
    "2.4.13_focus_appearance_AAA": true,
    "2.5.8_target_size_outline": null,
    "2.5.7_dragging_affordance": null
  }
}

The ratio is 3.45:1, so the pair passes AA only for large text: pass_level is AA-large.

2. Ask for a passing color

curl

curl -X POST https://api.auricartisan.com/v1/accessibility/recommend \
  -H "x-api-key: $AURIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fg":"#8A8A8A","bg":"#FFFFFF","minRatio":4.5}'

JavaScript (Node.js 18+)

const res = await fetch("https://api.auricartisan.com/v1/accessibility/recommend", {
  method: "POST",
  headers: { "x-api-key": process.env.AURIC_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ fg: "#8A8A8A", bg: "#FFFFFF", minRatio: 4.5 }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(JSON.stringify(await res.json()));

Python 3 (standard library)

import json, os, urllib.request

req = urllib.request.Request(
    "https://api.auricartisan.com/v1/accessibility/recommend",
    data=json.dumps({"fg": "#8A8A8A", "bg": "#FFFFFF", "minRatio": 4.5}).encode(),
    headers={"x-api-key": os.environ["AURIC_API_KEY"], "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req) as res:
    print(json.dumps(json.load(res)))

The response

{
  "target": "foreground",
  "minRatio": 4.5,
  "recommended": [118, 118, 118]
}

The recommended text color is [118, 118, 118], which is #767676: the same hue, darker, at 4.54:1.

Limits

What it does not do

  • Specialist allows 300 requests a minute and 1,000,000 credits a month, pooled across all of an account’s keys. Past the limit the API answers 429 with a retry-after header.

  • Production serves 89 endpoints. GET /v1 lists them, and the reference marks what each one costs.

  • The client packages named in the reference (@auric-artisan/api, @auric-artisan/cli, auric-artisan) are not published yet. Call the API over HTTP, as here.

Privacy and access

Keeping a key safe

  • Call the API from a server or a script, never from code that runs in a visitor’s browser, where the key can be read.
  • Keys are stored only as a SHA-256 hash, so a lost key cannot be recovered: create a new one.
  • If a key leaks, revoke it in the dashboard; revocation takes effect within a minute.

Go further

The full reference

Other integrations

Checked against

Where these facts come from

Versions, requirements and examples on this page were checked on . The endpoint list, plans and the answer to a request without a key were read from https://api.auricartisan.com; the responses shown come from the API’s own server running these exact requests; the client packages were looked up on npm and PyPI.

Found a mistake? Write to us and we will correct it.