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

# Introduction

> Upload, host, extract, and query PDFs with the Okra API.

## Base URL

```text theme={null}
https://api.okrapdf.com
```

The Mintlify API reference is backed by the live OpenAPI 3.1 spec from `https://api.okrapdf.com/openapi.json` (version `1.14.0`).

## Authentication

Use a Bearer token for authenticated endpoints:

```bash theme={null}
Authorization: Bearer okra_sk_YOUR_KEY
```

Secret keys use the `okra_sk_` prefix. Browser-facing publishable keys use `okra_pk_`. Create and rotate keys in [app.okrapdf.com/settings](https://app.okrapdf.com/settings?tab=api-keys).

## First request

```bash theme={null}
curl -X POST https://api.okrapdf.com/v1/documents \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -F "file=@report.pdf"
```

Response:

```json theme={null}
{
  "id": "doc-abc123",
  "status": "queued"
}
```

## Current surfaces

| Surface     | Endpoint family             | Use it for                                                                     |
| ----------- | --------------------------- | ------------------------------------------------------------------------------ |
| Files       | `/v1/files`                 | Store passive private PDF assets before running a workflow or hosting.         |
| Documents   | `/v1/documents`             | Upload, parse, read markdown/pages/entities, chat, and manage document config. |
| Host        | `/v1/host`                  | Publish clean `*.okrapdf.dev` PDF deployments from files or documents.         |
| Conversions | `/v1/conversions`           | One-call file conversion flows such as image to hosted PDF.                    |
| MCP         | `/mcp`                      | Remote agent tools and visual MCP Apps.                                        |
| Workflows   | `/v1/workflows`, `/v1/runs` | Built-in document workflows and private-beta dynamic agent workflows.          |
| Collections | `/v1/collections`           | Group documents and run multi-document queries or exports.                     |
| Agents      | `/v1/agents`                | Register and run reusable JSON-configured document agents.                     |

## Common document endpoints

| Method | Path                                               | Description                                           |
| ------ | -------------------------------------------------- | ----------------------------------------------------- |
| POST   | `/v1/documents`                                    | Upload a document with multipart form data.           |
| GET    | `/v1/documents/{id}`                               | Get document status and metadata.                     |
| GET    | `/v1/documents/{id}/full.md`                       | Read the full document as markdown.                   |
| GET    | `/v1/documents/{id}/pages/{page_number}/image.png` | Render a page image.                                  |
| GET    | `/v1/documents/{id}/entities/tables`               | List extracted tables.                                |
| POST   | `/v1/documents/{id}/structured-output`             | Extract JSON using a schema.                          |
| POST   | `/v1/documents/{id}/chat/completions`              | Ask questions using the OpenAI-compatible chat shape. |

## Errors

Errors use a structured JSON envelope:

```json theme={null}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Human-readable description of the problem"
  }
}
```

See [Errors](/api-reference/errors) for common codes and retry behavior.