DocloClient

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

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
});

Parameters:

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

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:

Option	Type	Description
`limit`	`number`	Max items to return (default: 20, max: 100)
`cursor`	`string`	Cursor 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:

Option	Type	Default	Description
`interval`	`number`	`1000`	Polling interval in ms
`timeout`	`number`	`300000`	Max 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');
}

Getting Started

Concepts

SDK

Doclo Cloud

Guides

Resources

Installation

Initialization

Configuration Options

Resources

Flows Resource

`flows.run(flowId, options)`

`flows.list(options?)`

`flows.get(flowId, version?)`

Runs Resource

`runs.get(executionId)`

`runs.waitForCompletion(executionId, options?)`

`runs.cancel(executionId)`

Types

Execution

FlowInfo

DocumentInput

Properties

`client.isTestMode`

Next Steps

Error Handling

Webhooks

​Installation

​Initialization

​Configuration Options

​Resources

​Flows Resource

​flows.run(flowId, options)

​flows.list(options?)

​flows.get(flowId, version?)

​Runs Resource

​runs.get(executionId)

​runs.waitForCompletion(executionId, options?)

​runs.cancel(executionId)

​Types

​Execution

​FlowInfo

​DocumentInput

​Properties

​client.isTestMode

​Next Steps

Error Handling

Webhooks

Installation

Initialization

Configuration Options

Resources

Flows Resource

`flows.run(flowId, options)`

`flows.list(options?)`

`flows.get(flowId, version?)`

Runs Resource

`runs.get(executionId)`

`runs.waitForCompletion(executionId, options?)`

`runs.cancel(executionId)`

Types

Execution

FlowInfo

DocumentInput

Properties

`client.isTestMode`

Next Steps