> ## 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.

# Cloud Quickstart

> Run your first flow on Doclo Cloud in minutes

Execute document processing flows on Doclo Cloud without managing infrastructure.

## Prerequisites

<Check>Node.js 18+ installed</Check>
<Check>A Doclo Cloud account with API key</Check>
<Check>A registered flow in your Doclo Cloud dashboard</Check>

## Installation

Install the Doclo client package:

```bash theme={null}
pnpm add @doclo/client
```

## Get Your API Key

<Steps>
  <Step title="Log in to Doclo Cloud">
    Go to [app.doclo.ai](https://app.doclo.ai) and sign in to your account.
  </Step>

  <Step title="Navigate to API Keys">
    Open Settings → API Keys in the dashboard.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Store securely">
    Add the key to your environment:

    ```bash theme={null}
    # .env.local
    DOCLO_API_KEY=dc_live_your-key-here
    ```
  </Step>
</Steps>

## Initialize the Client

```typescript theme={null}
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`:

```typescript theme={null}
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:

```typescript theme={null}
// 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

```typescript theme={null}
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:

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Client Reference" icon="code" href="/cloud/client">
    Full DocloClient API reference
  </Card>

  <Card title="Webhooks" icon="webhook" href="/cloud/webhooks">
    Get notified when flows complete
  </Card>

  <Card title="Authentication" icon="key" href="/cloud/authentication">
    API key management and security
  </Card>

  <Card title="REST API" icon="server" href="/api-reference">
    Direct API access without SDK
  </Card>
</CardGroup>