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.
Learn how to execute document processing flows on Doclo Cloud, with options for synchronous and asynchronous processing.
Execution Modes
Doclo Cloud supports two execution modes:
| Mode | Use Case | How |
|---|
| Synchronous | Small documents, immediate response needed | Set wait: true |
| Asynchronous | Large documents, background processing | Omit wait, use webhooks or polling |
Synchronous Execution
Wait for the flow to complete before returning:
const result = await client.flows.run('flow_abc123', {
input: {
document: {
base64: documentBase64,
filename: 'invoice.pdf',
mimeType: 'application/pdf'
}
},
wait: true,
timeout: 60000 // Wait up to 60 seconds
});
// Result is immediately available
console.log('Output:', result.output);
console.log('Status:', result.status); // 'success' or 'failed'
Timeout Configuration
| Option | Default | Description |
|---|
timeout | 30000 | Max time to wait for sync execution (ms) |
If the flow takes longer than the timeout, a TimeoutError is thrown. The execution continues in the background—use runs.get() to check status.
Asynchronous Execution
Start execution and retrieve results later:
// Start execution
const execution = await client.flows.run('flow_abc123', {
input: {
document: {
base64: documentBase64,
filename: 'invoice.pdf',
mimeType: 'application/pdf'
}
}
// No 'wait' option - returns immediately
});
console.log('Execution ID:', execution.id);
console.log('Status:', execution.status); // 'queued' or 'running'
- Polling - check status periodically
- Webhooks - receive notification when complete
Every flow execution requires a document input:
interface FlowRunInput {
document: {
base64: string; // Base64-encoded content
filename: string; // Original filename
mimeType: string; // MIME type
};
variables?: Record<string, unknown>; // Optional flow variables
}
Supported MIME Types
| Format | MIME Type |
|---|
| PDF | application/pdf |
| JPEG | image/jpeg |
| PNG | image/png |
| WebP | image/webp |
| TIFF | image/tiff |
Flow Variables
Pass variables to customize flow behavior:
const result = await client.flows.run('flow_abc123', {
input: {
document: { base64, filename, mimeType: 'application/pdf' },
variables: {
extractLineItems: true,
currency: 'USD',
language: 'en'
}
},
wait: true
});
inputSchema for required variables:
const flow = await client.flows.get('flow_abc123');
console.log('Required variables:', flow.inputSchema);
Execution Options
| Option | Type | Description |
|---|
input | FlowRunInput | Document and variables (required) |
wait | boolean | Wait for completion |
timeout | number | Sync mode timeout in ms |
webhookUrl | string | URL for completion notification |
metadata | object | Custom metadata to attach |
idempotencyKey | string | Prevent duplicate executions |
version | string | Specific flow version |
Idempotency
Prevent duplicate processing by providing an idempotency key:
const result = await client.flows.run('flow_abc123', {
input: { document: { base64, filename, mimeType: 'application/pdf' } },
idempotencyKey: `invoice-${invoiceId}`,
wait: true
});
const result = await client.flows.run('flow_abc123', {
input: { document: { base64, filename, mimeType: 'application/pdf' } },
metadata: {
customerId: 'cust_123',
source: 'email-inbox',
priority: 'high'
},
wait: true
});
// Metadata is returned with the execution
console.log(result.metadata); // { customerId: 'cust_123', ... }
Flow Versions
Run a specific flow version:
const result = await client.flows.run('flow_abc123', {
input: { document: { base64, filename, mimeType: 'application/pdf' } },
version: '1.2.0',
wait: true
});
Error Handling
import {
DocloClient,
AuthenticationError,
NotFoundError,
ValidationError,
RateLimitError,
TimeoutError,
ExecutionError
} from '@doclo/client';
try {
const result = await client.flows.run('flow_abc123', {
input: { document: { base64, filename, mimeType: 'application/pdf' } },
wait: true
});
} catch (error) {
if (error instanceof AuthenticationError) {
// Invalid or expired API key
console.error('Authentication failed:', error.message);
} else if (error instanceof NotFoundError) {
// Flow doesn't exist
console.error('Flow not found:', error.message);
} else if (error instanceof ValidationError) {
// Invalid input (missing required variables, bad document format)
console.error('Validation error:', error.message, error.details);
} else if (error instanceof RateLimitError) {
// Too many requests
console.error('Rate limited, retry after:', error.rateLimitInfo?.retryAfter);
} else if (error instanceof TimeoutError) {
// Sync execution timed out (execution continues in background)
console.error('Timeout:', error.message);
} else if (error instanceof ExecutionError) {
// Flow execution failed
console.error('Execution failed:', error.code, error.message);
}
}
Execution Failures
When an execution fails, the error field contains details:
const result = await client.flows.run('flow_abc123', {
input: { document: { base64, filename, mimeType: 'application/pdf' } },
wait: true
});
if (result.status === 'failed') {
console.error('Error code:', result.error?.code);
console.error('Error message:', result.error?.message);
console.error('Error details:', result.error?.details);
}
| Code | Description |
|---|
EXECUTION_FAILED | General execution failure |
EXECUTION_TIMEOUT | Execution exceeded time limit |
PROVIDER_ERROR | LLM/OCR provider failed |
PROVIDER_RATE_LIMITED | Provider rate limit exceeded |
INVALID_INPUT | Document couldn’t be processed |
Next Steps
Polling Results
Check execution status
Webhooks
Receive completion notifications
