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

# List Documents

> GET /api/documents — browse available documents with optional filters.

## `GET /api/documents`

Returns a list of documents in the Alchemist database. Use this to discover what's available, browse by source, or find documents published in a date range.

For searching by content, use `POST /api/insights/search` instead — it searches across the extracted insights and returns ranked results.

### Authentication

`X-API-Key: alch_YOUR_KEY`

### Query parameters

| Parameter     | Type            | Description                                                                          |
| ------------- | --------------- | ------------------------------------------------------------------------------------ |
| `source_name` | `string`        | Partial, case-insensitive match on publishing organization.                          |
| `since`       | `string (date)` | ISO 8601 date (`YYYY-MM-DD`). Only return documents published on or after this date. |
| `limit`       | `integer`       | Max documents to return. Default `50`.                                               |

### Response `200`

```json theme={null}
{
  "documents": [
    {
      "doc_id": "doc_01jww8y2hp6e3uaq",
      "document_url": "https://federalreserve.gov/monetarypolicy/files/fomcminutes20260319.pdf",
      "article_title": "FOMC Minutes — March 18–19, 2026",
      "summary": "The March 2026 FOMC minutes detail deliberations on the appropriate pace of policy adjustment...",
      "source_name": "Federal Reserve",
      "authors": [],
      "published_date": "2026-04-09",
      "extracted_at": "2026-04-09T15:02:00Z",
      "extraction_status": "complete",
      "ingested_at": "2026-04-09T14:58:00Z"
    }
  ]
}
```

| Field               | Type             | Description                                                  |
| ------------------- | ---------------- | ------------------------------------------------------------ |
| `doc_id`            | `string`         | Document identifier — use with `GET /api/documents/{doc_id}` |
| `document_url`      | `string`         | URL of the primary source                                    |
| `article_title`     | `string`         | Document title                                               |
| `summary`           | `string`         | Brief summary of the document                                |
| `source_name`       | `string`         | Publishing organization                                      |
| `authors`           | `string[]`       | Author names, if available                                   |
| `published_date`    | `string \| null` | When the document was published                              |
| `extraction_status` | `string`         | `"complete"` when insights have been extracted               |

### Examples

<CodeGroup>
  ```bash All Federal Reserve documents in 2026 theme={null}
  curl "https://api.askalchemist.com/api/documents?source_name=Federal+Reserve&since=2026-01-01" \
    -H "X-API-Key: alch_YOUR_KEY"
  ```

  ```python Python (httpx) theme={null}
  import httpx

  resp = httpx.get(
      "https://api.askalchemist.com/api/documents",
      headers={"X-API-Key": "alch_YOUR_KEY"},
      params={"source_name": "Federal Reserve", "since": "2026-01-01", "limit": 20},
  )
  for doc in resp.json()["documents"]:
      print(doc["published_date"], doc["article_title"])
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    source_name: "Federal Reserve",
    since: "2026-01-01",
    limit: "20",
  });
  const res = await fetch(
    `https://api.askalchemist.com/api/documents?${params}`,
    { headers: { "X-API-Key": "alch_YOUR_KEY" } }
  );
  const { documents } = await res.json();
  ```
</CodeGroup>