API Overview

Base URL

https://api.askalchemist.com

All endpoints are versioned implicitly — the current stable paths are documented here. Breaking changes will be communicated with advance notice.

Pass your API key in the X-API-Key header on every request:

curl https://api.askalchemist.com/api/documents/filters \
  -H "X-API-Key: alch_YOUR_KEY"

See API Keys for how to provision and manage keys.

Endpoints that accept a body use application/json. Endpoints that accept query parameters are documented with their names and types.

All responses are JSON. Success responses are documented per-endpoint. Error responses follow a consistent shape:

{
  "detail": "Human-readable error description"
}

Code	Meaning
`400`	Bad request — malformed JSON or invalid parameter value
`401`	Missing or invalid API key
`404`	Resource not found
`429`	Rate limit exceeded — check `X-RateLimit-Reset` header
`500`	Server error — transient; retry with exponential backoff

100 requests/minute per API key on the free tier. Rate limit state is returned in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 94
X-RateLimit-Reset: 1718534460

These endpoints authenticate with an alch_ API key and are the stable developer-facing surface:

Method	Path	Description
`GET`	`/api/health`	Health check (no auth required)
`POST`	`/api/insights/search`	Semantic search over the insight database
`GET`	`/api/documents/filters`	List available source names
`GET`	`/api/documents/{doc_id}`	Get a document and its insights
`GET`	`/api/documents`	List documents with optional filters

The full OpenAPI 3.1 spec is available at:

https://api.askalchemist.com/api/openapi.json