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

# Overview

> Complete reference for all Pulse API endpoints

## Base URL

All API requests should be made to:

```
https://api.runpulse.com
```

## Authentication

All endpoints require authentication via API key in the request header (agents without an account can instead [pay per request over MPP](/advanced/mpp-payments)):

```
x-api-key: YOUR_API_KEY
```

Get your API key from the [Pulse Platform](https://platform.runpulse.com/).

## Available Endpoints

### Pipeline Steps

<CardGroup cols={2}>
  <Card title="Classify" icon="route" href="/api-reference/endpoint/classify">
    **POST** `/classify`

    Cheaply classify a raw document and get the `pipeline_id` to route it to — before extracting.
  </Card>

  <Card title="Extract" icon="file-lines" href="/api-reference/endpoint/extract">
    **POST** `/extract`

    Parse documents into markdown, layout, figures, chunks, tables, and an `extraction_id`.
  </Card>

  <Card title="Schema" icon="brackets-curly" href="/api-reference/endpoint/schema">
    **POST** `/schema`

    Apply schemas to extract structured JSON from one extraction, many extractions, or split topics.
  </Card>

  <Card title="Tables" icon="table" href="/api-reference/endpoint/tables">
    **POST** `/tables`

    Extract table-first output with span handling, cross-page merging, and chart-to-table conversion.
  </Card>

  <Card title="Split" icon="scissors" href="/api-reference/endpoint/split">
    **POST** `/split`

    Split a document into topic-based page groups for routing or per-topic downstream steps.
  </Card>
</CardGroup>

### Batch Processing

<CardGroup cols={1}>
  <Card title="Batch Processing" icon="layer-group" href="/api-reference/endpoint/batch-overview">
    **POST** `/batch/extract`, `/batch/schema`, `/batch/tables`, `/batch/split`

    Run a workflow across many documents.
  </Card>
</CardGroup>

### Forms

<CardGroup cols={2}>
  <Card title="Fill Form" icon="pen-to-square" href="/api-reference/endpoint/form-fill">
    **POST** `/form/fill`

    Fill a PDF form from natural-language instructions, or run layout-only OCR on form cells.
  </Card>

  <Card title="Clear Form" icon="eraser" href="/api-reference/endpoint/form-clear">
    **POST** `/form/clear`

    Strip user-filled values from a PDF while preserving the printed template.
  </Card>
</CardGroup>

### Jobs, Results & Webhooks

<CardGroup cols={2}>
  <Card title="Poll Job" icon="magnifying-glass" href="/api-reference/endpoint/poll">
    **GET** `/job/{jobId}`

    Check status and retrieve results of async jobs.
  </Card>

  <Card title="Cancel Job" icon="xmark" href="/api-reference/endpoint/delete-job">
    **DELETE** `/job/{jobId}`

    Cancel a pending or processing async job.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/endpoint/webhook">
    **POST** `/webhook`

    Get portal link to configure webhook endpoints.
  </Card>

  <Card title="Large Results" icon="file-arrow-down" href="/api-reference/endpoint/large-results">
    **GET** `/results/{jobId}`

    Download a completed result that is too large for inline job responses.
  </Card>

  <Card title="Result Images" icon="image" href="/api-reference/endpoint/results-image">
    **GET** `/results/{jobId}/images/{filename}`

    Download visual assets emitted by extraction.
  </Card>

  <Card title="Result PDFs" icon="file-pdf" href="/api-reference/endpoint/results-pdf">
    **GET** `/results/{jobId}/pdf`

    Download PDFs produced by form workflows.
  </Card>

  <Card title="Async Processing" icon="clock" href="/api-reference/async-processing">
    Guide to using `async: true` and polling for results.
  </Card>
</CardGroup>

### Account & Usage

<CardGroup cols={2}>
  <Card title="Get Usage" icon="chart-line" href="/api-reference/endpoint/usage">
    **GET** `/usage`

    Billing-period credit status plus document, page, and credit totals with a day/week/month timeline.
  </Card>
</CardGroup>

### Deprecated Endpoints

<Warning>
  The following endpoints are deprecated and will be removed in a future version.
</Warning>

| Endpoint                | Status     | Replacement                                    |
| ----------------------- | ---------- | ---------------------------------------------- |
| `POST /extract_async`   | Deprecated | Use `POST /extract` with `async: true` instead |
| `POST /convert`         | Deprecated | Use `file_url` parameter in `/extract` instead |
| `POST /cancel/{job_id}` | Deprecated | Use `DELETE /job/{jobId}` instead              |
| `POST /split-schema`    | Deprecated | Use `POST /schema` with `split_id` instead     |

## Credit Usage

Pulse bills in **credits**. Each pipeline step is billed based on the pages (or tables) processed.

| Endpoint                            | Cost                 | Formula                        |
| ----------------------------------- | -------------------- | ------------------------------ |
| `/classify`                         | 0.5 credits / page   | `pages × 0.5`                  |
| `/extract` (`model: default`)       | 1 credit / page      | `pages × 1`                    |
| `/extract` (`model: pulse-ultra-2`) | 10 credits / page    | `pages × 10`                   |
| `/split`                            | 2 credits / page     | `pages × 2`                    |
| `/schema`                           | 1 credit / page      | `pages × 1`                    |
| `/schema` (`effort: true`)          | 4 credits / page     | `pages × 4`                    |
| `/tables`                           | 0.25 credits / table | `tables × 0.25`                |
| `/tables` (`merge: true`)           | 0.50 credits / table | `tables × 0.5`                 |
| `/tables` (charts)                  | +1 credit / chart    | added on top of the table cost |
| `/form/detect`                      | 1 credit / page      | `pages × 1`                    |
| `/form/fill`                        | 3 credits / page     | `pages × 3`                    |
| `/form/clear`                       | 3 credits / page     | `pages × 3`                    |

<Note>
  `/classify` bills only the pages in the effective `page_range` (default: first 5 pages) for PDFs and images. Office/HTML files are billed for every page.
</Note>

<Note>
  API keys can have per-key credit caps configured. Requests that would exceed a key's cap are rejected before processing.
</Note>

Track consumption against your plan programmatically with [`GET /usage`](/api-reference/endpoint/usage).

## Status Codes

| Code | Description                            |
| ---- | -------------------------------------- |
| 200  | Success                                |
| 400  | Bad Request - Invalid parameters       |
| 401  | Unauthorized - Invalid API key         |
| 403  | Forbidden - Access denied              |
| 404  | Not Found - Resource doesn't exist     |
| 413  | Payload Too Large - File exceeds limit |
| 429  | Too Many Requests - Rate limited       |
| 500  | Internal Server Error                  |
| 503  | Service Unavailable                    |

## Best Practices

<AccordionGroup>
  <Accordion title="Use Appropriate Endpoints">
    * Use `/extract` for all extractions — it's the primary endpoint
    * Set `async: true` for large documents or batch processing
    * Use `file_url` parameter when you have documents hosted online
    * Use `/schema` for named JSON fields, `/tables` for table-first output, and `/split` for topic routing
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    * Implement retry logic with exponential backoff
    * Check error codes and handle specifically
    * Log errors for debugging
  </Accordion>

  <Accordion title="Optimize Performance">
    * Process only necessary pages
    * Use schemas for structured extraction
    * Cache results when possible
  </Accordion>

  <Accordion title="Security">
    * Never expose API keys in client code
    * Use environment variables
    * Rotate keys regularly
    * Validate file types before upload
  </Accordion>
</AccordionGroup>

## Next Steps

Explore specific endpoints:

<CardGroup cols={2}>
  <Card title="Pipeline Overview" icon="diagram-project" href="/api-reference/endpoint/pipeline-overview">
    Learn how extract, schema, tables, and split work together
  </Card>

  <Card title="API Quickstart" icon="rocket" href="/quickstart">
    Get started quickly
  </Card>
</CardGroup>