> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Overview of the Raydocs REST API, authentication, and rate limits

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

```text theme={null}
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:

```http theme={null}
Authorization: Bearer <access_token>
```

Tokens can be created in your Raydocs dashboard (see the [API Keys](/api-reference/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:

```http theme={null}
Content-Type: application/json
```

### Example Request

```bash theme={null}
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:

```http theme={null}
GET /workspaces/1/extractions/templates?page=2
```

Paginated responses include metadata:

```json theme={null}
{
  "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**.

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

## Errors

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

```json theme={null}
{
  "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:

```bash theme={null}
curl -H "Authorization: Bearer <access_token>" \
  https://api.raydocs.com/workspaces
```

<Check>
  If you receive a JSON array of workspaces, your token is working correctly.
</Check>