API reference

Authentication

Admin token

Admin endpoints require an admin token:

• Header: x-admin-token: <TOKEN>
• Or Authorization: Bearer <TOKEN>

Configure it in one of these ways:

• EMERGENCY_ADMIN_TOKEN env var
• security.emergencyAdminToken in config/registry.config.local.json

API keys (agents/tools)

Agent-friendly endpoints accept an API key:

• Header: x-api-key: <API_KEY>

Keys are created in:

• UI: Management → App admin → API keys
• API: POST /api/admin/api-keys (admin token required)

Scopes are stored per key, e.g. analytics:write, events:write.

Public API

GET /api/public/datasets

Search datasets.

Query params:

• q (string) full-text query
• provider (string) one of: SOCRATA | TYLER | ARCGIS | CKAN | OPENDATASOFT | DCAT | OTHER | FILESYSTEM
• tag (repeatable) filter by tags
• limit / offset
• track=1 to increment search_hit_count (default behavior: only when q is present)

Example:

curl -s 'http://localhost:3000/api/public/datasets?q=lottery&limit=10'

GET /api/public/datasets/:id

Fetch dataset details (resources + analytics profiles + fields). Also increments read_count.

curl -s 'http://localhost:3000/api/public/datasets/<DATASET_UUID>'

GET /api/health

Returns the doctor report (DB connectivity, migrations, basic pg-boss and worker visibility).

curl -s 'http://localhost:3000/api/health'

GET /api/openapi.json

OpenAPI description for the main endpoints.

curl -s 'http://localhost:3000/api/openapi.json'

Agent API

POST /api/events

Event sink for agents/tools. Requires:

• admin token, OR
• API key with scope events:write

Body:

{
  "datasetId": "<uuid>",
  "eventType": "dataset.read",
  "actor": "my-agent",
  "source": "mcp",
  "metadata": {"note": "used in project X"},
  "occurredAt": "2026-03-07T12:00:00Z"
}

Example:

curl -s -X POST 'http://localhost:3000/api/events' \
  -H 'content-type: application/json' \
  -H 'x-api-key: <API_KEY>' \
  -d '{"datasetId":"<uuid>","eventType":"dataset.read"}'

POST /api/app/datasets/:id/analytics/import

Imports your analytics engine payload. Requires:

• admin token, OR
• API key with scope analytics:write

Example:

curl -s -X POST 'http://localhost:3000/api/app/datasets/<uuid>/analytics/import' \
  -H 'content-type: application/json' \
  -H 'x-api-key: <API_KEY>' \
  --data-binary @docs/examples/sample_analytics_output.json

Admin API

Config / DB

• POST /api/admin/config/test-db (admin token)
  • tests DB credentials and writes an audit snapshot into registry.app_settings
• POST /api/admin/config/save-file (admin token)
  • writes patch to config/registry.config.local.json
• GET /api/admin/config/effective (admin token)
  • shows bootstrap config + DB override + effective config
• POST /api/admin/config/override / DELETE /api/admin/config/override (admin token)
  • set/clear DB override patch

Logs

• GET /api/app/logs (admin token)
• POST /api/admin/logs/purge (admin token)

DB reset (testing)

• POST /api/admin/db/reset (admin token + confirm)

curl -s -X POST 'http://localhost:3000/api/admin/db/reset' \
  -H 'content-type: application/json' \
  -H 'x-admin-token: <TOKEN>' \
  -d '{"seedData":true,"confirm":"RESET"}'

Keys

• GET/POST/PATCH /api/admin/api-keys (admin token)

Crawl control

• GET /api/app/projects (admin token)
• PATCH /api/app/projects/:id (admin token)
• POST /api/app/projects/:id/run (admin token)
• GET/POST/PATCH /api/app/projects/:id/sources (admin token)