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

# API Overview

> Doclo Cloud REST API reference

The Doclo Cloud API provides programmatic access to document processing flows. Use the REST API directly when building integrations with platforms like n8n, Zapier, or custom backends.

<Note>
  For TypeScript/JavaScript applications, the [@doclo/client](/cloud/client) SDK provides a better developer experience with type safety and automatic retries.
</Note>

## Base URL

```
https://app.doclo.ai/api/v1
```

All API endpoints are prefixed with `/api/v1`. Use HTTPS for all requests.

## Authentication

Include your API key in the `Authorization` header:

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

See [Authentication](/api-reference/authentication) for details on API key formats and scopes.

## Request Format

All request bodies must be JSON with the `Content-Type: application/json` header:

```bash theme={null}
curl -X POST https://app.doclo.ai/api/v1/flows/invoice-extractor/run \
  -H "Authorization: Bearer dc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "document": {
        "base64": "data:application/pdf;base64,..."
      }
    }
  }'
```

## Response Format

All responses are JSON. Successful responses include the requested data:

```json theme={null}
{
  "id": "exec_abc123",
  "status": "completed",
  "output": { ... }
}
```

Error responses include an error object:

```json theme={null}
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Document base64 data is required"
  }
}
```

See [Errors](/api-reference/errors) for all error codes.

## Rate Limiting

API requests are rate-limited per organization. Rate limit information is included in response headers:

| Header                  | Description                           |
| ----------------------- | ------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window           |
| `X-RateLimit-Remaining` | Requests remaining in current window  |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets |

When rate limited, you'll receive a `429 Too Many Requests` response. Implement exponential backoff for retries.

## Credits

Document processing consumes credits based on page count and flow complexity. Credit information is included in execution responses:

```json theme={null}
{
  "id": "exec_abc123",
  "metrics": {
    "creditsUsed": 5,
    "pageCount": 3
  }
}
```

If you have insufficient credits, you'll receive a `402 Payment Required` response.

## Endpoints

### Flows

| Method | Endpoint                                        | Description          |
| ------ | ----------------------------------------------- | -------------------- |
| GET    | [/flows](/api-reference/flows/list)             | List available flows |
| GET    | [/flows/{flowId}](/api-reference/flows/get)     | Get flow details     |
| POST   | [/flows/{flowId}/run](/api-reference/flows/run) | Execute a flow       |

### Executions

| Method | Endpoint                                                 | Description          |
| ------ | -------------------------------------------------------- | -------------------- |
| GET    | [/runs/{executionId}](/api-reference/runs/get)           | Get execution status |
| POST   | [/runs/{executionId}/cancel](/api-reference/runs/cancel) | Cancel execution     |

## Sync vs Async Execution

By default, flow execution is asynchronous. The API returns immediately with an execution ID, and you poll for results:

```bash theme={null}
# Start async execution
POST /flows/invoice-extractor/run
# Returns: { "id": "exec_abc123", "status": "pending" }

# Poll for results
GET /runs/exec_abc123
# Returns: { "id": "exec_abc123", "status": "completed", "output": {...} }
```

For faster documents, use synchronous execution with `wait: true`:

```bash theme={null}
POST /flows/invoice-extractor/run
{
  "wait": true,
  "timeout": 30000,
  "input": { ... }
}
# Returns completed result directly (or times out after 30s)
```

Sync execution has a maximum timeout of 60 seconds. For longer documents, use async execution with polling or webhooks.

## Webhooks

Instead of polling, configure a webhook to receive results:

```json theme={null}
{
  "webhookUrl": "https://your-server.com/webhook",
  "webhookSecret": "your_secret_key",
  "input": { ... }
}
```

The webhook receives a POST request with the execution result. Verify the `X-Doclo-Signature` header using HMAC-SHA256. See [Webhooks](/cloud/webhooks) for implementation details.

## Idempotency

Include an `idempotencyKey` to safely retry requests:

```json theme={null}
{
  "idempotencyKey": "unique-request-id-12345",
  "input": { ... }
}
```

Requests with the same idempotency key return the same execution ID within 24 hours, preventing duplicate processing.

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API keys and scopes
  </Card>

  <Card title="Run Flow" icon="play" href="/api-reference/flows/run">
    Execute document processing
  </Card>
</CardGroup>