Open API Overview

The Ocriva Open API gives external developers programmatic access to document processing, template management, and processing history. It is intended for server-to-server integrations, automated pipelines, and custom tooling built on top of Ocriva.

Base URL

https://api.ocriva.com/v1

All endpoints described in this section are relative to this base URL.

Authentication

The Open API supports two authentication methods. API Key authentication is recommended for all new integrations.

API Key (Recommended)

Pass your API key in the X-API-Key header:

curl https://api.ocriva.com/v1/openapi/projects \
  -H "X-API-Key: ocr_your_api_key"

Alternatively, you can use the Authorization header with the Bearer scheme:

curl https://api.ocriva.com/v1/openapi/projects \
  -H "Authorization: Bearer ocr_your_api_key"

JWT (Legacy)

Exchange your API key for a short-lived JWT by calling the login endpoint, then include the JWT in subsequent requests:

# Step 1: Exchange API key for JWT
curl -X POST https://api.ocriva.com/v1/openapi/auth/login \
  -H "Content-Type: application/json" \
  -d '{"token": "ocr_your_api_key"}'
 
# Step 2: Use the returned accessToken in requests
curl https://api.ocriva.com/v1/openapi/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

The login response includes an accessToken, its expiresIn (seconds), and metadata about the token (tokenInfo).

Token Types

API keys are scoped to either an organization or a single project.

When using an organization token, passing a projectId that does not belong to the token's organization returns a 401 Unauthorized response. When using a project token, passing a projectId that differs from the token's project also returns a 401.

Rate Limiting

Requests are limited to 60 per minute per API key. If you exceed this limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

{
  "statusCode": 429,
  "message": "Too many requests. Please slow down.",
  "error": "Too Many Requests"
}

Error Format

All errors use a consistent envelope:

{
  "statusCode": 400,
  "message": "projectId is required for organization tokens",
  "error": "Bad Request"
}

Pagination

Endpoints that return lists accept page and limit query parameters and respond with a pagination object:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}