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

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

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

## Available Endpoints

### Pipeline Steps

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

    Extract content from documents. Supports sync and async via `async: true`.
  </Card>

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

    Split a document into topic-based page groups.
  </Card>

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

    Apply schemas to extract structured JSON data.
  </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>

### Utilities

<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="Async Processing" icon="clock" href="/api-reference/async-processing">
    Guide to using `async: true` and polling for results.
  </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              |

## Credit Usage

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

| Endpoint                            | Cost                 | Formula                        |
| ----------------------------------- | -------------------- | ------------------------------ |
| `/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>
  API keys can have per-key credit caps configured. Requests that would exceed a key's cap are rejected before processing.
</Note>

## 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
  </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, split, and schema work together
  </Card>

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