Ocriva Logo

Documents

Getting Started

Install @ocriva/sdk and send your first document processing request in minutes.

sdkinstallationquickstarttypescript

Published: 4/1/2026

Getting Started

The @ocriva/sdk package gives you a fully-typed TypeScript client for the Ocriva API. This guide walks you through installation, initial setup, and your first upload.

Requirements

  • Node.js >= 18 — the SDK uses the native fetch API built into Node 18+
  • TypeScript >= 5.0 (recommended) — required to take full advantage of the type definitions

Installation

Install the SDK with your preferred package manager:

# npm
npm install @ocriva/sdk
 
# pnpm
pnpm add @ocriva/sdk
 
# yarn
yarn add @ocriva/sdk

Getting Your API Key

API keys are created from the Ocriva Dashboard:

  1. Sign in at ocriva.com
  2. Navigate to Settings → API Tokens
  3. Click Create Token and choose a scope (organization or project)
  4. Copy the token — it will not be shown again

See Authentication for details on token types and scopes.

Quick Start

The following example shows the most common workflow: create a client, upload a file, poll until processing completes, then download the result.

import { OcrivaClient } from '@ocriva/sdk';
import { readFileSync } from 'node:fs';
 
const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_API_KEY!,
});
 
// 1. Read a local file into a Buffer
const buffer = readFileSync('./invoice.pdf');
 
// 2. Upload the file for processing
const upload = await client.upload.file(buffer, {
  fileName: 'invoice.pdf',
  fileType: 'pdf',
  fileSize: String(buffer.byteLength),
  mimeType: 'application/pdf',
  projectId: 'proj_abc123',
  templateId: 'tmpl_xyz789', // optional — apply an extraction template
});
 
console.log('Upload ID:', upload.id);
console.log('Status:', upload.status); // 'uploaded' | 'processing' | ...
 
// 3. Poll processing history until the job finishes
let record = await client.processingHistory.get(upload.id, 'proj_abc123');
 
while (record.status === 'pending' || record.status === 'queued' || record.status === 'in_progress') {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  record = await client.processingHistory.get(upload.id, 'proj_abc123');
}
 
if (record.status === 'completed') {
  // 4. Download the extracted result as JSON
  const blob = await client.processingHistory.getResult(record.id, {
    format: 'json',
    projectId: 'proj_abc123',
  });
 
  const text = await blob.text();
  console.log('Extracted data:', JSON.parse(text));
} else {
  console.error('Processing failed:', record.errorMessage);
}

Configuration

Pass a configuration object to OcrivaClient. Only apiKey is required; all other options have sensible defaults.

import { OcrivaClient } from '@ocriva/sdk';
 
const client = new OcrivaClient({
  apiKey: 'ocr_live_...',       // required
  baseUrl: 'https://api.ocriva.com/v1', // default
  timeout: 30_000,              // 30 s, in milliseconds
  maxRetries: 3,                // retries on 429 and 5xx responses
});

Configuration Options

OptionTypeDefaultDescription
apiKeystring—Required. Your Ocriva API key
baseUrlstringhttps://api.ocriva.com/v1Base URL of the API
timeoutnumber30000Request timeout in milliseconds
maxRetriesnumber3Maximum retry attempts on transient failures (429, 5xx)

The apiKey must be a non-empty string or the constructor will throw an OcrivaError immediately. The baseUrl, if provided, must be a valid URL with a scheme (e.g., https://).