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.

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.