Public API

All public API endpoints require the X-HiveGuard-Key header.

Base path: /api/v1/

Health

GET /api/v1/health

Check server health. No authentication required.

Response 200:

{"status": "ok", "version": "0.3.0"}

Challenge

GET /api/v1/challenge/generate

Generate a new challenge.

Query parameters:

Parameter	Type	Description
modality	string	Filter by modality: image, text, audio

Response 200:

{
  "challenge_id": "chal_abc123",
  "items": [
    {
      "id": "item_xyz",
      "data_ref": "https://cdn.example.com/img001.jpg",
      "modality": "image",
      "prompt": "Does this image contain a cat?"
    }
  ],
  "expires_at": "2024-01-01T12:05:00Z"
}

Response 204: Challenge pool is empty. The request is allowed through (Tier-4 fail-open). No body.

POST /api/v1/challenge/submit

Submit a response to a challenge.

Request body:

{
  "challenge_id": "chal_abc123",
  "responses": [
    {"item_id": "item_xyz", "answer": "yes"}
  ]
}

Response 200 (passed):

{"passed": true, "token": "eyJhbGci..."}

Response 200 (failed):

{"passed": false, "token": null}

GET /api/v1/challenge/generate/{modality}

Generate a challenge filtered to a specific modality. Same response shape as above.

Data

GET /api/v1/data/items

List ground-truth items visible to this API key.

Query parameters:

Parameter	Type	Default	Description
limit	int	100	Items per page (max 1000)
offset	int	0	Pagination offset

Response 200: JSON array of item objects.

[
  {
    "id": "00000000-...",
    "dataset_id": "00000000-...",
    "data_ref": "https://example.com/img.jpg",
    "modality": "image",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

GET /api/v1/data/labeled

List finalized labels.

Query parameters: Same as /data/items.

Response 200: JSON array of label objects.

[
  {
    "item_id": "00000000-...",
    "data_ref": "https://example.com/img.jpg",
    "modality": "image",
    "label": "yes",
    "confidence": 0.92,
    "solver_count": 5,
    "created_at": "2024-01-01T00:00:00Z"
  }
]

POST /api/v1/data/items

Upload ground-truth items.

Request body:

{
  "items": [
    {
      "dataset_id": "00000000-...",
      "data_ref": "https://example.com/img.jpg",
      "modality": "image"
    }
  ]
}

Maximum 1,000 items per request. Use the CLI’s batching for larger uploads.

Response 201:

{"created": 1000, "item_ids": ["00000000-...", ...]}