> ## Documentation Index
> Fetch the complete documentation index at: https://docs.askalchemist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Base URL, authentication, error codes, and conventions for the Alchemist REST API.

## 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.

## Authentication

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

```bash theme={null}
curl https://api.askalchemist.com/api/documents/filters \
  -H "X-API-Key: alch_YOUR_KEY"
```

See [API Keys](/authentication) for how to provision and manage keys.

## Request format

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

## Response format

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

```json theme={null}
{
  "detail": "Human-readable error description"
}
```

## Error codes

| 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 |

## Rate limits

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
```

## Public API endpoints

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      |

## OpenAPI spec

The full OpenAPI 3.1 spec is available at:

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