# Create Agent
Source: https://docs.okrapdf.com/api-reference/agents/create-agent

POST /v1/agents
Create a reusable agent configuration with model, instructions, and optional table binding.

## Overview

An agent defines how sessions behave — which model to use, what system instructions to follow, and optionally which table to write extracted data into.

<ParamField type="string">
  Human-readable name for the agent.
</ParamField>

<ParamField type="string">
  Model to use for completions. Defaults to `"default"`.
</ParamField>

<ParamField type="string">
  System instructions for the agent. Guides how the agent processes documents and uses tools.
</ParamField>

<ParamField type="string">
  Bind a typed table to this agent. Sessions created with this agent will have `doc_sql` and `table_sql` tools available for reading documents and writing to the table.
</ParamField>

<ParamField type="object">
  JSON Schema for structured output. When set, completions will conform to this schema.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/agents \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "invoice-extractor",
      "system": "Extract vendor, amount, and date from each invoice. Insert one row per document.",
      "table_id": "tbl_abc123"
    }'
  ```
</RequestExample>

### Response (201)

```json theme={null}
{
  "id": "agent_cf3de29f5a384695",
  "name": "invoice-extractor",
  "model": "default",
  "system": "Extract vendor, amount, and date from each invoice. Insert one row per document.",
  "table_id": "tbl_abc123",
  "output_schema": null,
  "version": 1,
  "created_at": "2026-04-14T05:30:00Z",
  "updated_at": "2026-04-14T05:30:00Z"
}
```


# Get Agent
Source: https://docs.okrapdf.com/api-reference/agents/get-agent

GET /v1/agents/{agentId}
Retrieve a single agent by ID.

## Overview

Returns the full configuration of an agent, including system prompt and table binding.

<ParamField type="string">
  The agent ID (e.g. `agent_cf3de29f5a384695`).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/agents/agent_cf3de29f5a384695 \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "id": "agent_cf3de29f5a384695",
  "name": "invoice-extractor",
  "model": "default",
  "system": "Extract vendor, amount, and date from each invoice.",
  "table_id": "tbl_abc123",
  "output_schema": null,
  "version": 1,
  "created_at": "2026-04-14T05:30:00Z",
  "updated_at": "2026-04-14T05:30:00Z"
}
```


# List Agents
Source: https://docs.okrapdf.com/api-reference/agents/list-agents

GET /v1/agents
List all agents owned by the authenticated user.

## Overview

Returns a paginated list of agents belonging to the authenticated user.

<ParamField type="integer">
  Maximum number of agents to return. Default `20`, max `100`.
</ParamField>

<ParamField type="string">
  Pagination cursor from a previous response.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/agents \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "data": [
    {
      "id": "agent_cf3de29f5a384695",
      "name": "invoice-extractor",
      "model": "default",
      "table_id": "tbl_abc123",
      "version": 1,
      "created_at": "2026-04-14T05:30:00Z"
    }
  ],
  "has_more": false
}
```


# Run Collection Agent
Source: https://docs.okrapdf.com/api-reference/agents/run-collection-agent

POST /v1/collections/{colId}/agents/{agentId}/run
Run an agent against a collection.

## Overview

Runs a visible built-in or custom agent across a collection.

<ParamField type="string">
  Collection ID.
</ParamField>

<ParamField type="string">
  Agent ID.
</ParamField>

<ParamField type="object">
  Optional run input payload.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/collections/col-abc123/agents/agent_abc123/run \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "input": { "prompt": "Compare revenue across documents" } }'
  ```
</RequestExample>


# Run Document Agent
Source: https://docs.okrapdf.com/api-reference/agents/run-document-agent

POST /v1/documents/{docId}/agents/{agentId}/run
Run an agent against a single document.

## Overview

Runs a visible built-in or custom agent against one document.

<ParamField type="string">
  Document ID.
</ParamField>

<ParamField type="string">
  Agent ID.
</ParamField>

<ParamField type="object">
  Optional run input payload.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/documents/doc-abc123/agents/agent_abc123/run \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "input": { "prompt": "Extract key fields" } }'
  ```
</RequestExample>


# Authentication
Source: https://docs.okrapdf.com/api-reference/authentication

Authenticate API requests with your okraPDF API key.

## API Keys

All API requests require an API key. Generate keys in your dashboard:

1. Go to [app.okrapdf.com/settings](https://app.okrapdf.com/settings?tab=api-keys)
2. Click **Create API Key**
3. Copy the key (starts with `okra_`)

<Warning>
  API keys grant full access to your account. Never expose them in client-side code or public repositories.
</Warning>

## Passing your key

Use one of these two methods:

### Bearer token (recommended)

```bash theme={null}
curl https://api.okrapdf.com/v1/documents \
  -H "Authorization: Bearer okra_YOUR_KEY"
```

### Header

```bash theme={null}
curl https://api.okrapdf.com/v1/documents \
  -H "x-api-key: okra_YOUR_KEY"
```

## Security best practices

* Store keys in environment variables, not in code
* Use different keys for development and production
* Rotate keys periodically
* Revoke keys immediately if compromised

For route-level access boundaries, see [Security Model](/api-reference/security-model).

```bash theme={null}
# .env
OKRA_API_KEY=okra_YOUR_KEY
```

```python theme={null}
import os
import requests

resp = requests.get(
    "https://api.okrapdf.com/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['OKRA_API_KEY']}"},
)
```

## Error responses

Invalid or missing API keys return a `401` status:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API key."
  }
}
```


# Add Documents to Collection
Source: https://docs.okrapdf.com/api-reference/collections/add-documents

POST /v1/collections/{id}/documents
Add one or more documents to an existing collection.

## Overview

Adds documents to a collection by ID. Documents already in the collection are silently skipped.

## Request

<ParamField type="string">
  Collection ID (`col-...`) or collection name.
</ParamField>

<ParamField type="string[]">
  Array of document IDs to add. Must contain at least one ID.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611/documents \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"document_ids": ["doc-abc123", "doc-def456"]}'
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "ok": true,
  "added": 2
}
```


# Clear Collection Cache
Source: https://docs.okrapdf.com/api-reference/collections/clear-cache

DELETE /v1/collections/{id}/cache
Purge cached query results for a collection.

## Overview

Purges all cached query results for a collection. Useful after adding or removing documents to ensure fresh answers.

## Request

<ParamField type="string">
  Collection ID (`col-...`) or collection name.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X DELETE https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611/cache \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "ok": true
}
```


# Create Collection
Source: https://docs.okrapdf.com/api-reference/collections/create-collection

POST /v1/collections
Create a new named collection, optionally seeded with documents.

## Overview

Creates a new collection. You can optionally include document IDs to add at creation time.

## Request

<ParamField type="string">
  Display name for the collection.
</ParamField>

<ParamField type="string">
  Optional description of the collection's purpose.
</ParamField>

<ParamField type="string[]">
  Document IDs to seed into the collection. IDs already present are silently skipped.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/collections \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Q4 Earnings",
      "description": "Quarterly earnings reports",
      "document_ids": ["doc-abc123", "doc-def456"]
    }'
  ```
</RequestExample>

### Response (201)

```json theme={null}
{
  "id": "col-40da068481cf4f248853507cba6be611",
  "name": "Q4 Earnings",
  "description": "Quarterly earnings reports",
  "visibility": "private",
  "created_at": "2025-01-15T08:30:00Z",
  "document_count": 2
}
```


# Delete Collection
Source: https://docs.okrapdf.com/api-reference/collections/delete-collection

DELETE /v1/collections/{id}
Delete a collection. Documents are preserved.

## Overview

Deletes a collection. Only the grouping is removed -- all member documents remain in your account.

## Request

<ParamField type="string">
  Collection ID (`col-...`) or collection name.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X DELETE https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611 \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "ok": true
}
```


# Export Collection
Source: https://docs.okrapdf.com/api-reference/collections/export-collection

GET /v1/collections/{id}/export
Export pre-computed markdown for every document in a collection.

## Overview

Exports markdown content for all documents in a collection. Supports NDJSON streaming (default) or a zip archive.

## Request

<ParamField type="string">
  Collection ID (`col-...`) or collection name.
</ParamField>

<ParamField type="string">
  `markdown` (default, NDJSON stream) or `zip` (one `.md` file per document).
</ParamField>

<RequestExample>
  ```bash theme={null}
  # NDJSON event stream
  curl -N "https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611/export?format=markdown" \
    -H "Authorization: Bearer okra_YOUR_KEY"

  # Zip archive
  curl -L "https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611/export?format=zip" \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -o collection-export.zip
  ```
</RequestExample>

### NDJSON Event Shapes

**`start`** -- first event in the stream:

```json theme={null}
{"type":"start","doc_count":3,"format":"markdown"}
```

**`result`** -- one per document:

```json theme={null}
{
  "type": "result",
  "doc_id": "doc-abc123",
  "file_name": "10k.pdf",
  "page_count": 2,
  "pages": [
    {"pageNumber": 1, "content": "# Page 1 markdown", "vendor": "okra"},
    {"pageNumber": 2, "content": "# Page 2 markdown", "vendor": "okra"}
  ]
}
```

**`done`** -- final success event:

```json theme={null}
{"type":"done","completed":3,"failed":0,"total_pages":12}
```

**`error`** -- terminal failure:

```json theme={null}
{"type":"error","error":"Collection export failed"}
```


# Get Collection
Source: https://docs.okrapdf.com/api-reference/collections/get-collection

GET /v1/collections/{id}
Retrieve a collection and its document list.

## Overview

Returns collection metadata along with the full list of member documents and their processing status.

## Request

<ParamField type="string">
  Collection ID (`col-...`) or collection name.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611 \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "id": "col-40da068481cf4f248853507cba6be611",
  "name": "Q4 Earnings",
  "description": "Quarterly earnings reports",
  "visibility": "private",
  "created_at": "2025-01-15T08:30:00Z",
  "document_count": 2,
  "documents": [
    {
      "id": "doc-abc123",
      "added_at": "2025-01-15T08:31:00Z",
      "file_name": "10k.pdf",
      "phase": "complete",
      "pages_total": 42,
      "total_nodes": 318,
      "source": "upload"
    }
  ]
}
```


# List Collections
Source: https://docs.okrapdf.com/api-reference/collections/list-collections

GET /v1/collections
Retrieve all collections owned by the authenticated API key.

## Overview

Returns an array of all collections belonging to the authenticated key, including document counts.

## Request

No parameters required.

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/collections \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "collections": [
    {
      "id": "col-40da068481cf4f248853507cba6be611",
      "name": "Q4 Earnings",
      "description": "Quarterly earnings reports",
      "visibility": "private",
      "created_at": "2025-01-15T08:30:00Z",
      "document_count": 12
    }
  ]
}
```


# Query Collection
Source: https://docs.okrapdf.com/api-reference/collections/query-collection

POST /v1/collections/{id}/query
Run a natural-language query across all documents in a collection.

## Overview

Queries all documents in a collection using natural language. Supports optional streaming for real-time responses.

## Request

<ParamField type="string">
  Collection ID (`col-...`) or collection name.
</ParamField>

<ParamField type="string">
  Natural-language question to ask across the collection.
</ParamField>

<ParamField type="boolean">
  When `true`, returns a streaming SSE response. Default `false`.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611/query \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "What was total revenue in Q4?"}'
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "answer": "Total revenue in Q4 was $4.2B, a 12% increase year-over-year.",
  "sources": [
    {
      "doc_id": "doc-abc123",
      "file_name": "10k.pdf",
      "page": 15
    }
  ]
}
```


# Remove Documents from Collection
Source: https://docs.okrapdf.com/api-reference/collections/remove-documents

DELETE /v1/collections/{id}/documents
Remove one or more documents from a collection.

## Overview

Removes documents from a collection. The documents themselves are not deleted from your account.

## Request

<ParamField type="string">
  Collection ID (`col-...`) or collection name.
</ParamField>

<ParamField type="string[]">
  Array of document IDs to remove. Must contain at least one ID.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X DELETE https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611/documents \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"document_ids": ["doc-abc123"]}'
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "ok": true,
  "removed": 1
}
```


# Update Collection
Source: https://docs.okrapdf.com/api-reference/collections/update-collection

PATCH /v1/collections/{id}
Update a collection's name, description, or visibility.

## Overview

Partially updates collection metadata. Only provided fields are changed.

## Request

<ParamField type="string">
  Collection ID (`col-...`) or collection name.
</ParamField>

<ParamField type="string">
  New display name.
</ParamField>

<ParamField type="string">
  New description.
</ParamField>

<ParamField type="string">
  `private` or `public`.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X PATCH https://api.okrapdf.com/v1/collections/col-40da068481cf4f248853507cba6be611 \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"visibility": "public"}'
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "ok": true
}
```


# Get Company
Source: https://docs.okrapdf.com/api-reference/companies/get-company

GET /v1/companies/{exchange}/{ticker}
Retrieve details for a specific company.

## Overview

Returns details for a single company identified by exchange and ticker. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/companies/NASDAQ/AAPL"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "exchange": "NASDAQ",
  "ticker": "AAPL",
  "name": "Apple Inc."
}
```


# List Companies
Source: https://docs.okrapdf.com/api-reference/companies/list-companies

GET /v1/companies
List all companies with available filings, optionally filtered by exchange.

## Overview

Returns a list of companies that have filings available. Optionally filter by stock exchange. No authentication required.

## Request

<ParamField type="string">
  Filter by stock exchange code (e.g. `NYSE`, `NASDAQ`).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/companies?exchange=NASDAQ"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "companies": [
    {
      "exchange": "NASDAQ",
      "ticker": "AAPL",
      "name": "Apple Inc."
    },
    {
      "exchange": "NASDAQ",
      "ticker": "MSFT",
      "name": "Microsoft Corporation"
    }
  ]
}
```


# Image to PDF
Source: https://docs.okrapdf.com/api-reference/conversions/image-to-pdf

POST /v1/conversions/image-to-pdf
Create a hosted PDF from a PNG or JPEG.

## Overview

Stores a PNG or JPEG from multipart upload or source URL as a private file asset, then publishes an immutable PDF derivative with preview and download URLs.

<ParamField type="file">
  PNG or JPEG file when using multipart form data.
</ParamField>

<ParamField type="string">
  Source image URL when using JSON.
</ParamField>

<ParamField type="string">
  Optional hosted PDF namespace.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/conversions/image-to-pdf \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -F "file=@scan.png" \
    -F "namespace=scan-as-pdf"
  ```
</RequestExample>


# Access Policy
Source: https://docs.okrapdf.com/api-reference/documents/access-policy

PUT /v1/documents/{id}/config
Control who can query, read, and manage a document.

## Overview

Every document has an access policy that controls who can interact with it. The policy uses a deny-by-default model with explicit grants.

## Policy shape

```json theme={null}
{
  "access": {
    "default_effect": "deny",
    "grants": [
      {
        "principal": { "type": "owner" },
        "actions": ["admin"]
      },
      {
        "principal": { "type": "public" },
        "actions": ["query", "read_content", "read_meta"]
      }
    ]
  }
}
```

