API Documentation

Introduction

The Precision Contrast API provides programmatic access to color contrast checking and palette generation. It's RESTful and returns JSON responses.

Authentication

Currently, the API is free to use without authentication. Rate limiting may be implemented in the future.

Endpoints

{
  "foreground": "#000000",  // Hex color code for text
  "background": "#FFFFFF"   // Hex color code for background
}

{
  "contrast": 21,          // Contrast ratio
  "AA": {
    "normal": true,       // Passes AA for normal text
    "large": true        // Passes AA for large text
  },
  "AAA": {
    "normal": true,      // Passes AAA for normal text
    "large": true       // Passes AAA for large text
  },
  "foreground": "#000000",
  "background": "#FFFFFF"
}

fetch('/api/v1/contrast', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    foreground: '#000000',
    background: '#FFFFFF'
  })
})
.then(response => response.json())
.then(data => console.log(data));

{
  "color": "#1A365D",     // Base hex color code
  "type": "accessible"    // Optional: "accessible" | "analogous" | "all"
}

{
  "palettes": [
    {
      "name": "Accessible Combinations",
      "colors": [
        {
          "foreground": "#1A365D",
          "background": "#FFFFFF",
          "contrast": 12.5,
          "AA": {
            "normal": true,
            "large": true
          },
          "AAA": {
            "normal": true,
            "large": true
          }
        },
        // ... more color combinations
      ]
    },
    {
      "name": "Analogous Combinations",
      "colors": [
        // ... analogous color combinations
      ]
    }
  ]
}

fetch('/api/v1/palettes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    color: '#1A365D',
    type: 'all'
  })
})
.then(response => response.json())
.then(data => console.log(data));

Error Handling

{
  "error": "Both foreground and background colors are required"
}

{
  "error": "Colors must be in valid hex format (e.g., #FF0000)"
}

{
  "error": "Internal server error"
}

Rate Limiting

These endpoints allow 20 requests per 10 seconds per IP. Exceeding that returns 429 with RateLimit-Limit, RateLimit-Reset and Retry-After headers. Handle 429 by backing off until Retry-After elapses.

Code Examples

Quick examples for common languages:

// npm install accessibility-checker-api

import { AccessibilityChecker } from 'accessibility-checker-api';

const checker = new AccessibilityChecker();
const result = await checker.checkContrast('#000000', '#FFFFFF');

# pip install accessibility-checker

from accessibility_checker import ContrastChecker

checker = ContrastChecker()
result = checker.check_contrast('#000000', '#FFFFFF')