Skip to main content
The DocloClient is the main entry point for interacting with Doclo Cloud. It provides methods for executing flows, managing runs, and handling authentication.

​
Installation

pnpm add @doclo/client

​
Initialization

import { DocloClient } from '@doclo/client';

const client = new DocloClient({
  apiKey: process.env.DOCLO_API_KEY!
});

​
Configuration Options

OptionTypeDefaultDescription
apiKeystringRequiredAPI key (dc_live_... or dc_test_...)
baseUrlstringhttps://app.doclo.aiBase URL for the API
convexUrlstringSame as baseUrlURL for Convex data operations
timeoutnumber300000Request 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:
ResourceDescription
client.flowsExecute flows and retrieve flow information
client.runsGet execution status, poll for completion, cancel runs
client.definitionsFlow definitions for local/hybrid execution
client.promptsPrompt assets management
client.schemasSchema assets management
client.assetsFlow assets bundles
client.observabilityObservability 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
});
Parameters:
OptionTypeDescription
input.document.base64stringBase64-encoded document content
input.document.filenamestringOriginal filename
input.document.mimeTypestringMIME type (application/pdf, image/png, etc.)
input.variablesobjectOptional variables to pass to the flow
waitbooleanWait for completion before returning
timeoutnumberTimeout for sync mode in ms (default: 30000)
webhookUrlstringURL to receive completion notification
metadataobjectCustom metadata to attach
idempotencyKeystringPrevent duplicate executions
versionstringSpecific flow version to run
Returns: 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 });
}
Parameters:
OptionTypeDescription
limitnumberMax items to return (default: 20, max: 100)
cursorstringCursor from previous response
Returns: 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
Returns: 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;
}
Returns: 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);
Parameters:
OptionTypeDefaultDescription
intervalnumber1000Polling interval in ms
timeoutnumber300000Max wait time in ms
Returns: 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;
}

​
DocumentInput

Document input structure: 
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

Error Handling

Handle errors gracefully

Webhooks

Receive completion notifications