## Principals

| Type      | Matches                            | Use case                                               |
| --------- | ---------------------------------- | ------------------------------------------------------ |
| `owner`   | The user who uploaded the document | Full control                                           |
| `public`  | Any caller, no auth required       | Public-facing documents (HKEX filings, shared reports) |
| `user`    | A specific user ID                 | Shared with a teammate                                 |
| `org`     | All members of an org              | Org-wide access                                        |
| `project` | All keys scoped to a project       | Project-level access                                   |

## Actions

| Action            | What it permits                         |
| ----------------- | --------------------------------------- |
| `admin`           | All operations (superset)               |
| `query`           | Chat completions, structured extraction |
| `read_content`    | Page markdown, node content             |
| `read_meta`       | Document status, metadata               |
| `download_pdf`    | Original PDF download                   |
| `update_config`   | Change settings and access policy       |
| `trigger_extract` | Start extraction jobs                   |
| `publish`         | Publish to public corpus                |
| `create_link`     | Create share links                      |
| `list_links`      | View existing share links               |

## Setting the policy

<RequestExample>
  ```bash theme={null}
  curl -X PUT https://api.okrapdf.com/v1/documents/doc-abc123/config \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "access": {
        "default_effect": "deny",
        "grants": [
          {
            "principal": { "type": "owner" },
            "actions": ["admin"]
          },
          {
            "principal": { "type": "public" },
            "actions": ["query", "read_content", "read_meta"]
          }
        ]
      }
    }'
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "document_id": "doc-abc123",
  "config_version": 1,
  "config": {
    "access": {
      "default_effect": "deny",
      "grants": [
        { "principal": { "type": "owner" }, "actions": ["admin"] },
        { "principal": { "type": "public" }, "actions": ["query", "read_content", "read_meta"] }
      ]
    }
  }
}
```

## Grant constraints

Grants can have optional constraints:

```json theme={null}
{
  "principal": { "type": "user", "id": "user_abc" },
  "actions": ["query"],
  "constraints": {
    "expires_at": "2026-06-01T00:00:00Z",
    "not_before": "2026-03-01T00:00:00Z"
  }
}
```

| Constraint       | Effect                                                      |
| ---------------- | ----------------------------------------------------------- |
| `expires_at`     | Grant stops working after this time                         |
| `not_before`     | Grant only active after this time                           |
| `redaction_role` | Applies PII redaction profile (`admin`, `viewer`, `public`) |

## Common patterns

### Public document (anyone can chat)

```json theme={null}
{
  "grants": [
    { "principal": { "type": "owner" }, "actions": ["admin"] },
    { "principal": { "type": "public" }, "actions": ["query", "read_content", "read_meta"] }
  ]
}
```

### Org-internal document

```json theme={null}
{
  "grants": [
    { "principal": { "type": "owner" }, "actions": ["admin"] },
    { "principal": { "type": "org", "id": "org_xyz" }, "actions": ["query", "read_content"] }
  ]
}
```

### Time-limited share

```json theme={null}
{
  "grants": [
    { "principal": { "type": "owner" }, "actions": ["admin"] },
    {
      "principal": { "type": "user", "id": "user_abc" },
      "actions": ["query", "read_content"],
      "constraints": { "expires_at": "2026-04-01T00:00:00Z" }
    }
  ]
}
```


# Verify Export Audit
Source: https://docs.okrapdf.com/api-reference/documents/audit-verify

GET /exports/{id}/audit/verify
Verify the integrity of a document's audit trail.

## Overview

Validates the chain-hash integrity of a document's audit trail. Returns the document log and vendor log for the specified version. Does not require authentication.

## Request

<ParamField type="string">
  Document ID.
</ParamField>

<ParamField type="string">
  Version to verify. Defaults to the latest version.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/exports/doc-abc123/audit/verify?v=3" \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "version": "3",
  "documentLog": { "valid": true, "entries": 12 },
  "vendorLog": { "valid": true, "entries": 5 }
}
```


# Chat Completions
Source: https://docs.okrapdf.com/api-reference/documents/chat-completions

POST /v1/documents/{id}/chat/completions
Ask questions about a processed document with the OpenAI-compatible chat shape.

## Overview

Runs a chat completion against one document. The model receives document context from okraPDF and can return cited answers when source evidence is available.

<ParamField type="string">
  Document ID.
</ParamField>

<ParamField type="object[]">
  OpenAI-compatible chat messages.
</ParamField>

<ParamField type="string">
  Optional model override.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/documents/doc-abc123/chat/completions \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [
        { "role": "user", "content": "What is the total amount due?" }
      ]
    }'
  ```
</RequestExample>


# Delete Document
Source: https://docs.okrapdf.com/api-reference/documents/delete-document

DELETE /v1/documents/{id}
Permanently delete a document and all associated data.

## Overview

Permanently deletes a document, its extracted content, page images, and exports. This action cannot be undone.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X DELETE https://api.okrapdf.com/v1/documents/doc-abc123 \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "deleted": true,
  "id": "doc-abc123"
}
```


# Download Original PDF
Source: https://docs.okrapdf.com/api-reference/documents/download

GET /v1/documents/{id}/original.pdf
Download the original uploaded PDF.

## Overview

Stream the original PDF that was uploaded for this document. Served from R2 with CDN caching.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -O https://api.okrapdf.com/v1/documents/doc-abc123/original.pdf \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response

Returns the raw PDF binary with `Content-Type: application/pdf`.


# Export Document
Source: https://docs.okrapdf.com/api-reference/documents/export

GET /exports/{id}/{format}
Download a pre-formatted export of a document.

## Overview

Returns a document export in the requested format. Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID.
</ParamField>

<ParamField type="string">
  Export format: `snapshot`, `markdown`, `excel`, `docx`, or `audit`.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/exports/doc-abc123/markdown \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

Response content type varies by format:

* `snapshot` -- `application/json`
* `markdown` -- `text/markdown`
* `excel` -- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
* `docx` -- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
* `audit` -- `application/json`


# Get Full JSON
Source: https://docs.okrapdf.com/api-reference/documents/full-json

GET /v1/documents/{id}/full.json
Retrieve the entire document content as structured JSON.

## Overview

Returns the full extracted document content as a single JSON object. Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/full.json \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "content": "{ ... full document JSON ... }"
}
```


# Get Full Markdown
Source: https://docs.okrapdf.com/api-reference/documents/full-markdown

GET /v1/documents/{id}/full.md
Retrieve the entire document content as markdown.

## Overview

Returns the full extracted document content as a single markdown string. Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/full.md \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

Returns `text/markdown` content type with the full document as markdown text.

```
# Annual Report 2024

## Executive Summary

Revenue grew 15% year-over-year...
```


# Get Document Config
Source: https://docs.okrapdf.com/api-reference/documents/get-config

GET /v1/documents/{id}/config
Retrieve the workflow configuration for a document.

## Overview

Returns the current workflow configuration for a document, including processing strategy and capability flags.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/config \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "strategy": "auto",
  "page_images": "eager",
  "capabilities": {}
}
```


# Get Figure
Source: https://docs.okrapdf.com/api-reference/documents/get-figure

GET /v1/documents/{id}/entities/figures/{index}
Retrieve a specific figure by index.

## Overview

Returns a specific figure node from the document by its 0-based index. Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<ParamField type="string">
  0-based figure index.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/entities/figures/0 \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "type": "figure",
  "value": "Figure 1: Revenue breakdown by segment"
}
```


# Get Page Content
Source: https://docs.okrapdf.com/api-reference/documents/get-page

GET /v1/documents/{id}/pages/{page_number}
Retrieve extracted content for a single page.

## Overview

Returns the extracted content for a specific page as JSON. Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<ParamField type="integer">
  1-based page number.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/pages/1 \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "page": 1,
  "content": "# Annual Report\n\nThis document summarizes..."
}
```


# Get Page Markdown
Source: https://docs.okrapdf.com/api-reference/documents/get-page-markdown

GET /v1/documents/{id}/pages/{page_number}/markdown
Retrieve a single page as raw markdown text.

## Overview

Returns the extracted content for a specific page as raw markdown. Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<ParamField type="integer">
  1-based page number.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/pages/1/markdown \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

Returns `text/markdown` content type with the page content as markdown.

```
# Annual Report

This document summarizes the fiscal year...
```


# Get Document Status
Source: https://docs.okrapdf.com/api-reference/documents/get-status

GET /v1/documents/{id}
Retrieve the current status and metadata for a document.

## Overview

Returns the current processing status, page count, and metadata for a document. This endpoint does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123 \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "id": "doc-abc123",
  "status": "completed",
  "file_name": "annual-report.pdf",
  "total_pages": 42,
  "pages_completed": 42,
  "inserted_at": "2025-01-15T08:30:00Z",
  "updated_at": "2025-01-15T08:32:00Z",
  "is_public": false
}
```


# Get Table
Source: https://docs.okrapdf.com/api-reference/documents/get-table

GET /v1/documents/{id}/entities/tables/{index}
Retrieve a specific table by index in multiple formats.

## Overview

Returns a specific table from the document. Use the `format` query parameter to choose the output format.

<Note>
  **Multiple formats.** Use the `format` query parameter to get the table as `json`, `csv`, `html`, or `markdown`.
</Note>

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<ParamField type="string">
  0-based table index.
</ParamField>

<ParamField type="string">
  Output format: `json`, `csv`, `html`, or `markdown`. Defaults to `json`.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/documents/doc-abc123/entities/tables/0?format=csv" \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

Response content type varies by format. For `json`:

```json theme={null}
{
  "type": "table",
  "value": "| Header 1 | Header 2 |\n|---|---|\n| A | B |"
}
```


# Ingest Vendor Output
Source: https://docs.okrapdf.com/api-reference/documents/ingest

POST /v1/documents/ingest
Push raw vendor extraction output into a document.

## Overview

Push raw vendor output (OCR, layout, etc.) into a document. Each call appends a new record -- previous data is never overwritten.

<Note>
  **Append-only.** Each ingest call appends a new record. Previous data is never overwritten.
</Note>

## Request

<ParamField type="string">
  Target document ID (e.g. `doc-abc123`).
</ParamField>

<ParamField type="string">
  Vendor identifier (e.g. `azure_di`, `textract`).
</ParamField>

<ParamField type="object">
  Raw vendor output. Any JSON shape accepted.
</ParamField>

<ParamField type="string">
  SHA-256 hash of the source PDF for optimistic concurrency. Returns 409 on mismatch.
</ParamField>

<ParamField type="object">
  Capability configuration including `vlm_qwen`, `structural_check`, `sandbox_verify`, `search`, `phases`, and `middleware`.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/documents/ingest \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "document_id": "doc-abc123",
      "vendor": "azure_di",
      "payload": { "pages": [...] }
    }'
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "ok": true,
  "seq": 3,
  "document_id": "doc-abc123"
}
```


# List Documents
Source: https://docs.okrapdf.com/api-reference/documents/list-documents

GET /v1/documents
List documents owned by the authenticated API key.

## Overview

Returns a paginated list of documents associated with the authenticated API key.

## Request

<ParamField type="integer">
  Max results to return (1-100, default 20).
</ParamField>

<ParamField type="string">
  Cursor: return results after this document ID.
</ParamField>

<ParamField type="string">
  Cursor: return results before this document ID.
</ParamField>

<ParamField type="string">
  Sort order by `inserted_at`: `asc` or `desc`.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/documents?limit=10&order=desc" \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "data": [
    {
      "id": "doc-abc123",
      "status": "completed",
      "file_name": "annual-report.pdf",
      "total_pages": 42,
      "pages_completed": 42,
      "inserted_at": "2025-01-15T08:30:00Z",
      "updated_at": "2025-01-15T08:32:00Z",
      "thumbnail_url": "https://res.okrapdf.com/v1/documents/doc-abc123/pg_1.png",
      "is_public": false,
      "source": "api"
    }
  ],
  "has_more": false
}
```


# List Figures
Source: https://docs.okrapdf.com/api-reference/documents/list-figures

GET /v1/documents/{id}/entities/figures
List all figures extracted from a document.

## Overview

Returns all figure nodes extracted from a document. Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<ParamField type="integer">
  Max number of figures to return.
</ParamField>

<ParamField type="integer">
  Number of figures to skip (for pagination).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/entities/figures \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "nodes": [
    {
      "type": "figure",
      "value": "Figure 1: Revenue breakdown by segment"
    }
  ]
}
```


# List Tables
Source: https://docs.okrapdf.com/api-reference/documents/list-tables

GET /v1/documents/{id}/entities/tables
List all tables extracted from a document.

## Overview

Returns all table nodes extracted from a document. Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<ParamField type="integer">
  Max number of tables to return.
</ParamField>

<ParamField type="integer">
  Number of tables to skip (for pagination).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/entities/tables \
    -H "Authorization: Bearer okra_YOUR_KEY"
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "nodes": [
    {
      "type": "table",
      "value": "| Header 1 | Header 2 |\n|---|---|\n| A | B |"
    }
  ]
}
```


# Get Page Image
Source: https://docs.okrapdf.com/api-reference/documents/page-image

GET /v1/documents/{id}/pages/{page_number}/image.png
Retrieve a rendered PNG image of a document page.

## Overview

Returns a PNG rendering of the specified page. The first request for a lazily-rendered page may take \~12s; subsequent requests serve from cache (\~0.3s). Does not require authentication for public documents.

## Request

<ParamField type="string">
  Document ID (e.g. `doc-abc123`) or 6-char short hash.
</ParamField>

<ParamField type="integer">
  1-based page number.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/documents/doc-abc123/pages/1/image.png \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    --output page1.png
  ```
</RequestExample>

### Response (200)

Returns `image/png` binary data.


# Structured Output
Source: https://docs.okrapdf.com/api-reference/documents/structured-output

POST /v1/documents/{id}/structured-output
Extract JSON from a document using a JSON Schema.

## Overview

Extracts data from a processed document and validates the result against a JSON Schema.

<ParamField type="string">
  Document ID.
</ParamField>

<ParamField type="string">
  Natural-language extraction instruction.
</ParamField>

<ParamField type="object">
  JSON Schema for the desired output.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/documents/doc-abc123/structured-output \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Extract invoice fields.",
      "schema": {
        "type": "object",
        "properties": {
          "vendor": { "type": "string" },
          "total": { "type": "number" }
        },
        "required": ["vendor", "total"]
      }
    }'
  ```
</RequestExample>


# Upload PDF (Multipart)
Source: https://docs.okrapdf.com/api-reference/documents/upload-multipart

POST /v1/documents
Upload a PDF file using multipart form data.

## Overview

Upload a PDF file directly using `multipart/form-data`. The document is assigned an ID and queued for processing.

## Request

<ParamField type="string">
  Page image rendering strategy: `eager` (default, render all pages), `cover` (page 1 only), or `none`. `lazy` is accepted as a deprecated alias for `eager`.
</ParamField>

