HomeAtlasChangelog
Worker surface · supported endpoints
Docs

API Reference

This page documents the current edge worker contract. It mirrors the routes implemented in worker/src/index.js.

Base URL
https://<your-worker-domain>
All routes below are relative to your deployed worker domain.
Authentication
Authorization: Bearer <token>
Most endpoints can be gated via API_AUTH_REQUIRED. Token management requires a platform JWT.
Browser sessions should expose POST /api/v1/auth/refresh to renew the session cookie from a refresh-token HttpOnly cookie.
Upstream Keys
OPENAI_API_KEY for chat completions
MISTRAL_API_KEY for OCR
CHROMA_BASE_URL + CHROMA_API_KEY for Chroma

Surface

Supported endpoints

A readable snapshot of what's live in the worker, grouped by capability.

Source of truth: worker/src/index.js
supported_endpoints 
app.get('/v1/api-tokens')
app.post('/v1/api-tokens')
app.delete('/v1/api-tokens/:tokenId')

app.get('/v1/usage')
app.get('/v1/usage/daily')
app.get('/v1/usage/rollups')

app.all('/v1/chat/completions')
app.all('/v1/ocr')

app.all('/v1/chroma')
app.all('/v1/chroma/*')
Notes: methods shown match the worker's route registration.

API Tokens

Manage API tokens (requires platform JWT; API tokens are not allowed here).

3 routes
  • GET /v1/api-tokens
    List API tokens for the current user.
    Headers
    • Authorization : Bearer <platform_jwt> Required.
    Response
    data
    array · Token records for the current user.
    Notes
    • Requires a platform JWT; API tokens are rejected here.
  • POST /v1/api-tokens
    Create a new API token.
    Headers
    • Authorization : Bearer <platform_jwt> Required.
    • Content-Type : application/json Required.
    Body
    name
    string · Optional token display name.
    scopes
    string[] · Optional; must be an array of strings.
    Response
    id
    string · Token id.
    token
    string · Returned once at creation time.
    ...
    any · Additional token metadata.
    Notes
    • Requires a platform JWT; API tokens are rejected here.
  • DELETE /v1/api-tokens/:tokenId
    Revoke an API token.
    Headers
    • Authorization : Bearer <platform_jwt> Required.
    Path params
    tokenId
    string · Token id to revoke.
    Response
    status
    204 · No content on success.
    Notes
    • Requires a platform JWT; API tokens are rejected here.

LLM Gateway

OpenAI-compatible chat completions proxy (streaming supported).

1 routes
  • POST /v1/chat/completions
    Proxy to upstream `/v1/chat/completions`.
    Headers
    • Content-Type : application/json Required.
    • Authorization : Bearer <token> Required only when API_AUTH_REQUIRED=1.
    • OpenAI-Organization : <org_id> Optional; forwarded to upstream.
    • OpenAI-Project : <project_id> Optional; forwarded to upstream.
    Body
    model
    string · Required by upstream; logged for analytics.
    messages
    array · Required by upstream.
    stream
    boolean · If true, worker injects stream_options.include_usage=true.
    stream_options.include_usage
    boolean · Forced to true when stream=true.
    max_completion_tokens
    number · Logged for analytics.
    max_tokens
    number · Logged for analytics (fallback).
    temperature
    number · Logged for analytics.
    top_p
    number · Logged for analytics.
    ...
    any · Other OpenAI Chat Completions fields are passed through.
    Response
    stream
    SSE · When stream=true, returns text/event-stream frames.
    usage
    object · Included in-stream when streaming; present in JSON response otherwise.
    ...
    any · Upstream response (pass-through).
    Notes
    • Only POST is supported; other methods return 405.
    • Upstream is configured via OPENAI_BASE_URL / OPENAI_API_BASE (defaults to api.openai.com).

OCR

OCR proxy backed by Mistral OCR.

1 routes
  • POST /v1/ocr
    Proxy to upstream `/v1/ocr`.
    Headers
    • Content-Type : application/json Required.
    • Authorization : Bearer <token> Required only when API_AUTH_REQUIRED=1.
    Body
    document
    object · If provided, passed through to upstream.
    documents
    array · If provided, passed through to upstream.
    url
    string · If provided (and no document[s]), worker converts to document:{type:'url',url}.
    model
    string · Optional; if url is used and model is missing, worker sets it from MISTRAL_OCR_MODEL.
    ...
    any · Other upstream OCR fields are passed through.
    Response
    ...
    any · Upstream OCR response (pass-through).
    Notes
    • Only POST is supported; other methods return 405.
    • Upstream is configured via MISTRAL_BASE_URL / MISTRAL_API_BASE (defaults to api.mistral.ai).
    • Model default: MISTRAL_OCR_MODEL (defaults to mistral-ocr-latest).

Chroma

Chroma proxy with per-user namespacing.

