API Documentation

Hawke Compare provides a REST API for programmatic image upload and comparison management. Use it to automate screenshot capture workflows, CI pipelines, and more.

Authentication

All write operations require authentication. Two methods are supported:

Authorization: Bearer hc_your_api_key_here

Public read operations (listing and viewing comparisons) require no authentication.

Base URL

http://localhost:3000

Comparisons

GET /api/comps

List recent public comparisons. No auth required.

Query parameters

  • limit — results (default 20, max 100)
  • offset — pagination offset
POST /api/comps

Create a new comparison. Requires API key auth.

Request body (JSON)

{
  "title": "Netflix vs Amazon vs Blu-ray",
  "description": "Episode 5, season 2",
  "labels": ["Netflix", "Amazon", "Blu-ray"]
}

Response

{
  "id": "abc12345",
  "title": "Netflix vs Amazon vs Blu-ray",
  "upload_token": "abc...xyz",
  "labels": [
    { "id": "lbl001", "name": "Netflix",  "position": 0 },
    { "id": "lbl002", "name": "Amazon",   "position": 1 },
    { "id": "lbl003", "name": "Blu-ray",  "position": 2 }
  ],
  "url": "/c/abc12345"
}

Example

curl -X POST /api/comps \
  -H "Authorization: Bearer hc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Comparison","labels":["Source A","Source B"]}'
GET /api/comps/:id

Retrieve full comparison data including labels and images. No auth required.

DELETE /api/comps/:id

Delete a comparison. Requires API key (owner) or the comparison's upload token.

curl -X DELETE /api/comps/abc12345 \
  -H "Authorization: Bearer hc_your_api_key"

Uploading Images

POST /api/comps/:id/images

Upload images to a comparison. Accepts multipart/form-data. Max 50 images per request, 50 MB per file.

Form fields

  • images (required) — image files (JPEG, PNG, WebP, AVIF, GIF)
  • label (optional) — label name, 0-based index, or label ID. Defaults to first label.
  • frame (optional) — integer frame number. Auto-increments per label if omitted.

Example — sequential label upload

COMP_ID="abc12345"
TOKEN="your_upload_token"
BASE=

for f in screenshots/netflix/*.png; do
  curl -X POST $BASE/api/comps/$COMP_ID/images \
    -H "Authorization: Bearer $TOKEN" \
    -F "images=@$f" -F "label=Netflix"
done

for f in screenshots/bluray/*.png; do
  curl -X POST $BASE/api/comps/$COMP_ID/images \
    -H "Authorization: Bearer $TOKEN" \
    -F "images=@$f" -F "label=Blu-ray"
done

API Keys

POST /api/keys

Create a new API key (requires login session). The full key is shown once only.

Response

{
  "id": "key00001",
  "name": "My automation script",
  "key": "hc_a1b2c3d4e5f6...",
  "prefix": "hc_a1b2"
}

Complete Workflow Example

#!/bin/bash
BASE=
API_KEY="hc_your_api_key"

# 1. Create comparison
RESP=$(curl -s -X POST $BASE/api/comps \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Encode Test","labels":["x264","x265","AV1"]}')

COMP_ID=$(echo $RESP | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
TOKEN=$(echo $RESP | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_token'])")

echo "Created: $BASE/c/$COMP_ID"

# 2. Upload up to 50 frames per batch
for label in x264 x265 AV1; do
  for img in frames/$label/*.png; do
    curl -s -X POST $BASE/api/comps/$COMP_ID/images \
      -H "Authorization: Bearer $TOKEN" \
      -F "images=@$img" -F "label=$label" > /dev/null
  done
done

echo "Done: $BASE/c/$COMP_ID"

Limits