Introduction

Welcome to the Raydocs REST API – a straightforward, token-based interface that lets you manage workspaces, extraction templates, sessions, documents, and results programmatically. The API exposes the same capabilities available in the dashboard: you can create extraction templates, upload documents, run extractions, and retrieve results with full audit trails.

Base URL

https://api.raydocs.com

All endpoints documented in this reference are relative to that URL.

Authentication

Every request must include a Personal Access Token in the Authorization header:

Authorization: Bearer <access_token>

Tokens can be created in your Raydocs dashboard (see the API Keys section). Each token is associated with one or more abilities / scopes that restrict what it can do.

Ability	Description
`workspaces-read`	Read workspaces the user belongs to
`workspaces-write`	Create, update or delete workspaces
`workspace-users-read`	List workspace members & invites
`workspace-users-write`	Manage workspace members & invites
`templates-read`	Read extraction templates
`templates-write`	Create or modify extraction templates
`sessions-read`	Read extraction sessions and results
`sessions-write`	Create sessions, upload documents, run extractions

When your request attempts an operation outside the abilities attached to the token, the API responds with 403 Forbidden.

Request Format

Content Type

All requests with a body should use JSON:

Content-Type: application/json

Example Request

curl -X POST "https://api.raydocs.com/extractions/templates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Extraction",
    "workspace_id": 1,
    "schema": {
      "groups": {
        "invoice_details": {
          "fields": {
            "invoice_number": { "type": "string" }
          }
        }
      }
    }
  }'

Pagination

List endpoints return paginated results. Use the page query parameter to retrieve subsequent pages:

GET /workspaces/1/extractions/templates?page=2

Paginated responses include metadata:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}

Rate Limits

Each IP address is limited to 100 requests per minute. Exceeding the limit returns 429 Too Many Requests.

For high-volume integrations, batch operations where possible (e.g., batch session creation) to stay within rate limits.

Errors

Errors are returned in JSON with an HTTP status code that reflects the problem:

{
  "message": "Validation failed.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Status Codes

Status	Meaning
200	Success
201	Created
204	Deleted (no content)
400	Bad request / validation error
401	Missing or invalid token
403	Token lacks required ability
404	Resource not found
422	Unprocessable entity
429	Rate limit exceeded
500	Server error

Quick Start

Make your first API call by listing your workspaces:

curl -H "Authorization: Bearer <access_token>" \
  https://api.raydocs.com/workspaces

If you receive a JSON array of workspaces, your token is working correctly.

Overview

Cookbook

Workspaces

Workspace Users

Extraction Templates

Extraction Sessions

Batch Operations

Documents

Workflows

Results

Base URL

Authentication

Request Format

Content Type

Example Request

Rate Limits

Errors

Status Codes

Quick Start

​Base URL

​Authentication

​Request Format

​Content Type

​Example Request

​Pagination

​Rate Limits

​Errors

​Status Codes

​Quick Start

Base URL

Authentication

Request Format

Content Type

Example Request

Pagination

Rate Limits

Errors

Status Codes

Quick Start