Skip to main content
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.
AbilityDescription
workspaces-readRead workspaces the user belongs to
workspaces-writeCreate, update or delete workspaces
workspace-users-readList workspace members & invites
workspace-users-writeManage workspace members & invites
templates-readRead extraction templates
templates-writeCreate or modify extraction templates
sessions-readRead extraction sessions and results
sessions-writeCreate 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

StatusMeaning
200Success
201Created
204Deleted (no content)
400Bad request / validation error
401Missing or invalid token
403Token lacks required ability
404Resource not found
422Unprocessable entity
429Rate limit exceeded
500Server 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.