2 routes
  • ALL /v1/chroma
    Proxy to Chroma base URL.
    Headers
    • Authorization : Bearer <token> Required when API_AUTH_REQUIRED=1; required for user namespacing.
    • x-chroma-api-key : <injected> Default auth header; worker injects CHROMA_API_KEY.
    • CHROMA_AUTH_HEADER : <optional> Override injected auth header name (default x-chroma-api-key).
    • CHROMA_AUTH_SCHEME : <optional> If set, worker prefixes the api key (e.g. 'Bearer').
    Body
    database
    string · If JSON body includes database, worker prefixes it with user namespace.
    name
    string · For specific POST create-database paths, worker prefixes name with user namespace.
    ...
    any · All other fields are passed through.
    Notes
    • Upstream is configured via CHROMA_BASE_URL / CHROMA_API_BASE; worker requires CHROMA_API_KEY.
    • Namespace is derived from authenticated user id; requests without user context are rejected.
    • Namespace separator is configurable via CHROMA_NAMESPACE_SEPARATOR (defaults to '__').
  • ALL /v1/chroma/*
    Proxy to Chroma with path passthrough.
    Headers
    • Authorization : Bearer <token> Required when API_AUTH_REQUIRED=1; required for user namespacing.
    • x-chroma-api-key : <injected> Default auth header; worker injects CHROMA_API_KEY.
    Query
    *
    any · Query string is passed through (with database name prefixed when present).
    Notes
    • Everything after /v1/chroma is forwarded to the Chroma base URL.
    • Worker prefixes database names in both the path and query string for per-user isolation.

Usage

Analytics Engine powered usage summaries.

3 routes
  • GET /v1/usage
    Usage summary (top models/paths/types/providers).
    Headers
    • Authorization : Bearer <usage_key> Optional; required only when USAGE_API_KEY is set.
    • x-usage-key : <usage_key> Optional alternative to Authorization header.
    Query
    hours
    int · Optional; 1..720. Overrides days.
    days
    int · Optional; converted to hours. Used only if hours is missing.
    Response
    window.hours
    number · Effective window size.
    window.generated_at
    string · ISO timestamp.
    totals
    object · Requests, errors, token totals, OCR totals, avg latency, etc.
    totals.ocr_pages
    number · Aggregated OCR pages (unknown page counts contribute 0).
    totals.ocr_estimated_cost_usd
    number · Aggregated OCR estimated cost in USD.
    top_models
    array · Top models by requests.
    top_paths
    array · Top paths by requests.
    by_type
    array · Rollup by request_type.
    by_type[].ocr_pages
    number · OCR pages by request type.
    by_type[].ocr_estimated_cost_usd
    number · OCR estimated cost by request type.
    by_provider
    array · Rollup by provider.
    Notes
    • If USAGE_API_KEY is not set, this endpoint does not require a key.
    • Requires Analytics Engine credentials: CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN (or CF_* / ACCOUNT_ID / API_TOKEN).
    • Dataset can be overridden via ANALYTICS_DATASET (defaults to ai_worker_requests).
    • Dashboard defaults to 7-day aggregates via ?days=7.
  • GET /v1/usage/daily
    Daily usage buckets for charting (UTC).
    Headers
    • Authorization : Bearer <usage_key> Optional; required only when USAGE_API_KEY is set.
    • x-usage-key : <usage_key> Optional alternative to Authorization header.
    Query
    days
    int · Optional; defaults to 7 for dashboard usage.
    Response
    generated_at
    string · ISO timestamp.
    timezone
    string · UTC timezone label for day boundaries.
    days
    number · Number of day buckets returned.
    daily[]
    array · Ordered oldest-to-newest day buckets.
    daily[].date
    string · UTC calendar date (YYYY-MM-DD).
    daily[].requests
    number · Daily request count.
    daily[].input_tokens
    number · Daily input tokens.
    daily[].output_tokens
    number · Daily output tokens.
    daily[].total_tokens
    number · Daily total tokens.
    daily[].input_estimated_cost_usd
    number · Daily estimated input-token cost in USD.
    daily[].output_estimated_cost_usd
    number · Daily estimated output-token cost in USD.
    daily[].estimated_cost_usd
    number · Daily estimated cost in USD.
    daily[].ocr_pages
    number · Daily OCR pages.
    daily[].ocr_estimated_cost_usd
    number · Daily OCR estimated cost in USD.
    Notes
    • If USAGE_API_KEY is not set, this endpoint does not require a key.
    • Missing days should be zero-filled server-side for stable chart rendering.
  • GET /v1/usage/rollups
    Windowed rollups (10m, 1h, 6h, 24h, 7d).
    Headers
    • Authorization : Bearer <usage_key> Optional; required only when USAGE_API_KEY is set.
    • x-usage-key : <usage_key> Optional alternative to Authorization header.
    Response
    generated_at
    string · ISO timestamp.
    rollups[]
    array · Primary rollup entries containing label + totals.
    rollups[].window
    string · Preset label (10m, 1h, 6h, 24h, 7d).
    rollups[].totals.ocr_pages
    number · OCR pages for the rollup window.
    rollups[].totals.ocr_estimated_cost_usd
    number · OCR estimated cost for the rollup window.
    windows[]
    array · Compatibility alias for rollups[].
    Notes
    • If USAGE_API_KEY is not set, this endpoint does not require a key.
    • Requires Analytics Engine credentials: CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN (or CF_* / ACCOUNT_ID / API_TOKEN).

Examples

Quick starts

chat_completions curl 
curl -sS https://<your-worker-domain>/v1/chat/completions \
	  -H "Content-Type: application/json" \
	  -H "Authorization: Bearer $FOURTY32_TOKEN" \
	  -d '{
	    "model": "openai/gpt-4.1",
	    "messages": [{"role":"user","content":"Plan a launch checklist"}]
	  }'
usage curl 
curl -sS https://<your-worker-domain>/v1/usage?days=7 \
  -H "Authorization: Bearer $USAGE_KEY"