API Reference

REST API for submitting analyses and retrieving results programmatically. Keys are managed in the dashboard.

Authentication

All API requests require an API key (except GET /health). Generate one from Dashboard → Settings → API Keys.

Include your key in every request using either:

Authorization: Bearer bl_live_your_key_here

Or:

X-API-Key: bl_live_your_key_here

Replace bl_live_your_key_here with your real secret.

Base URL

https://buyologylabs.com/api/v1

Endpoint paths below are relative to this base. In development: http://localhost:3000/api/v1.

Rate limits

60 requests per hour per API key (rolling window; configurable per key in the dashboard).
Rate limit headers are included on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp in seconds).

Endpoints

POST /analyses

Submit a new analysis.

Request body

{
  "title": "Q1 Campaign Banner",
  "asset_url": "https://example.com/banner.jpg",
  "asset_type": "image",
  "target_demographics": {
    "age_group": "25-34",
    "gender": "all",
    "lsm_tier": "all",
    "province": "national",
    "context": "Fast food promotion targeting urban youth"
  }
}

Returns 202 Accepted when queued. One credit is deducted when the request is accepted. 402 if you have no credits.

Response

{
  "analysis_id": "uuid",
  "status": "processing"
}

GET /analyses

List your analyses.

Query parameters

limit — default 10, max 100
offset — default 0
status — "completed" | "processing" | "failed"

Response

{
  "analyses": [...],
  "total": 42,
  "limit": 10,
  "offset": 0
}

GET /analyses/:id

Get full analysis results for an ID that belongs to your account. Response is the full analysis object including neural metrics, geographic insights, recommendations, and parsed results when completed.

Measurement governance (PRD-008): every client-bound score passes through the release serializer. When a value is released, it remains a JSON number. When a value is withheld, the field is present as a structured refusal — never null, never 0, never omitted:

{
  "shown": false,
  "constructId": "neuroscore",
  "state": "INSUFFICIENT_MEASUREMENT_RELIABILITY"
}

state is a K9.5 insufficiency token or RETIRED. Consumers must distinguish withheld (object with shown: false) from absent (path not present on the stored payload). Production enforcement is on by default: INTERNAL Tier B/C fields return the refusal object unless explicitly released.

Score interpretation

A creative score estimates properties of the asset under a defined assessment method. It does not estimate realised attention, recall, persuasion or conversion in a live placement without explicit environmental, audience, delivery and validation evidence.

GET /health

Health check — no authentication. Not under /api/v1; use the site origin:

GET https://buyologylabs.com/api/health

Response

{
  "status": "healthy",
  "services": {
    "database": "connected",
    "ai": "configured",
    "payments": "configured",
    "email": "configured"
  }
}

The live endpoint may also include fields such as timestamp, version, and uptime.

Error codes

400 — Bad request (invalid input)
401 — Invalid or missing API key
403 — Insufficient permissions
429 — Rate limit exceeded (body may include retryAfter)
500 — Internal server error

CORS

/api/v1/* allows cross-origin requests with Access-Control-Allow-Origin: *. Methods: GET, POST, OPTIONS. Preflight requests return 204.