Execute document processing flows on Doclo Cloud without managing infrastructure.
Prerequisites
A Doclo Cloud account with API key
A registered flow in your Doclo Cloud dashboard
Installation
Install the Doclo client package:
Get Your API Key
Navigate to API Keys
Open Settings → API Keys in the dashboard.
Create a new key
Click “Create API Key”, give it a name, and copy the generated key.API keys use the format dc_live_... for production or dc_test_... for testing.
Store securely
Add the key to your environment:# .env.local
DOCLO_API_KEY=dc_live_your-key-here
Initialize the Client
import 'dotenv/config';
import { DocloClient } from '@doclo/client';
const client = new DocloClient({
apiKey: process.env.DOCLO_API_KEY!
});
Execute a Flow
Synchronous Execution
For quick processing with immediate results, use wait: true:
import fs from 'fs';
// Prepare the document
const fileBuffer = fs.readFileSync('./invoice.pdf');
const base64 = fileBuffer.toString('base64');
// Execute flow and wait for result
const result = await client.flows.run('flow_abc123', {
input: {
document: {
base64,
filename: 'invoice.pdf',
mimeType: 'application/pdf'
}
},
wait: true,
timeout: 60000 // Wait up to 60 seconds
});
console.log('Extracted data:', result.output);
Asynchronous Execution
For large documents or background processing, omit wait and use webhooks or polling:
// Start execution without waiting
const execution = await client.flows.run('flow_abc123', {
input: {
document: {
base64,
filename: 'invoice.pdf',
mimeType: 'application/pdf'
}
},
webhookUrl: 'https://your-app.com/webhook' // Optional
});
console.log('Execution started:', execution.id);
console.log('Status:', execution.status); // 'queued' or 'running'
// Poll for completion
const result = await client.runs.waitForCompletion(execution.id, {
interval: 2000, // Poll every 2 seconds
timeout: 300000 // Wait up to 5 minutes
});
console.log('Result:', result.output);
Complete Example
import 'dotenv/config';
import { DocloClient, NotFoundError, RateLimitError } from '@doclo/client';
import fs from 'fs';
async function processInvoice(pdfPath: string) {
// Initialize client
const client = new DocloClient({
apiKey: process.env.DOCLO_API_KEY!
});
// Read and encode file
const fileBuffer = fs.readFileSync(pdfPath);
const base64 = fileBuffer.toString('base64');
const filename = pdfPath.split('/').pop() ?? 'document.pdf';
// Execute flow
const result = await client.flows.run(process.env.DOCLO_FLOW_ID!, {
input: {
document: {
base64,
filename,
mimeType: 'application/pdf'
}
},
wait: true,
timeout: 60000
});
// Handle result
if (result.status === 'success') {
console.log('Extracted data:', JSON.stringify(result.output, null, 2));
console.log('Tokens used:', result.metrics?.tokensUsed);
console.log('Cost:', `$${result.metrics?.cost.toFixed(4)}`);
} else if (result.status === 'failed') {
console.error('Extraction failed:', result.error?.message);
}
return result;
}
processInvoice('./invoice.pdf').catch(console.error);
Error Handling
The client provides typed error classes for common failure scenarios:
import {
DocloClient,
DocloError,
AuthenticationError,
NotFoundError,
RateLimitError,
ValidationError
} 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) {
console.error('Invalid API key');
} else if (error instanceof NotFoundError) {
console.error('Flow does not exist');
} else if (error instanceof RateLimitError) {
console.error('Too many requests');
console.error('Retry after:', error.rateLimitInfo?.retryAfter, 'seconds');
} else if (error instanceof ValidationError) {
console.error('Invalid input:', error.message);
} else if (error instanceof DocloError) {
console.error('Error:', error.code, error.message);
}
}
Next Steps