<ParamField type="string">
  Processing strategy hint.
</ParamField>

<ParamField type="file">
  The PDF file to upload.
</ParamField>

<ParamField type="string">
  Comma-separated capability flags.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/documents \
    -H "Authorization: Bearer okra_YOUR_KEY" \
    -F "file=@report.pdf" \
    -F "capabilities=vlm_qwen"
  ```
</RequestExample>

### Response (202)

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


# Errors
Source: https://docs.okrapdf.com/api-reference/errors

Standard error codes and how to handle them.

## Error format

All errors return a consistent JSON shape:

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

## Error codes

| Code                       | HTTP Status | Description                                                       |
| -------------------------- | ----------- | ----------------------------------------------------------------- |
| `BAD_REQUEST`              | 400         | Invalid request body or parameters                                |
| `UNAUTHORIZED`             | 401         | Missing or invalid API key                                        |
| `FORBIDDEN`                | 403         | Valid key but not authorized for this resource                    |
| `NOT_FOUND`                | 404         | Document or resource does not exist                               |
| `CONFLICT`                 | 409         | Resource state conflict                                           |
| `SCHEMA_VALIDATION_FAILED` | 422         | Request was well-formed but semantically invalid                  |
| `RATE_LIMITED`             | 429         | Too many requests - see [rate limits](/api-reference/rate-limits) |
| `INTERNAL_ERROR`           | 500         | Unexpected server error                                           |
| `TIMEOUT`                  | 504         | The operation timed out                                           |

## Handling errors

### Retry strategy

For transient errors (`429`, `500`, `502`, `503`, `504`), use exponential backoff:

```python theme={null}
import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 5))
            time.sleep(retry_after)
            continue

        if resp.status_code >= 500:
            time.sleep(2 ** attempt)
            continue

        return resp

    raise Exception(f"Failed after {max_retries} retries")
```

### Non-retryable errors

| Code  | Action                                         |
| ----- | ---------------------------------------------- |
| `400` | Fix your request body or parameters            |
| `401` | Check your API key                             |
| `403` | Verify you own the resource                    |
| `404` | Verify the document ID exists                  |
| `422` | Check request schema against the API reference |

## Structured output errors

The `/v1/documents/{id}/structured-output` endpoint returns specific extraction errors:

| Code                       | HTTP Status | Description                                                                                              |
| -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `SCHEMA_VALIDATION_FAILED` | 422         | Extracted data didn't match your JSON schema. Check field types, required fields, and nesting.           |
| `EXTRACTION_BLOCKED`       | 422         | The model couldn't extract data — document has no pages, parsing failed, or all queries returned errors. |
| `TIMEOUT`                  | 504         | Extraction exceeded the time limit (default 45s, MCP uses 120s). Simplify the schema or use page ranges. |
| `DOCUMENT_NOT_FOUND`       | 404         | Document ID does not exist or has not finished processing. Check document status first.                  |

### Example error response

```json theme={null}
{
  "error": {
    "message": "Structured output timed out",
    "type": "server_error",
    "details": { "timeoutMs": 120000 }
  }
}
```

### Tips for reliable extraction

* **Keep schemas flat** when possible — fewer nested objects means faster extraction
* **Use string types** for financial values (e.g. `"$215,938 million"`) rather than numbers to avoid parsing ambiguity
* **Check document status** before extracting — `phase: "complete"` is required


# Download File Bytes
Source: https://docs.okrapdf.com/api-reference/files/download-file

GET /v1/files/{id}/bytes
Download private file bytes.

## Overview

Downloads the original private file bytes. Requires authentication.

<ParamField type="string">
  File ID.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/files/file_abc123/bytes \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -o report.pdf
  ```
</RequestExample>


# Finalize Direct Upload
Source: https://docs.okrapdf.com/api-reference/files/finalize-file

POST /v1/files/finalize
Finalize a direct-to-storage PDF upload.

## Overview

Call this after PUTing bytes to the signed `upload_url` returned by `/v1/files/presign`.

<ParamField type="string">
  Upload session ID returned by `/v1/files/presign`.
</ParamField>

<ParamField type="string">
  Original filename.
</ParamField>

<ParamField type="string">
  Storage key returned by the presign response.
</ParamField>

<ParamField type="string">
  SHA-256 digest of the uploaded file.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/files/finalize \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "upl_abc123",
      "fileName": "report.pdf",
      "r2Key": "uploads/...",
      "sha256": "..."
    }'
  ```
</RequestExample>


# Get File
Source: https://docs.okrapdf.com/api-reference/files/get-file

GET /v1/files/{id}
Get file metadata for a passive PDF asset.

## Overview

Returns metadata for a private file asset.

<ParamField type="string">
  File ID.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/files/file_abc123 \
    -H "Authorization: Bearer $OKRA_API_KEY"
  ```
</RequestExample>


# List Files
Source: https://docs.okrapdf.com/api-reference/files/list-files

GET /v1/files
List passive PDF file assets.

## Overview

Files are passive private assets. They do not automatically start document parsing. Use them when you want to upload once and later host, convert, or run a workflow.

<ParamField type="integer">
  Maximum number of files to return.
</ParamField>

<ParamField type="string">
  Pagination cursor from a previous response.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/files \
    -H "Authorization: Bearer $OKRA_API_KEY"
  ```
</RequestExample>


# Create Direct Upload
Source: https://docs.okrapdf.com/api-reference/files/presign-file

POST /v1/files/presign
Create a direct-to-storage upload session for a PDF.

## Overview

Use this for larger PDFs or browser/server uploads where you want to PUT bytes directly to the signed storage URL, then finalize the file with `/v1/files/finalize`.

<ParamField type="string">
  Original filename.
</ParamField>

<ParamField type="integer">
  File size in bytes.
</ParamField>

<ParamField type="string">
  SHA-256 digest of the file bytes.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/files/presign \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "fileName": "report.pdf",
      "fileSize": 10485760,
      "sha256": "..."
    }'
  ```
</RequestExample>


# Upload File
Source: https://docs.okrapdf.com/api-reference/files/upload-file

POST /v1/files
Upload a passive PDF file asset.

## Overview

Upload a PDF as a private file asset without starting a document workflow. For files larger than the multipart threshold, use [Create Direct Upload](/api-reference/files/presign-file) and [Finalize Direct Upload](/api-reference/files/finalize-file).

<ParamField type="file">
  PDF file to upload.
</ParamField>

<ParamField type="string">
  Optional JSON document config to attach to the file metadata.
</ParamField>

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

### Response

```json theme={null}
{
  "object": "file",
  "id": "file_abc123",
  "file_name": "report.pdf",
  "workflow_bound": false
}
```


# Get Filing
Source: https://docs.okrapdf.com/api-reference/filings/get-filing

GET /v1/filings/{exchange}/{ticker}/{slug}
Retrieve details for a specific SEC filing.

## Overview

Returns metadata for a single SEC filing identified by exchange, ticker, and slug. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`).
</ParamField>

<ParamField type="string">
  Filing slug, typically the SEC accession number (e.g. `0000320193-23-000106`).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/filings/NASDAQ/AAPL/0000320193-23-000106"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "exchange": "NASDAQ",
  "ticker": "AAPL",
  "slug": "0000320193-23-000106",
  "type": "10-K",
  "filed_at": "2023-11-03"
}
```


# Get Filing Audit Trail
Source: https://docs.okrapdf.com/api-reference/filings/get-filing-audit

GET /v1/filings/{exchange}/{ticker}/{slug}/audit
Retrieve the processing audit trail for a filing.

## Overview

Returns the audit trail showing all processing steps and their outcomes for a filing. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`).
</ParamField>

<ParamField type="string">
  Filing slug, typically the SEC accession number (e.g. `0000320193-23-000106`).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/filings/NASDAQ/AAPL/0000320193-23-000106/audit"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "audit": [
    {
      "step": "upload",
      "status": "complete",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "step": "ocr",
      "status": "complete",
      "timestamp": "2024-01-15T10:31:12Z"
    }
  ]
}
```


# List Filing Nodes
Source: https://docs.okrapdf.com/api-reference/filings/get-filing-nodes

GET /v1/filings/{exchange}/{ticker}/{slug}/nodes
List extracted nodes (tables, text blocks, etc.) in a filing.

## Overview

Returns structured nodes extracted from a filing. Filter by node type or page, with pagination support. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`).
</ParamField>

<ParamField type="string">
  Filing slug, typically the SEC accession number (e.g. `0000320193-23-000106`).
</ParamField>

<ParamField type="string">
  Filter by node type (e.g. `table`, `text`, `title`).
</ParamField>

<ParamField type="integer">
  Filter nodes to a specific page number.
</ParamField>

<ParamField type="integer">
  Maximum number of nodes to return.
</ParamField>

<ParamField type="integer">
  Number of nodes to skip for pagination.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/filings/NASDAQ/AAPL/0000320193-23-000106/nodes?type=table&limit=10"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "nodes": [
    {
      "id": "node-abc123",
      "type": "table",
      "page": 1,
      "content": "..."
    }
  ],
  "total": 42
}
```


# Get Filing Page
Source: https://docs.okrapdf.com/api-reference/filings/get-filing-page

GET /v1/filings/{exchange}/{ticker}/{slug}/page/{page_number}
Retrieve content for a specific page in a filing.

## Overview

Returns the content of a single page within a filing by its 1-based page number. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`).
</ParamField>

<ParamField type="string">
  Filing slug, typically the SEC accession number (e.g. `0000320193-23-000106`).
</ParamField>

<ParamField type="integer">
  1-based page number.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/filings/NASDAQ/AAPL/0000320193-23-000106/page/1"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "page_number": 1,
  "width": 612,
  "height": 792,
  "content": "..."
}
```


# List Filing Pages
Source: https://docs.okrapdf.com/api-reference/filings/get-filing-pages

GET /v1/filings/{exchange}/{ticker}/{slug}/pages
List all pages in a filing.

## Overview

Returns a list of all pages within a specific SEC filing. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`).
</ParamField>

<ParamField type="string">
  Filing slug, typically the SEC accession number (e.g. `0000320193-23-000106`).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/filings/NASDAQ/AAPL/0000320193-23-000106/pages"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "pages": [
    {
      "page_number": 1,
      "width": 612,
      "height": 792
    },
    {
      "page_number": 2,
      "width": 612,
      "height": 792
    }
  ]
}
```


# Get Filing Status
Source: https://docs.okrapdf.com/api-reference/filings/get-filing-status

GET /v1/filings/{exchange}/{ticker}/{slug}/status
Check the processing status of a filing.

## Overview

Returns the current processing status for a filing. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`).
</ParamField>

<ParamField type="string">
  Filing slug, typically the SEC accession number (e.g. `0000320193-23-000106`).
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/filings/NASDAQ/AAPL/0000320193-23-000106/status"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "phase": "complete",
  "total_pages": 78,
  "total_nodes": 215
}
```


# List Filings
Source: https://docs.okrapdf.com/api-reference/filings/list-filings

GET /v1/filings
List all available SEC filings, optionally filtered by exchange, ticker, or type.

## Overview

Returns a paginated list of SEC filings. Filter by exchange, ticker, or filing type. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NYSE`, `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`, `MSFT`).
</ParamField>

<ParamField type="string">
  Filing type (e.g. `10-K`, `10-Q`, `8-K`).
</ParamField>

<ParamField type="integer">
  Maximum number of filings to return.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/filings?exchange=NASDAQ&ticker=AAPL&type=10-K"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "filings": [
    {
      "exchange": "NASDAQ",
      "ticker": "AAPL",
      "slug": "0000320193-23-000106",
      "type": "10-K",
      "filed_at": "2023-11-03"
    }
  ]
}
```


# Search Filing
Source: https://docs.okrapdf.com/api-reference/filings/search-filing

GET /v1/filings/{exchange}/{ticker}/{slug}/search
Full-text search within a specific filing.

## Overview

Search for text within a specific filing. Returns matching nodes and their locations. No authentication required.

## Request

<ParamField type="string">
  Stock exchange code (e.g. `NASDAQ`).
</ParamField>

<ParamField type="string">
  Company ticker symbol (e.g. `AAPL`).
</ParamField>

<ParamField type="string">
  Filing slug, typically the SEC accession number (e.g. `0000320193-23-000106`).
</ParamField>

<ParamField type="string">
  Search query string.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.okrapdf.com/v1/filings/NASDAQ/AAPL/0000320193-23-000106/search?q=revenue"
  ```
</RequestExample>

### Response

```json theme={null}
{
  "results": [
    {
      "node_id": "node-abc123",
      "page": 12,
      "snippet": "...total revenue of $383.3 billion..."
    }
  ]
}
```


# Create Hosted PDF
Source: https://docs.okrapdf.com/api-reference/host/create-hosted-pdf

POST /v1/host
Publish a PDF file to a clean okrapdf.dev hostname.

## Overview

Publish an existing PDF from `/v1/files` or `/v1/documents` as `https://{namespace}.okrapdf.dev`. Internal storage keys such as `original.pdf` are not exposed.

<ParamField type="object">
  Source file or document reference. Use a file ID for passive assets or a document ID for parsed documents.
</ParamField>

<ParamField type="string">
  Desired DNS-label namespace. If omitted, okraPDF generates one.
</ParamField>

<ParamField type="string">
  Human-readable title for the hosted PDF.
</ParamField>

<ParamField type="object">
  Optional access settings such as disabled, unlisted, expiry, password, download availability, and indexing.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/host \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "source": { "file_id": "file_abc123" },
      "namespace": "acme-report",
      "title": "Acme Report"
    }'
  ```
</RequestExample>

### Response

```json theme={null}
{
  "namespace": "acme-report",
  "deployment": {
    "url": "https://acme-report.okrapdf.dev"
  }
}
```


# Get Hosted PDF
Source: https://docs.okrapdf.com/api-reference/host/get-hosted-pdf

GET /v1/host/{namespace}
Retrieve hosted PDF deployment metadata.

## Overview

Returns metadata for a hosted PDF deployment.

<ParamField type="string">
  Hosted PDF namespace.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/host/acme-report \
    -H "Authorization: Bearer $OKRA_API_KEY"
  ```
</RequestExample>


# List Hosted PDFs
Source: https://docs.okrapdf.com/api-reference/host/list-hosted-pdfs

GET /v1/host
List hosted PDF deployments.

## Overview

Returns hosted PDF deployments owned by the authenticated account.

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/host \
    -H "Authorization: Bearer $OKRA_API_KEY"
  ```
</RequestExample>


# Update Hosted PDF
Source: https://docs.okrapdf.com/api-reference/host/update-hosted-pdf

PATCH /v1/host/{namespace}
Update title, source, or access settings for a hosted PDF.

## Overview

Update a hosted PDF title, repoint an owned deployment hostname to another PDF with `replace: true`, or change access settings such as unlisted, disabled, expiry, password, download availability, and indexing.

<ParamField type="string">
  Hosted PDF namespace.
</ParamField>

<ParamField type="string">
  New title.
</ParamField>

<ParamField type="object">
  New source file or document reference.
</ParamField>

<ParamField type="boolean">
  Set true when repointing the namespace to another source.
</ParamField>

<ParamField type="object">
  Access settings.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X PATCH https://api.okrapdf.com/v1/host/acme-report \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "title": "Acme Report v2" }'
  ```
