Skip to main content
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:
HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix 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

MethodEndpointDescription
GET/flowsList available flows
GET/flows/Get flow details
POST/flows//runExecute a flow

​
Executions

MethodEndpointDescription
GET/runs/Get execution status
POST/runs//cancelCancel 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.

​
Next Steps

Authentication

API keys and scopes

Run Flow

Execute document processing