API Overview

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.

For TypeScript/JavaScript applications, the @doclo/client SDK provides a better developer experience with type safety and automatic retries.

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:

Authorization: Bearer dc_live_your_api_key

See Authentication for details on API key formats and scopes.

Request Format

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

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:

{
  "id": "exec_abc123",
  "status": "completed",
  "output": { ... }
}

Error responses include an error object:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Document base64 data is required"
  }
}

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

{
  "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	List available flows
GET	/flows/	Get flow details
POST	/flows//run	Execute a flow

Executions

Method	Endpoint	Description
GET	/runs/	Get execution status
POST	/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:

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

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:

{
  "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 for implementation details.

Idempotency

Include an idempotencyKey to safely retry requests:

{
  "idempotencyKey": "unique-request-id-12345",
  "input": { ... }
}

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

Overview

Flows

Runs

API Overview

Base URL

Authentication

Request Format

Response Format

Rate Limiting

Credits

Endpoints

Flows

Executions

Sync vs Async Execution

Webhooks

Idempotency

Next Steps

Authentication

Run Flow

​Base URL

​Authentication

​Request Format

​Response Format

​Rate Limiting

​Credits

​Endpoints

​Flows

​Executions

​Sync vs Async Execution

​Webhooks

​Idempotency

​Next Steps

Authentication

Run Flow

Base URL

Authentication

Request Format

Response Format

Rate Limiting

Credits

Endpoints

Flows

Executions

Sync vs Async Execution

Webhooks

Idempotency

Next Steps