</RequestExample>


# Introduction
Source: https://docs.okrapdf.com/api-reference/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.


# Quickstart
Source: https://docs.okrapdf.com/api-reference/quickstart

Upload and query your first PDF with REST.

## Prerequisites

* An okraPDF account: [sign up](https://app.okrapdf.com/sign-up)
* An API key: [create one](https://app.okrapdf.com/settings?tab=api-keys)

```bash theme={null}
export OKRA_API_KEY=okra_sk_YOUR_KEY
```

## 1. Upload a document

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

Response:

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

## 2. Poll status

```bash theme={null}
curl https://api.okrapdf.com/v1/documents/doc-abc123 \
  -H "Authorization: Bearer $OKRA_API_KEY"
```

Wait until the document reports a terminal phase such as `complete`, `awaiting_review`, or `error`.

```json theme={null}
{
  "id": "doc-abc123",
  "phase": "complete",
  "fileName": "invoice.pdf",
  "pagesTotal": 3,
  "pagesCompleted": 3
}
```

## 3. Read results

```bash theme={null}
# Full document markdown
curl https://api.okrapdf.com/v1/documents/doc-abc123/full.md \
  -H "Authorization: Bearer $OKRA_API_KEY"

# Page 1 as markdown
curl https://api.okrapdf.com/v1/documents/doc-abc123/pages/1/markdown \
  -H "Authorization: Bearer $OKRA_API_KEY"

# Extracted tables
curl https://api.okrapdf.com/v1/documents/doc-abc123/entities/tables \
  -H "Authorization: Bearer $OKRA_API_KEY"
```

## 4. Ask a cited question

```bash theme={null}
curl -X POST https://api.okrapdf.com/v1/documents/doc-abc123/chat/completions \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What is the total amount due?" }
    ]
  }'
```

## 5. Extract structured JSON

```bash theme={null}
curl -X POST https://api.okrapdf.com/v1/documents/doc-abc123/structured-output \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extract invoice fields.",
    "schema": {
      "type": "object",
      "properties": {
        "vendor": { "type": "string" },
        "total": { "type": "number" },
        "currency": { "type": "string" }
      },
      "required": ["vendor", "total"]
    }
  }'
```

## JavaScript SDK equivalent

```ts theme={null}
import { createOkra } from '@okrapdf/sdk';

const okra = createOkra({ apiKey: process.env.OKRA_API_KEY });
const session = await okra.sessions.create('./invoice.pdf', { wait: true });

const { markdown } = await okra.read(session.id);
const { answer, sources } = await session.prompt('What is the total amount due?');

console.log(markdown);
console.log(answer, sources);
```


# Rate Limits
Source: https://docs.okrapdf.com/api-reference/rate-limits

API rate limits for okraPDF.

## Limits

| Context         | Requests/min | Expensive ops/min |
| --------------- | ------------ | ----------------- |
| Authenticated   | 600          | 30                |
| Unauthenticated | 60           | 5                 |

"Expensive ops" include `POST /v1/documents` (uploads), `POST /v1/documents/{id}/structured-output`, and `POST /v1/documents/{id}/chat/completions`. All other endpoints count as standard requests.

## Rate limit headers

Every API response includes rate limit information:

| Header                  | Description                       |
| ----------------------- | --------------------------------- |
| `X-RateLimit-Limit`     | Max requests per window           |
| `X-RateLimit-Remaining` | Requests remaining                |
| `X-RateLimit-Reset`     | Unix timestamp when window resets |

## When rate limited

You receive a `429` response:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later."
  }
}
```

The `Retry-After` header tells you how many seconds to wait.

## Best practices

1. **Check headers** before hitting limits -- monitor `X-RateLimit-Remaining`
2. **Use exponential backoff** on 429 responses
3. **Batch small PDFs** -- prefer one large job over many small ones
4. **Cache results** -- store extraction results locally after fetching

```python theme={null}
import time

def respect_rate_limit(response):
    remaining = int(response.headers.get("X-RateLimit-Remaining", 1))
    if remaining <= 1:
        reset = int(response.headers.get("X-RateLimit-Reset", 0))
        wait = max(0, reset - time.time())
        time.sleep(wait)
```


# Security Model
Source: https://docs.okrapdf.com/api-reference/security-model

How authentication and access control work across the API.

## Two layers

1. **Authentication** — who is calling (API key, shared secret, JWT)
2. **Access policy** — what the caller can do on a specific document

## Authentication

Every request is authenticated via one of:

| Method          | Header                              | Use case                  |
| --------------- | ----------------------------------- | ------------------------- |
| API key         | `Authorization: Bearer okra_sk_...` | Server-to-server          |
| Publishable key | `Authorization: Bearer okra_pk_...` | Browser clients           |
| Shared secret   | `x-document-agent-secret: ...`      | Internal worker-to-worker |

Unauthenticated requests can still interact with documents that have a `public` grant in their access policy.

## Access policy

Each document has a deny-by-default access policy with explicit grants. A grant maps a **principal** (who) to **actions** (what).

```json theme={null}
{
  "access": {
    "default_effect": "deny",
    "grants": [
      { "principal": { "type": "owner" }, "actions": ["admin"] },
      { "principal": { "type": "public" }, "actions": ["query", "read_content"] }
    ]
  }
}
```

See [Access Policy](/api-reference/documents/access-policy) for the full reference.

## Route classes

### Document and source read surface (`/v1/documents/...`)

Processed outputs and public-source chat. Access is controlled by API credentials, source resolution, and document grants where applicable.

* `GET /v1/documents/{id}` — metadata
* `GET /v1/documents/{id}/pages/{page}` — page content
* `POST /v1/public/resolve/chat/completions` — public source chat

### Authenticated mutation surface (`/v1/...`)

Mutations and configuration require an API key.

* `POST /v1/documents` — upload and process a document
* `PUT /v1/documents/{id}/config` — set document config and access policy
* `POST /v1/files` — upload a passive file asset
* `POST /v1/host` — publish a hosted PDF deployment

## Caching

* Public routes: `Cache-Control: public` (CDN-safe)
* Private routes: `Cache-Control: private` or `no-store`


# Run Invoice Extraction
Source: https://docs.okrapdf.com/api-reference/workflows/create-invoice-extraction-run

POST /v1/workflows/invoice-extraction/runs
Start the built-in invoice extraction workflow.

## Overview

Starts an invoice-extraction workflow for one or more uploaded files. Parser and model controls are managed by okraPDF.

<ParamField type="object[]">
  File inputs. Each item must include `file_id`.
</ParamField>

<ParamField type="string">
  Optional existing table for results.
</ParamField>

<ParamField type="string">
  Quality preset.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.okrapdf.com/v1/workflows/invoice-extraction/runs \
    -H "Authorization: Bearer $OKRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "inputs": [{ "file_id": "file_abc123" }],
      "quality": "standard"
    }'
  ```
</RequestExample>


# Get Invoice Extraction Run
Source: https://docs.okrapdf.com/api-reference/workflows/get-invoice-extraction-run

GET /v1/workflows/invoice-extraction/runs/{run_id}
Get invoice extraction run metadata.

## Overview

Returns status, quality metadata, input file references, event stream URL, row URL, and export URLs for a run.

<ParamField type="string">
  Invoice extraction run ID.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/workflows/invoice-extraction/runs/run_abc123 \
    -H "Authorization: Bearer $OKRA_API_KEY"
  ```
</RequestExample>


# Invoice Extraction
Source: https://docs.okrapdf.com/api-reference/workflows/invoice-extraction

Built-in workflow for extracting invoice fields into reviewable outputs.

## Overview

The `invoice-extraction` workflow starts from one or more `/v1/files` inputs, runs okraPDF's built-in invoice processing pipeline, and returns run metadata plus JSON, CSV, XML, and XLSX export URLs.

Use this when you want an opinionated workflow instead of a one-off document question.

<Steps>
  <Step title="Upload one or more files">
    Use [Upload File](/api-reference/files/upload-file) or direct upload.
  </Step>

  <Step title="Create a run">
    Call [Run Invoice Extraction](/api-reference/workflows/create-invoice-extraction-run) with file IDs.
  </Step>

  <Step title="Review outputs">
    Poll the run, inspect exceptions, and download results.
  </Step>
</Steps>


# Invoice Extraction Results
Source: https://docs.okrapdf.com/api-reference/workflows/invoice-extraction-results

GET /v1/workflows/invoice-extraction/runs/{run_id}/results.json
Download invoice extraction results as JSON.

## Overview

Downloads normalized JSON results for an invoice extraction run. CSV, XML, and XLSX result endpoints are also available with the same run ID.

<ParamField type="string">
  Invoice extraction run ID.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/workflows/invoice-extraction/runs/run_abc123/results.json \
    -H "Authorization: Bearer $OKRA_API_KEY"
  ```
</RequestExample>


# List Invoice Extraction Runs
Source: https://docs.okrapdf.com/api-reference/workflows/list-invoice-extraction-runs

GET /v1/workflows/invoice-extraction/runs
List invoice extraction runs for the signed-in account.

## Overview

Returns invoice extraction runs indexed for the authenticated account.

<ParamField type="integer">
  Maximum number of runs to return.
</ParamField>

<ParamField type="string">
  Pagination cursor.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl https://api.okrapdf.com/v1/workflows/invoice-extraction/runs \
    -H "Authorization: Bearer $OKRA_API_KEY"
  ```
</RequestExample>


# How It Works
Source: https://docs.okrapdf.com/architecture

A workbench that helps you understand, verify, and manage PDF data

## The Simple Version

**Upload a PDF → Understand, verify, and manage the data inside.**

okraPDF is a workbench that helps you extract structured data from documents, verify its accuracy, and put it to work.

```mermaid theme={null}
flowchart LR
    A[Your PDF] --> B[okraPDF]
    B --> C[Understand]
    B --> D[Verify]
    B --> E[Manage]

    subgraph C[Understand]
        C1[Search]
        C2[Chat]
    end

    subgraph D[Verify]
        D1[Review]
        D2[Correct]
    end

    subgraph E[Manage]
        E1[Tables]
        E2[Charts]
        E3[Images]
        E4[Export]
    end

    style A fill:#1e293b,color:#f8fafc,stroke:#475569
    style B fill:#FFE01B,color:#1e293b,stroke:#E6C800
    style C fill:#16a34a,color:#fff,stroke:#15803d
    style D fill:#7c3aed,color:#fff,stroke:#6d28d9
    style E fill:#0369a1,color:#fff,stroke:#0284c7
```

## What You Get

<CardGroup>
  <Card title="Understand" icon="magnifying-glass">
    Search across all pages. Chat with AI that's grounded in your document.
  </Card>

  <Card title="Verify" icon="check-double">
    Review extracted data side-by-side with the original. Correct errors with AI assistance.
  </Card>

  <Card title="Manage" icon="table">
    Tables, charts, images, footnotes — detected, structured, and exportable.
  </Card>
</CardGroup>

## Behind the Scenes

When you upload a PDF, four things happen automatically:

<Steps>
  <Step title="Secure Upload">
    Your file goes directly to encrypted cloud storage. We never store files on local servers.
  </Step>

  <Step title="Text Extraction">
    We use [Google's Document AI](https://cloud.google.com/document-ai/docs/processors-list#processor_doc-ocr) to extract text with high accuracy — even from scanned documents and complex layouts.
  </Step>

  <Step title="Entity Detection">
    Our AI scans each page for tables, charts, images, footnotes, and signatures.
  </Step>

  <Step title="Workbench Ready">
    Your document is ready for search, chat, review, and export.
  </Step>
</Steps>

**Processing time:** 10-30 seconds for most documents.

## Review & Verify

In the review page, you can verify extracted data side-by-side with the original document. AI assists with corrections without hallucinating content.

```mermaid theme={null}
flowchart LR
    A[Extracted Data] --> B[AI Review]
    C[Original Page] --> B
    B --> D[Verified Data]

    style A fill:#1e293b,color:#f8fafc,stroke:#475569
    style B fill:#FFE01B,color:#1e293b,stroke:#E6C800
    style C fill:#1e293b,color:#f8fafc,stroke:#475569
    style D fill:#16a34a,color:#fff,stroke:#15803d
