The DocloClient is the main entry point for interacting with Doclo Cloud. It provides methods for executing flows, managing runs, and handling authentication.
Installation
Initialization
import { DocloClient } from '@doclo/client';
const client = new DocloClient({
apiKey: process.env.DOCLO_API_KEY!
});
Configuration Options
| Option | Type | Default | Description |
|---|
apiKey | string | Required | API key (dc_live_... or dc_test_...) |
baseUrl | string | https://app.doclo.ai | Base URL for the API |
convexUrl | string | Same as baseUrl | URL for Convex data operations |
timeout | number | 300000 | Request timeout in ms (5 minutes) |
const client = new DocloClient({
apiKey: process.env.DOCLO_API_KEY!,
timeout: 60000 // 1 minute timeout
});
API keys must be at least 50 characters and start with dc_live_ (production) or dc_test_ (test mode). Production keys cannot be used with localhost or private IP addresses.
Resources
The client exposes several resource namespaces:
| Resource | Description |
|---|
client.flows | Execute flows and retrieve flow information |
client.runs | Get execution status, poll for completion, cancel runs |
client.definitions | Flow definitions for local/hybrid execution |
client.prompts | Prompt assets management |
client.schemas | Schema assets management |
client.assets | Flow assets bundles |
client.observability | Observability event ingestion |
The definitions, prompts, schemas, assets, and observability resources are used for advanced hybrid execution and asset management. See Hybrid Client for details. Flows Resource
flows.run(flowId, options)
Execute a flow with a document.
const result = await client.flows.run<InvoiceOutput>('flow_abc123', {
input: {
document: {
base64: '...',
filename: 'invoice.pdf',
mimeType: 'application/pdf'
},
variables: {
extractLineItems: true
}
},
wait: true,
timeout: 60000
});
| Option | Type | Description |
|---|
input.document.base64 | string | Base64-encoded document content |
input.document.filename | string | Original filename |
input.document.mimeType | string | MIME type (application/pdf, image/png, etc.) |
input.variables | object | Optional variables to pass to the flow |
wait | boolean | Wait for completion before returning |
timeout | number | Timeout for sync mode in ms (default: 30000) |
webhookUrl | string | URL to receive completion notification |
metadata | object | Custom metadata to attach |
idempotencyKey | string | Prevent duplicate executions |
version | string | Specific flow version to run |
Execution<T>
flows.list(options?)
List flows available in your organization.
const flows = await client.flows.list({ limit: 20 });
for (const flow of flows.data) {
console.log(flow.id, flow.name);
}
// Pagination
if (flows.hasMore) {
const nextPage = await client.flows.list({ cursor: flows.nextCursor });
}
| Option | Type | Description |
|---|
limit | number | Max items to return (default: 20, max: 100) |
cursor | string | Cursor from previous response |
PaginatedResponse<FlowInfo>
flows.get(flowId, version?)
Get information about a specific flow.
const flow = await client.flows.get('flow_abc123');
console.log(flow.name);
console.log(flow.inputSchema); // JSON Schema for required input
FlowInfo
Runs Resource
runs.get(executionId)
Get the current status and result of an execution.
const execution = await client.runs.get<InvoiceOutput>('exec_abc123');
switch (execution.status) {
case 'queued':
case 'running':
console.log('Still processing...');
break;
case 'success':
console.log('Output:', execution.output);
break;
case 'failed':
console.error('Error:', execution.error?.message);
break;
case 'cancelled':
console.log('Execution was cancelled');
break;
}
Execution<T>
runs.waitForCompletion(executionId, options?)
Poll until an execution completes.
const result = await client.runs.waitForCompletion('exec_abc123', {
interval: 2000, // Poll every 2 seconds
timeout: 300000 // Wait up to 5 minutes
});
console.log('Final status:', result.status);
console.log('Output:', result.output);
| Option | Type | Default | Description |
|---|
interval | number | 1000 | Polling interval in ms |
timeout | number | 300000 | Max wait time in ms |
Execution<T>
Throws: TimeoutError if execution doesn’t complete within timeout.
runs.cancel(executionId)
Cancel a running execution.
await client.runs.cancel('exec_abc123');
Types
Execution
The result of a flow execution:
interface Execution<T = unknown> {
id: string; // Unique execution ID
flowId: string; // Flow that was executed
status: ExecutionStatus; // Current status
createdAt: string; // When execution started
completedAt?: string; // When execution finished
duration?: number; // Duration in ms
output?: T; // Extracted data (if successful)
metrics?: ExecutionMetrics; // Usage metrics
traceId?: string; // Distributed tracing ID
metadata?: Record<string, unknown>;
error?: {
code: string;
message: string;
details?: Record<string, unknown>;
};
}
type ExecutionStatus =
| 'queued'
| 'running'
| 'success'
| 'failed'
| 'cancelled';
interface ExecutionMetrics {
tokensUsed: number;
cost: number;
stepsRun: number;
stepsTotal: number;
}
FlowInfo
Information about a flow:
interface FlowInfo {
id: string;
name: string;
description?: string;
inputSchema?: object; // JSON Schema for variables
version: string;
createdAt: string;
updatedAt: string;
}
interface DocumentInput {
base64: string; // Base64-encoded content
filename: string; // Original filename
mimeType: string; // MIME type
}
Properties
client.isTestMode
Check if using a test API key:
if (client.isTestMode) {
console.log('Running in test mode');
}
Next Steps
