Quickstart

This walk-through creates a case, attaches its agreement and runs the automatic pipeline. You need an API key (see Authentication).

export RECOVAI_API_KEY="rk_..."   # your key
export RECOVAI=https://api.recovai.ai

1. Create a case.

   curl -s $RECOVAI/cases \
     -H "X-API-Key: $RECOVAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "business_name": "Example Trading LLC",
       "balance": 48250.00,
       "external_reference": "ACCT-000123"
     }'

   Keep the case.id from the response.

2. Upload the agreement.

   curl -s $RECOVAI/cases/$CASE_ID/documents \
     -H "X-API-Key: $RECOVAI_API_KEY" \
     -F type=contract \
     -F file=@agreement.pdf

   The response includes the case’s new readiness.

3. Run the pipeline.

   curl -s -X POST $RECOVAI/cases/$CASE_ID/advance \
     -H "X-API-Key: $RECOVAI_API_KEY"

   This returns 202 Accepted with a job_id.

4. Wait for the job.

   curl -s $RECOVAI/jobs/$JOB_ID -H "X-API-Key: $RECOVAI_API_KEY"

   Poll every few seconds until finished is true.

5. Read the case.

   curl -s $RECOVAI/cases/$CASE_ID -H "X-API-Key: $RECOVAI_API_KEY"

   readiness and main_blocker tell you what the case needs next.

The same flow in code

PHP

PHP 8 or later with the cURL extension.

<?php
// quickstart.php: php quickstart.php agreement.pdf
const BASE = 'https://api.recovai.ai';

function api(string $method, string $path, array $options = []): array
{
    $ch = curl_init(BASE . $path);
    $headers = ['X-API-Key: ' . getenv('RECOVAI_API_KEY')];
    if (isset($options['json'])) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($options['json']));
    } elseif (isset($options['multipart'])) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $options['multipart']);
    }
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_TIMEOUT => 60,
    ]);
    $body = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($status >= 400) {
        throw new RuntimeException("$status {$body['error']}: " . ($body['details'] ?? ''));
    }
    return $body;
}

// 1. Create a case
$case = api('POST', '/cases', ['json' => [
    'business_name' => 'Example Trading LLC',
    'balance' => 48250.00,
    'external_reference' => 'ACCT-000123',
]])['case'];
echo "created {$case['case_number']}\n";

// 2. Upload the agreement
api('POST', "/cases/{$case['id']}/documents", ['multipart' => [
    'type' => 'contract',
    'file' => new CURLFile($argv[1], 'application/pdf'),
]]);

// 3. Run the pipeline and 4. wait for it
$jobId = api('POST', "/cases/{$case['id']}/advance")['job_id'];
do {
    sleep(3);
    $job = api('GET', "/jobs/$jobId")['job'];
} while (!$job['finished']);

// 5. Read the case
$case = api('GET', "/cases/{$case['id']}")['case'];
echo $case['readiness'] . ' ' . ($case['main_blocker'] ?? '') . "\n";

Node.js

Node 18 or later (built-in fetch).

// quickstart.mjs: node quickstart.mjs agreement.pdf
import { readFile } from 'node:fs/promises';
import { basename } from 'node:path';

const BASE = 'https://api.recovai.ai';
const headers = { 'X-API-Key': process.env.RECOVAI_API_KEY };

async function api(path, init = {}) {
  const res = await fetch(BASE + path, { ...init, headers: { ...headers, ...init.headers } });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${body.error}: ${body.details ?? ''}`);
  return body;
}

// 1. Create a case
const { case: kase } = await api('/cases', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ business_name: 'Example Trading LLC', balance: 48250.0, external_reference: 'ACCT-000123' }),
});
console.log('created', kase.case_number);

// 2. Upload the agreement
const file = process.argv[2];
const form = new FormData();
form.append('type', 'contract');
form.append('file', new Blob([await readFile(file)], { type: 'application/pdf' }), basename(file));
await api(`/cases/${kase.id}/documents`, { method: 'POST', body: form });

// 3. Run the pipeline and 4. wait for it
let { job_id } = await api(`/cases/${kase.id}/advance`, { method: 'POST' });
let job;
do {
  await new Promise((r) => setTimeout(r, 3000));
  ({ job } = await api(`/jobs/${job_id}`));
} while (!job.finished);

// 5. Read the case
const { case: updated } = await api(`/cases/${kase.id}`);
console.log(updated.readiness, updated.main_blocker ?? '');

Python

Python 3.9 or later, with the requests package installed.

# quickstart.py: python quickstart.py agreement.pdf
import os, sys, time
import requests

BASE = "https://api.recovai.ai"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["RECOVAI_API_KEY"]

def api(method, path, **kwargs):
    res = session.request(method, BASE + path, timeout=60, **kwargs)
    body = res.json()
    if not res.ok:
        raise RuntimeError(f"{res.status_code} {body.get('error')}: {body.get('details', '')}")
    return body

# 1. Create a case
case = api("POST", "/cases", json={
    "business_name": "Example Trading LLC",
    "balance": 48250.00,
    "external_reference": "ACCT-000123",
})["case"]
print("created", case["case_number"])

# 2. Upload the agreement
path = sys.argv[1]
with open(path, "rb") as f:
    api("POST", f"/cases/{case['id']}/documents",
        data={"type": "contract"},
        files={"file": (os.path.basename(path), f, "application/pdf")})

# 3. Run the pipeline and 4. wait for it
job_id = api("POST", f"/cases/{case['id']}/advance")["job_id"]
while True:
    time.sleep(3)
    job = api("GET", f"/jobs/{job_id}")["job"]
    if job["finished"]:
        break

# 5. Read the case
case = api("GET", f"/cases/{case['id']}")["case"]
print(case["readiness"], case.get("main_blocker") or "")