```

**How it works:**

* View extracted data alongside the original page image
* AI suggests corrections for punctuation and character errors
* You approve changes — the AI is constrained to correct, not rewrite

## AI Chat

When you chat with your document, we create a private workspace with all your extracted data:

```mermaid theme={null}
flowchart LR
    Q[Ask: What's the revenue in Q3?] --> AI

    subgraph Workspace["Your Private Workspace"]
        AI[AI Agent]
        PDF[Original PDF]
        T[Tables]
        C[Charts]
        TXT[Full Text]
    end

    AI --> PDF
    AI --> T
    AI --> C
    AI --> TXT
    AI --> R[Answer: $4.2M per Table 3 on page 12]

    style Q fill:#1e293b,color:#f8fafc,stroke:#475569
    style R fill:#16a34a,color:#fff,stroke:#15803d
    style AI fill:#FFE01B,color:#1e293b,stroke:#E6C800
    style Workspace fill:#1e3a5f,color:#f8fafc,stroke:#0ea5e9
    style PDF fill:#0ea5e9,color:#fff,stroke:#0284c7
    style T fill:#0ea5e9,color:#fff,stroke:#0284c7
    style C fill:#0ea5e9,color:#fff,stroke:#0284c7
    style TXT fill:#0ea5e9,color:#fff,stroke:#0284c7
```

**What's in your workspace:**

* Your original PDF
* All extracted tables, charts, and images
* Full document text
* Isolated from other users

## Security

| What We Do               | Why It Matters                                              |
| ------------------------ | ----------------------------------------------------------- |
| Encrypt files at rest    | Your documents are protected even if storage is compromised |
| Encrypt all transfers    | No one can intercept your uploads or downloads              |
| Isolate AI sessions      | Your data never mixes with other users' data                |
| No training on your data | Your documents are never used to train AI models            |


# Chat
Source: https://docs.okrapdf.com/cli/chat

Ask a question about one processed document from the command line.

`okra chat` asks a question about a single processed document and returns a cited answer. It requires a document ID via `--doc`.

```bash theme={null}
okra chat "What was total revenue?" --doc doc-abc123
```

<Note>
  `okra chat` is the ergonomic alias for the canonical grounded command [`okra context ask`](/cli/reference). Both answer from bounded, cited context for one document.
</Note>

## Flags

| Flag             | Description                             |
| ---------------- | --------------------------------------- |
| `--doc <id>`     | Document ID to ask about (**required**) |
| `--model <name>` | Override the model                      |
| `--stream`       | Stream response tokens as they arrive   |

## Streaming

```bash theme={null}
okra chat "Summarize the key findings" --doc doc-abc123 --stream
```

With `--stream`, tokens print as they arrive. In `--json` mode the streamed answer is collected and returned as a single JSON payload.

## Machine-readable output

When stdout is not a TTY (or with `--json`), `okra chat` returns the standard envelope with the answer and any citations:

```json theme={null}
{
  "ok": true,
  "command": "chat",
  "result": { "answer": "Total revenue was $4.2M for FY2023." },
  "cost": { "usd": null },
  "citations": [],
  "next_actions": []
}
```

## Asking across multiple documents

To ask one question across several documents, group them into a collection and use [`okra collections query`](/cli/collections):

```bash theme={null}
okra collections query "Q4 Reports" "Compare revenue across companies"
```

<Tip>
  For general questions that aren't about a specific document, use a chat client connected via [MCP](/mcp/overview) rather than `okra chat`, which always operates on one document.
</Tip>


# Collections
Source: https://docs.okrapdf.com/cli/collections

Query across a collection of documents from the CLI.

A **collection** groups documents so you can ask one question across all of them. From the CLI you **list** collections and **query** them. Collections themselves are created and managed in the [web app](/web/overview) or via the [Collections API](/api-reference/collections/create-collection) — there is no `okra collections create`.

## Commands

```bash theme={null}
okra collections list                          # list your collections
okra collections query <name-or-id> "<question>"  # ask one question across the collection
```

<Tip>
  `collections` accepts either a **collection name** or a **collection ID** (`col-...`). The CLI tries ID lookup first, then falls back to name.
</Tip>

## List collections

```bash theme={null}
okra collections list
okra collections list --json
```

## Query a collection

`okra collections query` fans the same question out across every document in the collection and returns the combined result.

```bash theme={null}
okra collections query earnings "What changed quarter over quarter?"

# Write the result to a file (CSV / JSON inferred from extension)
okra collections query earnings "What changed quarter over quarter?" -o earnings.csv
```

| Flag              | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| `--schema <file>` | **Experimental.** JSON Schema file for structured fan-out extraction |

```bash theme={null}
# Experimental structured fan-out
okra collections query earnings "Extract revenue and net income" --schema ./schema.json
```

## Creating and publishing collections

Creating a collection, adding or removing documents, and publishing a collection to a public URL are not CLI operations:

* **Create / manage** — use the [web app](/web/overview) or `POST /v1/collections` (see [Create a collection](/api-reference/collections/create-collection)).
* **Publish** — publishing to a public URL asserts that you own or are licensed to publish the content, so it is a deliberate, gated action in the web app, not a one-line CLI flag.

<Info>
  Public collection pages live at `okrapdf.com/c/<slug>`. They are part of the free, read-only public tier — see the [web overview](/web/overview) for how the surfaces relate.
</Info>


# Extract
Source: https://docs.okrapdf.com/cli/extract

Upload a PDF and extract structured data in one command.

`okra extract` uploads, processes, and extracts structured data from a PDF in one step. The source can be a **local file path**, a **URL**, or the **document ID** of a PDF you already uploaded.

```bash theme={null}
# From a local file
okra extract ./report.pdf

# From a URL
okra extract https://example.com/report.pdf

# From an existing document
okra extract doc-abc123
```

## Structured extraction with a schema

Pass a JSON Schema to get structured JSON back. The schema can be a file path or inline JSON.

```bash theme={null}
okra extract ./invoice.pdf \
  --schema ./invoice.schema.json \
  --prompt "Extract vendor, total, currency, and due date"
```

When stdout is not a TTY (or with `--json`), the result comes back in the standard envelope:

```json theme={null}
{
  "ok": true,
  "command": "extract",
  "result": { "data": {} },
  "cost": { "usd": null },
  "citations": [],
  "next_actions": []
}
```

## Per-field citations (`--cite`)

Add `--cite` to attach **per-field source citations** — the page and bounding box each extracted value came from. Grounding is opt-in: without `--cite` you get values only.

```bash theme={null}
okra extract ./invoice.pdf --schema ./invoice.schema.json --cite
```

Citations are returned in the Anthropic-shaped `citations` array (`type: page_location`, with the source page, bbox, and the schema field each value maps to), alongside the extracted `data`.

## Fire-and-forget (`--no-wait`)

By default `okra extract` waits for processing to finish. Use `--no-wait` to queue the work and return immediately; follow up with `okra jobs wait`.

```bash theme={null}
okra extract ./report.pdf --no-wait
okra jobs wait <docId>
```

## Flags

| Flag               | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| `--schema <file>`  | JSON Schema file or inline JSON for structured extraction                |
| `--prompt <query>` | Extraction prompt (default: "Extract all data according to the schema")  |
| `--cite`           | Return per-field source citations (page + bbox) for each extracted value |
| `--no-wait`        | Fire-and-forget — queue the job and don't wait for processing            |

Global flags (`--json`, `--quiet`, `--output`) apply as well — see the [CLI Reference](/cli/reference).

<Tip>
  To browse a document's text, tables, and structure after extraction, use the grounded [`context`](/cli/reference) commands (`okra context structure`, `okra context tables`, `okra context get`) or read raw markdown with `okra read <docId>`.
</Tip>


# Jobs
Source: https://docs.okrapdf.com/cli/jobs

Inspect, wait on, and control parse, render, and workflow jobs.

`okra jobs` inspects the parse, render, and workflow jobs your other commands create. Jobs are created implicitly — `okra upload`, `okra extract`, `okra parse`, `okra render`, and the workflow commands all enqueue a job — so the `jobs` surface is for **listing, waiting, and controlling** them, not creating them.

## Recommended flow

```bash theme={null}
# 1) Kick off work that enqueues a job (e.g. a fire-and-forget parse)
okra upload ./report.pdf --no-wait

# 2) Wait for the latest parse job for that document
okra jobs wait <docId> --timeout 600

# 3) Inspect the job and its result
okra jobs get <jobId>
```

<Tip>
  `okra jobs wait` accepts **either** a job ID **or** a document ID. Given a document ID, it waits for that document's latest `document.parse` job.
</Tip>

## Commands

```bash theme={null}
okra jobs list                       # list your jobs (newest first)
okra jobs list --status completed    # filter by status
okra jobs list --type document.parse # filter by job type
okra jobs list --doc <docId>         # filter by document
okra jobs get <jobId>                # job status + result (alias: show)
okra jobs wait <jobOrDocId>          # block until a job finishes
okra jobs events <jobId>             # print the job event-stream URL
okra jobs cancel <jobId>             # cancel a queued or running job
okra jobs retry <jobId>              # retry a failed job
okra jobs resume <jobId>             # resume a paused job
```

### `jobs list` flags

| Flag                | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `--limit <n>`       | Max jobs to return                                            |
| `--type <type>`     | Filter by job type (e.g. `document.parse`, `document.render`) |
| `--status <status>` | Filter by job status                                          |
| `--doc <docId>`     | Filter to jobs for one document                               |

Combine with the global `--json` flag for machine-readable output:

```bash theme={null}
okra jobs list --status completed --limit 5 --json
```

When stdout is not a TTY, `okra jobs` commands emit the standard envelope. For example, `okra jobs list --json` returns:

```json theme={null}
{
  "ok": true,
  "command": "jobs list",
  "result": { "jobs": [] },
  "cost": { "usd": null },
  "citations": [],
  "next_actions": []
}
```

### `jobs wait`

```bash theme={null}
okra jobs wait <jobId>
okra jobs wait <docId>               # waits for the latest document.parse job
okra jobs wait <jobOrDocId> --timeout 600
```

| Flag                  | Description                              |
| --------------------- | ---------------------------------------- |
| `--timeout <seconds>` | Maximum seconds to wait (default: `300`) |

### `jobs cancel`, `retry`, and `resume`

```bash theme={null}
okra jobs cancel <jobId>             # cancel a queued or running job
okra jobs retry <jobId>              # retry a failed job
okra jobs resume <jobId>             # resume a paused job
```

Only non-terminal jobs can be cancelled; only failed jobs can be retried; only paused jobs can be resumed.

<Info>
  To create work, use a verb command (`okra upload`, `okra extract`, `okra parse`, `okra render`) rather than `okra jobs`. Those commands enqueue the job and, by default, wait for it — add `--no-wait` to queue and follow up with `okra jobs wait`.
</Info>


# Quickstart
Source: https://docs.okrapdf.com/cli/quickstart

Install the Okra CLI and work with PDFs from your terminal.

## Install

```bash theme={null}
npm install -g @okrapdf/cli
```

The package installs the `okra` binary. For one-off usage:

```bash theme={null}
npx @okrapdf/cli --help
```

## Authenticate

```bash theme={null}
export OKRA_API_KEY=okra_sk_YOUR_KEY

okra auth set-key "$OKRA_API_KEY"
okra auth status
```

## Upload a PDF

```bash theme={null}
okra upload ./report.pdf
okra upload https://example.com/report.pdf
```

## Ask a question

```bash theme={null}
okra chat "What is total revenue?" --doc doc-abc123
```

## Extract structured data

```bash theme={null}
okra extract ./invoice.pdf \
  --schema ./invoice.schema.json \
  --prompt "Extract vendor, total, currency, and due date"
```

## Read markdown

```bash theme={null}
okra read doc-abc123 --pages 1-3
```

## Machine and agent output

When stdout is not a TTY, most `okra` commands automatically emit a structured JSON envelope. You can also force this in an interactive terminal with `--json`:

```bash theme={null}
okra context resolve "https://example.com/report.pdf" --json
okra extract ./invoice.pdf --schema ./schema.json --json
```

The envelope returns a uniform success/failure shape with `ok`, `result`, `cost`, `citations`, and `next_actions`. See the [CLI Reference](/cli/reference) for the full envelope contract, stable error codes, and agent stop-gate rules.

## What's next

<CardGroup>
  <Card title="Extract" icon="file-pdf" href="/cli/extract">
    Structured extraction flags and examples.
  </Card>

  <Card title="Chat" icon="message" href="/cli/chat">
    Ask questions against a processed document.
  </Card>

  <Card title="Collections" icon="list-check" href="/cli/collections">
    Query across multiple documents.
  </Card>

  <Card title="Reference" icon="terminal" href="/cli/reference">
    Auth, environment variables, and global flags.
  </Card>
</CardGroup>


# Reference
Source: https://docs.okrapdf.com/cli/reference

Current auth, environment variables, and global CLI options.

## Envelope format

When stdout is not a TTY (and always with `--json`), every command emits a structured JSON envelope that unifies success and failure:

```json theme={null}
{
  "ok": true,
  "command": "context resolve",
  "result": {},
  "cost": { "usd": null },
  "citations": [],
  "next_actions": []
}
```

On failure, the same top-level shape is used with `"ok": false` and additional fields:

```json theme={null}
{
  "ok": false,
  "command": "collections publish",
  "error": "confirmation_required",
  "message": "Public publish asserts that you own or are licensed to publish this content.",
  "cost": { "usd": null },
  "citations": [],
  "next_actions": [
    {
      "cmd": "okra collections publish earnings --confirm-rights",
      "why": "Confirm the public publish rights gate explicitly."
    }
  ]
}
```

### Field reference

| Field          | Description                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| `ok`           | `true` on success, `false` on failure.                                         |
| `command`      | The command name as executed (e.g. `context resolve`).                         |
| `result`       | Command-specific payload on success.                                           |
| `error`        | Stable, **machine-readable** error code on failure (never a freeform message). |
| `message`      | Human-readable explanation of the failure.                                     |
| `cost`         | Estimated cost, when available (`usd` field).                                  |
| `citations`    | Any source citations returned by the command.                                  |
| `next_actions` | Suggested follow-up commands that an agent can run directly.                   |

### Error codes and exit codes

* `error` is always a stable machine code (e.g. `confirmation_required`, `human_review_required`, `engine_not_available`). Freeform messages go in `message`, not `error`.
* Commands that fail with `"ok": false` return a **non-zero** exit code.
* When a command succeeds, the exit code is zero.

### Agent stop-gates

Agents must **stop** when `error` is either `confirmation_required` or `human_review_required`, show the `message` to a human, and only rerun a `next_actions[].cmd` after explicit approval. Do not add confirmation flags (e.g. `--confirm-rights`, `--yes`, `--attest`) without human input.

### Enabling JSON output

```bash theme={null}
# Automatic when stdout is not a TTY
okra context resolve "https://example.com/report.pdf" | jq .

# Force JSON in an interactive terminal
okra upload ./report.pdf --json
okra upload ./report.pdf -o json
```

## Global options

```text theme={null}
okra --help
okra --version
okra --json
okra --quiet
okra --output result.json
```

| Flag              | Description                                  |
| ----------------- | -------------------------------------------- |
| `--json`          | Emit machine-readable JSON where supported.  |
| `--quiet`         | Suppress progress and human-readable output. |
| `--output <file>` | Write output to a file instead of stdout.    |
| `--version`       | Print the installed package version.         |

## Auth

```bash theme={null}
okra auth login
okra auth set-key okra_sk_YOUR_KEY
okra auth status
okra auth whoami
okra auth token
okra auth logout
```

## Primary commands

```bash theme={null}
okra upload ./report.pdf
okra extract ./invoice.pdf --schema ./schema.json
okra chat "Summarize this document" --doc doc-abc123
okra read doc-abc123 --pages 1-5
okra list
okra delete doc-abc123
okra collection query earnings "What changed quarter over quarter?"
```

## Noun-first agent surface

The agent contract uses stable resource nouns that match API resources and the `/v1/resources` catalog. Legacy ergonomic verbs (e.g. `upload`, `read`, `chat`, `extract`, `parse`, `audit`, `redact`, `render`) remain compatible, but the preferred agent surface is:

* `resources`
* `documents`
* `files`
* `jobs`
* `agents`
* `workflows`
* `collections`

Run `okra resources list` to discover every API noun and verb, and `okra <noun> --help` for a resource's subcommands.

## Grounded context commands

Before (or instead of) a full parse, the `context` commands navigate a source and retrieve bounded, cited context:

```bash theme={null}
okra context structure doc-abc123          # navigable sections, page ranges, artifacts
okra context tables doc-abc123             # detected tables with columns + page hints
okra context get "termination clause" --source-id doc-abc123
okra context ask "What is the guaranteed fee?" --source-id doc-abc123
```

## Environment variables

| Variable        | Description                                        |
| --------------- | -------------------------------------------------- |
| `OKRA_API_KEY`  | API key used by authenticated commands.            |
| `OKRA_BASE_URL` | API origin. Defaults to `https://api.okrapdf.com`. |
| `OKRA_QUIET`    | Set to `1` for quiet mode.                         |


# Verify
Source: https://docs.okrapdf.com/cli/verify

Verify a claim against a document page with bbox-grounded evidence.

## Overview

`okra documents verify` checks a **specific claim** against a **specific page** of a document and returns a grounded verdict with visual evidence. It answers "is this claim supported by what's actually on the page?" — not a page-level approval workflow.

```bash theme={null}
okra documents verify <docId> "<claim>" --page <n>
```

The vision model reads the page and returns one of three verdicts:

* **`supported`** — the page supports the claim
* **`contradicted`** — the page contradicts the claim
* **`not_visible`** — the claim can't be confirmed from what's on the page

## Verify a claim

```bash theme={null}
okra documents verify doc-abc123 "Total revenue was $4.2M in FY2023" --page 2
```

```json theme={null}
{
  "ok": true,
  "command": "documents verify",
  "result": {
    "verdict": "supported",
    "page": 2,
    "bbox": { "x": 0.12, "y": 0.34, "w": 0.4, "h": 0.05 },
    "evidence_snippet": "Total revenue for the fiscal year ended 2023 was $4.2M.",
    "page_image_url": "https://res.okrapdf.com/v1/documents/doc-abc123/pg_2.png",
    "confidence": 0.96,
    "model": "gemini-3-flash"
  },
  "cost": { "usd": null },
  "citations": [],
  "next_actions": []
}
```

Every result carries the **page**, an `evidence_snippet` of the supporting (or contradicting) text, a `page_image_url` for visual reference, a `confidence` score, and the resolved `bbox` of the evidence on the page.

## Focus on a region (`--bbox`)

Pass `--bbox` to constrain verification to a region of the page instead of the whole page. Coordinates are normalized `{ "x", "y", "w", "h" }`.

```bash theme={null}
okra documents verify doc-abc123 "The signature is dated March 3" \
  --page 7 \
  --bbox '{"x":0.1,"y":0.8,"w":0.3,"h":0.1}'
```

## Arguments and flags

| Argument / Flag | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| `<docId>`       | Document ID (or 6-char short hash) to verify against        |
| `<claim>`       | The claim to check, as a quoted string                      |
| `--page <n>`    | Page number (1-based) to verify against (**required**)      |
| `--bbox <json>` | Optional region `{"x":..,"y":..,"w":..,"h":..}` to focus on |

## Pipe-friendly use

`okra documents verify` emits the standard envelope, so a verdict is easy to branch on in a script:

```bash theme={null}
verdict=$(okra documents verify doc-abc123 "Revenue grew YoY" --page 2 --json \
  | jq -r '.result.verdict')

[ "$verdict" = "supported" ] && echo "claim holds"
```

<Info>
  This is the document-level claim check. To verify a PDF-backed claim from an agent (with `document_id` or a public `pdf_url`), use the `verify_source` tool over [MCP](/mcp/overview).
</Info>


# React Hooks
Source: https://docs.okrapdf.com/developers/react

React helpers from the @okrapdf/sdk/react subpath.

## Install

```bash theme={null}
npm install @okrapdf/sdk
```

`@okrapdf/sdk/react` is a subpath export of the SDK package, not a separate npm package.

## OkraProvider

Wrap a subtree with `OkraProvider` and provide either a `documentId`, a `url`, or a `file`.

```tsx theme={null}
'use client';

import { OkraProvider } from '@okrapdf/sdk/react';

export function DocumentRoot({ documentId, children }) {
  return (
    <OkraProvider
      apiKey={process.env.NEXT_PUBLIC_OKRA_PUBLISHABLE_KEY}
      documentId={documentId}
    >
      {children}
    </OkraProvider>
  );
}
```

<Warning>
  Use publishable browser keys or a server-side boundary for browser apps. Do not expose `okra_sk_` secret keys in client-side bundles.
</Warning>

## Status and pages

```tsx theme={null}
import { useOkraDocument, useDocumentStatus, usePages } from '@okrapdf/sdk/react';

function DocumentPanel() {
  const { session, documentId, isReady } = useOkraDocument();
  const status = useDocumentStatus(session);
  const pages = usePages(session, { enabled: isReady });

  if (status.error) return <p>{status.error.message}</p>;
  if (!documentId) return <p>Resolving document...</p>;

  return (
    <section>
      <p>{status.data?.phase ?? 'loading'}</p>
      {pages.data.map((page) => (
        <article key={page.pageNumber ?? page.page}>
          <h2>Page {page.pageNumber ?? page.page}</h2>
          <pre>{page.markdown ?? page.content}</pre>
        </article>
      ))}
    </section>
  );
}
```

## Chat

```tsx theme={null}
import { useChat, useOkraDocument } from '@okrapdf/sdk/react';

function ChatPanel() {
  const { session } = useOkraDocument();
  const chat = useChat({ session, stream: true });

  return (
    <form onSubmit={chat.handleSubmit}>
      {chat.messages.map((message) => (
        <p key={message.id}>
          <strong>{message.role}</strong>: {message.content}
        </p>
      ))}
      <input
        value={chat.input}
        onChange={chat.handleInputChange}
        placeholder="Ask about this document"
      />
      <button disabled={chat.isLoading || !session}>Send</button>
    </form>
  );
}
```

## Structured extraction

The React package does not ship a separate `useStructuredOutput` hook. Call `session.prompt(...)` with a schema from your component or wrap it in your app's own state hook.

```tsx theme={null}
import { useState } from 'react';
import { z } from 'zod';
import { useOkraDocument } from '@okrapdf/sdk/react';

const Invoice = z.object({
  vendor: z.string(),
  total: z.number(),
});

function InvoiceFields() {
  const { session } = useOkraDocument();
  const [data, setData] = useState<z.infer<typeof Invoice> | null>(null);

  async function extract() {
    if (!session) return;
    const result = await session.prompt('Extract invoice fields', {
      schema: Invoice,
    });
    setData(result.data ?? null);
  }

  return (
    <section>
      <button onClick={extract} disabled={!session}>Extract</button>
      {data ? <pre>{JSON.stringify(data, null, 2)}</pre> : null}
    </section>
  );
}
```

## DocumentAgent realtime context

For realtime DocumentAgent state and methods, use `createOkraContext(...)`. This requires the `agents` React package in your app.

```tsx theme={null}
import { createOkraContext } from '@okrapdf/sdk/react';

const okra = createOkraContext({
  host: 'https://api.okrapdf.com',
  agent: 'DocumentAgent',
  authEndpoint: '/api/okra/document-token',
});

export function LiveDocument({ documentId }) {
  const document = okra.useDocument(documentId);
  const phase = okra.useDocumentSlice(documentId, (state) => state.phase);

  return <p>{phase ?? document.state?.phase ?? 'connecting'}</p>;
}
```


# TypeScript SDK
Source: https://docs.okrapdf.com/developers/sdk

Use @okrapdf/sdk for document sessions, files, collections, and workflows.

## Install

```bash theme={null}
npm install @okrapdf/sdk
```

```ts theme={null}
import { createOkra, OkraClient } from '@okrapdf/sdk';
import { doc } from '@okrapdf/sdk/doc';
```

`createOkra(...)` returns an `OkraClient`. Use it when you want workflow defaults or middleware-style options. Use `new OkraClient(...)` when you want the direct class.

## Upload and ask

```ts theme={null}
import { createOkra } from '@okrapdf/sdk';

const okra = createOkra({ apiKey: process.env.OKRA_API_KEY });

const session = await okra.sessions.create('./report.pdf', {
  wait: true,
  model: 'anthropic/claude-haiku-4.5',
});

const { answer, sources } = await session.prompt('What is total revenue?');

console.log(answer);
console.log(sources);
```

`sessions.create(...)` accepts local file paths in Node, URLs, `Blob`, `ArrayBuffer`, or `Uint8Array`. Use `sessions.from(documentId)` to attach to an existing document.

## Read pages and entities

```ts theme={null}
const status = await session.status();
const pages = await session.pages({ range: '1-3' });
const tables = await session.entities({ type: 'table' });

console.log(status.phase, pages.length, tables.nodes.length);
```

## Structured output

```ts theme={null}
import { z } from 'zod';

const Invoice = z.object({
  vendor: z.string(),
  total: z.number(),
  currency: z.string().optional(),
});

const result = await session.prompt('Extract invoice fields', {
  schema: Invoice,
});

console.log(result.data);
```

## Streaming

```ts theme={null}
for await (const event of session.stream('Summarize in 3 bullets')) {
  if (event.type === 'text_delta') process.stdout.write(event.text);
  if (event.type === 'done') console.log('\nfinal:', event.answer);
}
```

## Passive file assets

Use `files.upload(...)` when you want to store a PDF first and decide later whether to parse, host, or run a workflow.

```ts theme={null}
const file = await okra.files.upload('./invoice.pdf');

console.log(file.id);
console.log(file.urls.bytes);
```

## Host and URL building

The SDK exports a deterministic URL builder for document-derived assets:

```ts theme={null}
const d = doc(session.id, { fileName: 'report.pdf' });

console.log(d.pg[1].png());
console.log(d.pg[1].md());
console.log(d.full.md());
```

For clean hosted PDF deployments, call the REST [Host API](/api-reference/host/create-hosted-pdf) or upload through `files.upload(...)` and publish with `/v1/host`.

## Invoice extraction workflow

```ts theme={null}
const file = await okra.files.upload('./invoice.pdf');

const run = await okra.runInvoiceExtraction({
  inputs: [file.id],
  quality: 'standard',
});

console.log(run.runId, run.exports.csvUrl, run.exports.jsonUrl);
```

## Dynamic agent workflows

The stable SDK surface currently exposes built-in workflows such as invoice extraction. Custom workflow authoring lives in the MCP and REST workflow surfaces:

* Use [MCP](/mcp/overview) when an agent should draft, run, and inspect a workflow.
* Use `POST /v1/workflows` and `POST /v1/runs` when your app wants to create and run a workflow directly.

## Collections

```ts theme={null}
const stream = okra.collections.query(
  'col-abc123',
  'Extract revenue, net income, and EPS.',
);

for await (const event of stream) {
  console.log(event);
}
```

## API surface

```ts theme={null}
createOkra({ apiKey, baseUrl?, sharedSecret?, fetch?, workflow? }) => OkraClient

okra.sessions.create(sourceOrDocId, { wait?, model?, upload?, waitOptions? }) => session
okra.sessions.from(documentId, { model? }) => session

okra.files.upload(input, options?)
okra.files.get(fileId)
okra.files.list(options?)
okra.files.delete(fileId)

session.status()
session.wait()
session.pages({ range? })
session.page(pageNumber)
session.entities({ type?, limit?, offset? })
session.prompt(query, { schema?, model? })
session.stream(query, options?)
session.publish()
session.shareLink({ role, expiresInMs, maxViews, label })
```


# FAQ
Source: https://docs.okrapdf.com/faq

Common questions about okraPDF

## Getting Started

<AccordionGroup>
  <Accordion title="How much free credit do I get?" icon="gift">
    New accounts start with \*\*$5 free credit** (~250 pages at $0.02/page). No credit card required. After you've used your free credit, you can add more from Settings.
  </Accordion>

  <Accordion title="What file types are supported?" icon="file">
    okraPDF supports:

    * **PDF files** — native PDFs and scanned documents
    * **Images** — PNG, JPG, JPEG (converted to single-page PDF)

    We don't currently support Word docs, Excel files, or PowerPoint. Export those as PDF first.
  </Accordion>

  <Accordion title="Is there a file size limit?" icon="weight-hanging">
    Yes:

    * **Maximum file size:** 100 MB
    * **Maximum pages:** 500 pages per document

    For larger documents, consider splitting into smaller files.
  </Accordion>

  <Accordion title="How long does processing take?" icon="clock">
    Most documents process in **10-30 seconds**. Factors that affect speed:

    * Page count — more pages take longer
    * Scan quality — low-quality scans need more OCR processing
    * Table complexity — dense tables require more analysis
  </Accordion>
</AccordionGroup>

## Extraction Quality

<AccordionGroup>
  <Accordion title="How accurate is the OCR?" icon="bullseye">
    okraPDF uses Google Document AI, which achieves **95%+ accuracy** on clean documents. Accuracy depends on:

    * **Document quality** — 300 DPI scans work best
    * **Text clarity** — handwriting is less accurate than typed text
    * **Language** — English has the highest accuracy
  </Accordion>

  <Accordion title="What if extraction has errors?" icon="triangle-exclamation">
    Use the Review feature:

    1. Click any extracted table or figure
    2. Compare side-by-side with the original
    3. Click to edit — AI suggests corrections
    4. Approve changes

    The AI only corrects based on what's in the original image. It won't add or invent data.
  </Accordion>

  <Accordion title="Can it handle scanned documents?" icon="scanner">
    Yes. okraPDF handles both native PDFs (with embedded text) and scanned images. For best results with scans:

    * Use 300 DPI or higher resolution
    * Ensure pages are straight (not skewed)
    * Avoid shadows or dark edges
  </Accordion>

  <Accordion title="What about handwritten content?" icon="pen">
    Handwriting recognition is supported but less accurate than printed text. Complex or cursive handwriting may have lower confidence scores. Always verify handwritten content in the Review view.
  </Accordion>
</AccordionGroup>

## Tables and Figures

<AccordionGroup>
  <Accordion title="What table formats are detected?" icon="table">
    okraPDF detects:

    * Standard grid tables with borders
    * Borderless tables (aligned by whitespace)
    * Multi-level headers
    * Merged cells
    * Tables spanning multiple pages
  </Accordion>

  <Accordion title="What counts as a 'figure'?" icon="image">
    Figures include:

    * Charts and graphs (bar, line, pie, etc.)
    * Diagrams and flowcharts
    * Photos and illustrations
    * Logos and signatures
    * Infographics
  </Accordion>

  <Accordion title="Are captions linked to figures?" icon="tag">
    Yes. When we detect a figure, we also look for nearby captions (like "Figure 1: Revenue Growth") and link them together in the extraction.
  </Accordion>
</AccordionGroup>

## Exporting Data

<AccordionGroup>
  <Accordion title="What export formats are available?" icon="file-export">
    * **CSV** — Opens in Excel, Google Sheets, any spreadsheet app
    * **JSON** — Structured data for developers
    * **Markdown** — For documentation and notes
    * **Clipboard** — Paste directly into spreadsheets
  </Accordion>

  <Accordion title="Can I export all tables at once?" icon="layer-group">
    Currently, you export tables one at a time. We're working on batch export features.
  </Accordion>

  <Accordion title="Is the original PDF structure preserved?" icon="sitemap">
    Yes. We preserve:

    * Table headers and column structure
    * Row order and cell alignment
    * Merged cell boundaries
    * Page location reference
  </Accordion>
</AccordionGroup>

## Privacy and Security

<AccordionGroup>
  <Accordion title="Where are my documents stored?" icon="cloud">
    Documents are stored in Google Cloud Storage with:

    * Encryption at rest (AES-256)
    * Encryption in transit (TLS 1.3)
    * Data centers in the United States
  </Accordion>

  <Accordion title="Is my data used to train AI models?" icon="brain">
    **No.** Your documents are never used to train AI models. We use Google Document AI and other services that process your data but don't retain it for training.
  </Accordion>

  <Accordion title="Can I delete my documents?" icon="trash">
    Yes. Delete any document from your library at any time. Deleted documents are removed from our storage within 24 hours.
  </Accordion>

  <Accordion title="Who can see my documents?" icon="lock">
    Only you. Documents are isolated per account. We don't share your data with other users or third parties (except our infrastructure providers listed in our privacy policy).
  </Accordion>
</AccordionGroup>

## Account and Billing

<AccordionGroup>
  <Accordion title="How do credits work?" icon="coins">
    okraPDF uses a prepaid credit system:

    * Add credits from Settings (min \$5, no processing fee)
    * OCR costs \$0.02 per page
    * Chat costs the actual API cost (typically \$0.01-0.05/message)
    * Credits never expire
    * Failed uploads are automatically refunded
  </Accordion>

  <Accordion title="What happens when I run out of credits?" icon="battery-empty">
    You can still view and export previously processed documents. To process new documents or chat, add credits from Settings.
  </Accordion>

  <Accordion title="Can I get a refund?" icon="rotate-left">
    Failed document processing is automatically refunded. For other refund requests, email [support@okrapdf.com](mailto:support@okrapdf.com).
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="My upload is stuck" icon="spinner">
    Try these steps:

    1. Refresh the page
    2. Check your internet connection
    3. Try a smaller file (under 50 MB)
    4. Clear browser cache and retry

    If still stuck, email [support@okrapdf.com](mailto:support@okrapdf.com) with your document details.
  </Accordion>

  <Accordion title="Tables aren't being detected" icon="table-cells">
    Some tables may not be detected if:

    * The table lacks clear structure (no borders, inconsistent spacing)
    * It's actually a formatted list, not a table
    * The scan quality is too low

    Try uploading at higher resolution or with a cleaner scan.
  </Accordion>

  <Accordion title="Export isn't working" icon="download">
    1. Ensure pop-ups aren't blocked
    2. Try a different browser
    3. Use "Copy to Clipboard" as an alternative
    4. Check if your browser has sufficient permissions
  </Accordion>
</AccordionGroup>

## Still have questions?

<Card title="Contact Support" icon="headset" href="mailto:support@okrapdf.com">
  Email us at [support@okrapdf.com](mailto:support@okrapdf.com) — we typically respond within 24 hours.
</Card>


# Chat Widget
Source: https://docs.okrapdf.com/integrations/chat-widget

Embed a PDF chatbot on any website with one script tag

## Overview

Add a floating chat bubble to any website that answers questions about your PDF. One script tag, zero dependencies, streaming responses.

<Card title="Live Demo" icon="message-bot" href="https://typebot-integration.okrapdf.dev">
  Try the embedded chat widget on a live page
</Card>

## Quick Start

Upload a document, then paste this before `</body>`:

```html theme={null}
<script src="https://typebot-integration.okrapdf.dev/widget.js"
        data-doc="YOUR_DOC_ID"
        data-key="YOUR_PUBLISHABLE_KEY"></script>
```

That's it. A chat bubble appears in the bottom-right corner. Your visitors ask questions, the widget streams answers from your PDF.

<Steps>
  <Step title="Upload a PDF">
    ```bash theme={null}
    okra upload earnings.pdf
    # → Document ID: ocr-abc123
    ```
  </Step>

  <Step title="Get a publishable key">
    Create a key scoped for client-side use in your [dashboard](https://app.okrapdf.com/dashboard). Publishable keys (prefixed `okra_pk_`) can only read — they can't upload or delete documents.
  </Step>

  <Step title="Add the script tag">
    ```html theme={null}
    <script src="https://typebot-integration.okrapdf.dev/widget.js"
            data-doc="ocr-abc123"
            data-key="okra_pk_your_key_here"></script>
    ```
  </Step>
</Steps>

## How It Works

The widget calls okraPDF's OpenAI-compatible completions endpoint directly from the browser:

```
Browser → POST /v1/documents/{id}/chat/completions → Streaming SSE response
```

No backend proxy needed. The publishable key restricts access to read-only completions on that specific document.

## Use with Chatbot Builders

Since the completions API is OpenAI-compatible, any chatbot platform that supports custom endpoints works out of the box.

<AccordionGroup>
  <Accordion title="Typebot">
    Add an **HTTP Request** block:

    * **URL:** `https://api.okrapdf.com/v1/documents/YOUR_DOC_ID/chat/completions`
    * **Method:** POST
    * **Headers:** `Authorization: Bearer YOUR_OKRA_KEY`
    * **Body:** `{"model":"moonshotai/kimi-k2.5","messages":[{"role":"user","content":"{{userQuestion}}"}]}`
    * **Response mapping:** `choices[0].message.content` → your response variable
    * **Timeout:** Set to 120s (LLM calls take 5-30s)
  </Accordion>

  <Accordion title="Botpress / Voiceflow / Flowise">
    Any platform with a "Custom OpenAI" or "HTTP Request" integration:

    * **Base URL:** `https://api.okrapdf.com/v1/documents/YOUR_DOC_ID`
    * **API Key:** Your okraPDF key (passed as OpenAI API key)
    * **Model:** `moonshotai/kimi-k2.5`
  </Accordion>

  <Accordion title="Python / Node.js (OpenAI SDK)">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.okrapdf.com/v1/documents/YOUR_DOC_ID",
        api_key="okra_pk_your_key_here",
    )

    response = client.chat.completions.create(
        model="moonshotai/kimi-k2.5",
        messages=[{"role": "user", "content": "What was total revenue?"}],
    )
    print(response.choices[0].message.content)
    ```
  </Accordion>

  <Accordion title="n8n">
    Use the [okraPDF n8n node](https://github.com/okrapdf/n8n-nodes-okrapdf) for native integration.
  </Accordion>
</AccordionGroup>

## Customization

The widget accepts these `data-` attributes:

| Attribute  | Description                    | Default |
| ---------- | ------------------------------ | ------- |
| `data-doc` | Document ID (required)         | —       |
| `data-key` | Publishable API key (required) | —       |

For deeper customization (colors, position, greeting), fork the [widget source](https://github.com/okrapdf/examples/tree/main/chatpdf-widget) — it's \~80 lines of vanilla JS.

## Source Code

<CardGroup>
  <Card title="Widget Source" icon="github" href="https://github.com/okrapdf/examples/tree/main/chatpdf-widget">
    Vanilla JS, zero dependencies, \~80 lines
  </Card>

  <Card title="Live Demo" icon="globe" href="https://typebot-integration.okrapdf.dev">
    Deployed example with streaming chat
  </Card>
</CardGroup>


# Chrome Extension
Source: https://docs.okrapdf.com/integrations/chrome-extension

Capture and process PDFs directly from your browser

## Overview

See a PDF in your browser? Capture it with one click. The okraPDF Chrome Extension sends documents directly to your library for instant processing.

<Frame>
  <video />
</Frame>

<Info>
  **Current Version: 2.0.3** — Now with okraPDF branding and improved capture reliability.
</Info>

## Installation

<Steps>
  <Step title="Visit Chrome Web Store">
    Go to the [okraPDF Extension](https://chrome.google.com/webstore/detail/okrapdf) in the Chrome Web Store
  </Step>

  <Step title="Add to Chrome">
    Click "Add to Chrome" and confirm the permissions
  </Step>

  <Step title="Pin the Extension">
    Click the puzzle piece icon in Chrome's toolbar and pin okraPDF for easy access
  </Step>

  <Step title="Sign In">
    Click the extension icon and sign in with your okraPDF account
  </Step>
</Steps>

## How to Use

### Capture a PDF

When viewing a PDF in Chrome:

1. Click the okraPDF extension icon
2. Click **"Capture PDF"**
3. The document is sent to your okraPDF library

```mermaid theme={null}
flowchart LR
    A[PDF in Browser] --> B[Click Extension]
    B --> C[Capture PDF]
    C --> D[okraPDF Library]
    D --> E[Processing Starts]

    style A fill:#1e293b,color:#f8fafc,stroke:#475569
    style B fill:#FFE01B,color:#1e293b,stroke:#E6C800
    style C fill:#0ea5e9,color:#fff,stroke:#0284c7
    style D fill:#16a34a,color:#fff,stroke:#15803d
    style E fill:#16a34a,color:#fff,stroke:#15803d
```

### From Any Webpage

See a PDF link on a page? Right-click and select **"Send to okraPDF"** from the context menu.

## Features

<CardGroup>
  <Card title="One-Click Capture" icon="mouse-pointer">
    Send PDFs to your library without downloading first
  </Card>

  <Card title="Automatic Processing" icon="wand-magic-sparkles">
    OCR and extraction start automatically after capture
  </Card>

  <Card title="Context Menu" icon="bars">
    Right-click any PDF link to capture
  </Card>

  <Card title="Batch Capture" icon="layer-group">
    Select multiple PDF links and send them all at once
  </Card>
</CardGroup>

## Supported Sources

The extension works with PDFs from:

| Source                    | Support        |
| ------------------------- | -------------- |
| Direct PDF URLs           | Full support   |
| Google Drive previews     | Supported      |
| Dropbox shared links      | Supported      |
| Email attachments (Gmail) | Via preview    |
| Embedded viewers          | Most supported |

<Note>
  Some sites block extension access. If capture fails, download the PDF manually and upload to okraPDF.
</Note>

## Permissions Explained

The extension requests these permissions:

| Permission                | Why We Need It                   |
| ------------------------- | -------------------------------- |
| **Read browsing history** | Detect when you're viewing a PDF |
| **Access current tab**    | Capture the PDF content          |
| **Storage**               | Remember your login state        |

<Tip>
  We only access tabs when you click the extension. We never read your browsing history.
</Tip>

## After Capture

Once captured, you can:

1. **View processing status** — Click the extension to see capture history
2. **Open in okraPDF** — Click any captured document to open in the web app
3. **Continue browsing** — Processing happens in the background

## Extension Settings

Click the extension icon and select the gear icon to access settings:

| Setting                     | Description                                         |
| --------------------------- | --------------------------------------------------- |
| **Auto-open after capture** | Immediately open okraPDF after capture              |
| **Notifications**           | Show desktop notification when processing completes |
| **Default folder**          | Choose which library folder receives captures       |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Extension not capturing">
    1. Ensure you're signed in (click extension icon to check)
    2. Try refreshing the page
    3. Check if the site blocks extensions (some enterprise sites do)
  </Accordion>

  <Accordion title="'Not a PDF' error">
    The page may be rendering a PDF in a custom viewer. Try:

    1. Right-click the PDF and "Open in new tab"
    2. Download and upload manually
  </Accordion>

  <Accordion title="Capture stuck">
    Large PDFs (50+ MB) may take longer. Check your okraPDF library—the document may still be processing.
  </Accordion>

  <Accordion title="Extension disappeared">
    Click the puzzle piece icon in Chrome's toolbar and re-pin okraPDF.
  </Accordion>
</AccordionGroup>

## Version History

| Version   | Changes                                |
| --------- | -------------------------------------- |
| **2.0.3** | Bug fixes, improved error messages     |
| **2.0.2** | Updated icons to okraPDF branding      |
| **2.0.1** | Brand color updates                    |
| **2.0.0** | Complete rebrand from previous version |

## Privacy

* **No tracking** — We don't track your browsing
* **Minimal permissions** — Only what's needed for capture
* **Secure transfer** — All uploads encrypted

## Next Steps

<Card title="Email Import" icon="envelope" href="/integrations/email-import">
  Forward documents to okraPDF via email
</Card>


# Email Import
Source: https://docs.okrapdf.com/integrations/email-import

Forward PDFs to okraPDF via email for automatic processing

## Overview

No browser, no app? Forward PDF attachments to okraPDF by email. We'll process them automatically and add them to your library.

<Frame>
  <video />
</Frame>

<Info>
  **Works from any device.** Forward from your phone, tablet, or any email client.
</Info>

## How It Works

```mermaid theme={null}
flowchart LR
    A[Your Email] --> B[Forward to<br/>ingest@okrapdf.com]
    B --> C[Attachments<br/>Extracted]
    C --> D[OCR<br/>Processing]
    D --> E[Your Library]
    E --> F[Confirmation<br/>Email]

    style A fill:#1e293b,color:#f8fafc,stroke:#475569
    style B fill:#FFE01B,color:#1e293b,stroke:#E6C800
    style C fill:#0ea5e9,color:#fff,stroke:#0284c7
    style D fill:#0ea5e9,color:#fff,stroke:#0284c7
    style E fill:#16a34a,color:#fff,stroke:#15803d
    style F fill:#16a34a,color:#fff,stroke:#15803d
```

<Steps>
  <Step title="Forward the Email">
    Forward any email with PDF attachments to your personal ingest address
  </Step>

  <Step title="Receive Acknowledgment">
    You'll get an instant confirmation that we received your documents
  </Step>

  <Step title="Processing">
    OCR and extraction run automatically (10-30 seconds for most documents)
  </Step>

  <Step title="Ready to Use">
    Documents appear in your okraPDF library, fully processed
  </Step>
</Steps>

## Your Personal Ingest Address

Every okraPDF account has a unique ingest email address:

```
your-id@ingest.okrapdf.com
```

Find your address in **Settings > Integrations > Email Import**.

<Warning>
  Keep your ingest address private. Anyone with this address can add documents to your library.
</Warning>

## What Gets Processed

| Attachment Type      | Support             |
| -------------------- | ------------------- |
| PDF files            | Full support        |
| Images (PNG, JPG)    | Converted and OCR'd |
| Multiple attachments | All processed       |

<Note>
  Non-PDF, non-image attachments are ignored. The email body text is not imported.
</Note>

## Confirmation Emails

After forwarding, you'll receive:

1. **Acknowledgment** — Immediate confirmation we received your email
2. **Success notification** — When processing completes, with links to your documents
3. **Error notification** — If any attachments fail, with details on what went wrong

## Use Cases

<AccordionGroup>
  <Accordion title="Mobile Capture" icon="mobile">
    Receive a PDF on your phone? Forward it to okraPDF without switching apps.
  </Accordion>

  <Accordion title="Receipts & Invoices" icon="receipt">
    Set up email rules to auto-forward receipts from vendors to your ingest address.
  </Accordion>

  <Accordion title="Team Workflows" icon="users">
    Share your ingest address with team members who need to contribute documents.
  </Accordion>

  <Accordion title="Scanner Integration" icon="scanner">
    Configure your office scanner to email scans directly to okraPDF.
  </Accordion>
</AccordionGroup>

## Email Rules

Automate imports by setting up email rules in Gmail, Outlook, or your email client:

<Tabs>
  <Tab title="Gmail">
    1. Open Gmail Settings > Filters
    2. Create filter: `from:invoices@vendor.com has:attachment`
    3. Action: Forward to your ingest address
  </Tab>

  <Tab title="Outlook">
    1. Rules > New Rule
    2. Condition: From specific sender + Has attachment
    3. Action: Forward to your ingest address
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No confirmation email">
    1. Check your spam folder
    2. Verify you sent to the correct ingest address
    3. Ensure attachments are under 25MB each
  </Accordion>

  <Accordion title="Documents not appearing">
    Processing can take up to 2 minutes for large documents. If still missing:

    1. Check for an error notification email
    2. Verify the attachment was a supported format
  </Accordion>

  <Accordion title="Partial imports">
    If some attachments fail, you'll receive an error email listing which ones and why.
  </Accordion>
</AccordionGroup>

## Limits

| Limit                     | Value               |
| ------------------------- | ------------------- |
| Max attachment size       | 25 MB per file      |
| Max attachments per email | 10 files            |
| Supported formats         | PDF, PNG, JPG, JPEG |

## Security

* **Unique address** — Your ingest address is private to your account
* **Encrypted transfer** — All emails processed over TLS
* **No email storage** — We extract attachments and discard the email

## Next Steps

<Card title="Chrome Extension" icon="chrome" href="/integrations/chrome-extension">
  Capture PDFs from your browser
</Card>


# okraPDF for iPhone & iPad
Source: https://docs.okrapdf.com/ios/overview

A native PDF toolkit for iOS — split, sign, redact, organize, and extract structured data from PDFs, backed by your okraPDF account.

okraPDF for iOS is a native PDF toolkit for iPhone and iPad. On-device tools handle everyday PDF edits; structured extraction runs against the same [okraPDF account](https://app.okrapdf.com) you use from the [CLI](/cli/quickstart) and [API](/api-reference/introduction).

<Note>
  The iOS app is in final App Store review. This page describes the shipping feature set; the download link will go live when the listing is published.
</Note>

## What it does

Open a PDF from Files, Mail, or any app via the share sheet, then run a tool:

<CardGroup>
  <Card title="Edit" icon="pen-to-square">
    Split, merge, rotate, compress, and organize pages.
  </Card>

  <Card title="Sign" icon="signature">
    Add a signature to a PDF on device.
  </Card>

  <Card title="Redact" icon="eye-slash">
    Black out sensitive content before sharing.
  </Card>

  <Card title="Convert" icon="file-import">
    Turn PNG images and spreadsheets into PDFs.
  </Card>

  <Card title="Extract" icon="table-list">
    Pull readable text, tables, and structured fields from a PDF.
  </Card>

  <Card title="Share extension" icon="share-nodes">
    Send a PDF straight from another app into okraPDF.
  </Card>
</CardGroup>

## How it connects

Sign in with your okraPDF account and the app uses your existing credentials — the documents and jobs you create on iOS are the same [Documents](/web/overview) and [Jobs](/cli/jobs) you see on the web, CLI, and API.

* **On-device tools** (split, merge, rotate, sign) run locally and never leave your phone.
* **Extraction** uploads to your account and returns structured data with the same engine as `okra extract`.

<Card title="The web app" icon="rocket" href="https://app.okrapdf.com">
  Manage the same documents and account from any browser.
</Card>


# Use okraPDF with Claude
Source: https://docs.okrapdf.com/mcp/overview

Connect the remote okraPDF MCP server for PDF upload, citation verification, visual review, and document analysis.

## Remote MCP URL

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

okraPDF runs a remote Streamable HTTP MCP server on Cloudflare Workers. It supports OAuth discovery for clients with remote connector support, and API-key headers for clients that prefer explicit bearer tokens.

## Setup

<Tabs>
  <Tab title="Claude Desktop / Claude.ai">
    Add a custom connector with this URL:

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

    Leave OAuth client fields blank. The server advertises discovery metadata and prompts for browser authentication on first use.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add -s user -t http okrapdf https://api.okrapdf.com/mcp
    ```

    If your client asks for headers instead of OAuth, use:

    ```bash theme={null}
    claude mcp add -s user -t http okrapdf https://api.okrapdf.com/mcp \
      --header "Authorization: Bearer $OKRA_API_KEY"
    ```
  </Tab>

  <Tab title="Cursor / Windsurf">
    Add this to your MCP config:

    ```json theme={null}
    {
      "mcpServers": {
        "okrapdf": {
          "type": "http",
          "url": "https://api.okrapdf.com/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Legacy bridge">
    For clients that only support stdio:

    ```json theme={null}
    {
      "mcpServers": {
        "okrapdf": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://api.okrapdf.com/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## What the tools do

| Tool                               | Use it for                                                                                                                                      |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `verify_source`                    | Verify a PDF-backed claim, preferably with page text plus bounding-box evidence. Can work from `document_id` or from `pdf_url` plus page hints. |
| `upload_document`                  | Upload a PDF URL or base64 payload for full parse and live viewer polling.                                                                      |
| `resolve_pdf_url`                  | Resolve a public PDF URL through Okra's URL registry before full-document ingest or visual review.                                              |
| `describe_collection`              | Inspect collection metadata, document list, SQLite schema, and query patterns.                                                                  |
| `execute_code`                     | Run JavaScript over `docs.*`, `sql.*`, and `citation.*` for document or collection analysis.                                                    |
| `view_pdf` / `view_document`       | Open the visual MCP App with page previews and bounding-box overlays.                                                                           |
| `interact`                         | Navigate or highlight inside an already-open visual document viewer.                                                                            |
| `review_extraction`                | Open the bbox extraction review workflow with verify and flag controls.                                                                         |
| `view_structured` / `inspect_html` | Open the parsed HTML/PDFQuery inspector MCP App.                                                                                                |
| `render_ui`                        | Query document data and render charts, tables, metrics, proof cards, or dashboards in an MCP App.                                               |
| `create_view`                      | Render model-authored safe component JSON when the model already has the data.                                                                  |
| `draft_workflow`                   | Author a catalog workflow or dynamic agent workflow script using `agent()` / `parallel()` / `pipeline()` / `phase()`.                           |
| `run_workflow`                     | Start a saved workflow and return the run id/status URL.                                                                                        |
| `view_workflow`                    | Inspect a workflow blueprint, readiness, AST, visualization, finite-definition validation, and static agent analysis.                           |
| `view_workflow_run`                | Inspect run status, controller output, per-agent outputs, events, logs, and failures.                                                           |

## Example prompts

```text theme={null}
Upload this PDF and open the visual viewer:
https://www.irs.gov/pub/irs-pdf/fw9.pdf
```

```text theme={null}
Verify that the vendor total is $12,450 on page 2 and show the proof card.
```

```text theme={null}
Describe my earnings collection, then use execute_code to compare revenue by company.
```

```text theme={null}
Render a dashboard of invoice totals by vendor with source citations.
```

```text theme={null}
Draft a dynamic agent workflow that runs text-layer and VLM extraction in parallel, then uses a judge agent to flag discrepancies.
```

## Citation verification modes

`verify_source` defaults to `verification_requirement: "bbox"`. This means Okra only mints a durable proof link when it can resolve page text and bounding-box coordinates.

Use `verification_requirement: "text_match"` only when a deterministic text match is enough and a visual proof link is not required.

## Upload limits and URL caveats

Direct URLs work best for public PDFs, raw GitHub files, arXiv PDFs, and presigned S3/GCS URLs. Sites with anti-bot protection, login walls, JavaScript rendering, or CAPTCHA can block server-side fetches. For app/API integrations, use `POST /v1/documents` multipart upload instead of asking the MCP server to fetch a protected URL.


# Pricing
Source: https://docs.okrapdf.com/pricing

Pay for what you use. No subscriptions, no commitments.

## Philosophy

okraPDF uses **prepaid credits**. You load your balance, use the product, and only pay for what you consume. Credits never expire. No monthly fees, no plan tiers, no feature gates.

## Rates

| Product                          | Rate                   | Notes                                                             |
| -------------------------------- | ---------------------- | ----------------------------------------------------------------- |
| **Document Processing (OCR)**    | **\$0.02/page**        | Full pipeline: OCR + table extraction + structured output         |
| **AI Document Chat**             | **At actual API cost** | Passthrough from the LLM provider (typically \$0.01-0.05/message) |
| **Export** (CSV, JSON, Markdown) | **Free**               | Included with processing                                          |
| **Storage**                      | **Free**               | Up to 1GB per account                                             |

### What's included per page

Each page processed includes the full extraction pipeline — no per-feature stacking:

* Google Document AI OCR
* Vision model analysis (table/figure detection)
* Structured output (headers, rows, columns preserved)
* Confidence scoring

## Signup Credit

New accounts receive **\$5.00 free credit** — no credit card required. That's approximately **250 pages** of document processing to start.

## Adding Credits

| Parameter      | Value             |
| -------------- | ----------------- |
| Minimum top-up | **\$5**           |
| Presets        | $5, $10, $25, $50 |
| Maximum        | \$500             |
| Processing fee | None              |
| Expiration     | Never             |

Add credits from **Settings** in your dashboard. Payments are one-time via Stripe — no recurring charges.

## Cost Examples

| Document       | Pages | OCR Cost | Chat (10 messages) | Total    |
| -------------- | ----- | -------- | ------------------ | -------- |
| Invoice        | 2     | \$0.04   | \~\$0.20           | \~\$0.24 |
| Contract       | 15    | \$0.30   | \~\$0.30           | \~\$0.60 |
| Annual report  | 50    | \$1.00   | \~\$0.40           | \~\$1.40 |
| Research paper | 30    | \$0.60   | \~\$0.25           | \~\$0.85 |

<Tip>
  Chat costs vary by conversation length and complexity. Simple questions cost less; multi-step analysis costs more. You can always check your balance and spending in Settings.
</Tip>

## Insufficient Balance

When your balance runs low:

* **Upload**: You'll see a prompt to add credits before processing
* **Chat**: The chat input shows a message to add credits
* **Existing documents**: Always accessible — view, export, and download anytime

No blurred overlays, no locked features. Just a prompt to add credits when you need more.

## FAQ

<AccordionGroup>
  <Accordion title="Do credits expire?" icon="clock">
    No. Credits never expire. Use them whenever you need to.
  </Accordion>

  <Accordion title="Is there a free trial?" icon="gift">
    Every new account gets **\$5 free credit** (\~250 pages). No credit card required.
  </Accordion>

  <Accordion title="Why passthrough pricing for chat?" icon="comments">
    Chat costs vary significantly based on conversation length and complexity. Rather than overcharging simple questions or undercharging complex ones, we pass through the exact API cost. This keeps pricing transparent and fair.
  </Accordion>

  <Accordion title="Can I get a refund?" icon="rotate-left">
    If a document fails to process, the charge is automatically refunded to your balance. For other refund requests, contact [support@okrapdf.com](mailto:support@okrapdf.com).
  </Accordion>

  <Accordion title="Do you offer volume pricing?" icon="building">
    For high-volume needs (10,000+ pages/month), contact us at [support@okrapdf.com](mailto:support@okrapdf.com) for custom pricing.
  </Accordion>
</AccordionGroup>


# Package Versions
Source: https://docs.okrapdf.com/versions

Latest published versions of okraPDF packages

<Info>Auto-generated by CI on package publish. Last updated **2026-05-29**.</Info>

| Package                                  | Version  | Install                    |
| ---------------------------------------- | -------- | -------------------------- |
| **API** (`api.okrapdf.com`)              | `1.14.0` | -                          |
| **SDK + CLI** (`@okrapdf/sdk`)           | `0.14.5` | `npm i @okrapdf/sdk`       |
| **React subpath** (`@okrapdf/sdk/react`) | `0.14.5` | included in `@okrapdf/sdk` |

## Compatibility Matrix

The SDK package, CLI binary, and React subpath are published together from `@okrapdf/sdk`.

| SDK package | CLI binary | React subpath        | API    |
| ----------- | ---------- | -------------------- | ------ |
| 0.14.5      | `okra`     | `@okrapdf/sdk/react` | 1.14.0 |

## Changelog

* [SDK and CLI releases](https://github.com/okrapdf/okrapdf-sdk/releases)


# The okraPDF Web App
Source: https://docs.okrapdf.com/web/overview

app.okrapdf.com is the visual view of the same resources the CLI, API, and MCP expose — Documents, Files, Jobs, Collections, and more.

The web app at [app.okrapdf.com](https://app.okrapdf.com) is a visual surface over the **same resources** the [CLI](/cli/quickstart), [API](/api-reference/introduction), and [MCP server](/mcp/overview) work with. Every noun in the sidebar maps to a resource you can also drive from a script or an agent — uploading a PDF in the browser and uploading it with `okra upload` create the same document.

<Note>
  Sign in with your okraPDF account. The same API key you use for the CLI and API is managed under **Settings → API Keys**.
</Note>

## Workspace

The left sidebar mirrors the resource nouns one-to-one:

<CardGroup>
  <Card title="Documents" icon="file-lines" href="https://app.okrapdf.com/documents">
    Processed PDFs with markdown, page images, extracted tables, chat, and citations. The equivalent of `okra documents` and `GET /v1/documents`.
  </Card>

  <Card title="Files" icon="copy" href="https://app.okrapdf.com/files">
    Raw uploaded file assets that haven't been turned into a processed document. Maps to `okra files` and `/v1/files`.
  </Card>

  <Card title="Jobs" icon="bars-progress" href="https://app.okrapdf.com/jobs">
    Parse, render, and workflow jobs with live status and results. Maps to `okra jobs` and `/v1/jobs`.
  </Card>

  <Card title="Collections" icon="layer-group" href="https://app.okrapdf.com/collections">
    Group documents and ask one question across all of them. Maps to `okra collections` and `/v1/collections`.
  </Card>

  <Card title="Tables" icon="table" href="https://app.okrapdf.com/tables">
    Materialized extraction tables built from your documents.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="https://app.okrapdf.com/workflows">
    Multi-step runs such as accessibility/compliance audits, with run history.
  </Card>
</CardGroup>

## Settings

[**Settings**](https://app.okrapdf.com/settings) is where you manage your account and the credentials the other platforms use:

* **API Keys** — mint and revoke `okra_*` keys for the [CLI](/cli/reference) and [API](/api-reference/authentication).
* **Vendor Keys** — store your own Anthropic / OpenAI / Google keys to run extraction on [your own model](/mcp/overview#use-your-own-api-key-direct-provider).
* **Webhooks** — subscribe to document and job events. See [Webhooks](/api-reference/webhooks).

## One resource, every surface

The web app is never the only way to do something — it's the human-friendly view of an agent-first platform.

| Resource           | Web              | CLI                                   | API                                        |
| ------------------ | ---------------- | ------------------------------------- | ------------------------------------------ |
| Upload a PDF       | drag-and-drop    | `okra upload <source>`                | `POST /v1/documents`                       |
| Read a document    | open it          | `okra read <docId>`                   | `GET /v1/documents/{id}/full.md`           |
| Ask a question     | chat panel       | `okra chat "<q>" --doc <id>`          | `POST /v1/documents/{id}/chat/completions` |
| Query a collection | Collections page | `okra collections query <name> "<q>"` | `POST /v1/collections/{id}/query`          |

<Card title="Open the app" icon="rocket" href="https://app.okrapdf.com/documents">
  Sign in and upload your first PDF.
</Card>