> ## 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://www.sec.gov/Archives/edgar/data/831259/000083125926000021/a1q2026exhibit991.htm",
      "article_title": "Freeport Reports First-Quarter 2026 Results",
      "summary": "Freeport reported Q1 2026 net income of $881 million ($0.61/share), driven by higher copper and gold prices...",
      "source_name": "SEC",
      "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 SEC 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": "SEC", "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: "SEC",
    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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.