API Reference

The Raven Docs REST API gives you full programmatic access to your workspace.

Base URL

http://localhost:3000/api

For production deployments with a custom domain:

https://your-domain.com/api

Authentication

All API requests require an API key passed in the header:

curl http://localhost:3000/api/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"

See Authentication for details on getting an API key.

Request Format

Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	For POST/PUT	application/json

Query Parameters

List endpoints support pagination and filtering:

GET /v1/pages?workspaceId=ws_123&limit=20&page=1

Parameter	Type	Description
limit	number	Items per page (default: 20, max: 100)
page	number	Page number (default: 1)

Response Format

All responses are JSON:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Success Responses

Status	Description
200 OK	Request successful
201 Created	Resource created
204 No Content	Delete successful

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Title is required",
    "details": {
      "field": "title",
      "reason": "required"
    }
  }
}

See Errors for all error codes.

Endpoints

Workspaces

Method	Endpoint	Description
GET	/workspaces	List workspaces
GET	/workspaces/:id	Get workspace
POST	/workspaces	Create workspace
PUT	/workspaces/:id	Update workspace

Workspaces Reference →

Spaces

Method	Endpoint	Description
GET	/spaces	List spaces
GET	/spaces/:id	Get space
POST	/spaces	Create space
PUT	/spaces/:id	Update space
DELETE	/spaces/:id	Delete space

Spaces Reference →

Pages

Method	Endpoint	Description
GET	/pages	List pages
GET	/pages/:id	Get page
POST	/pages	Create page
PUT	/pages/:id	Update page
DELETE	/pages/:id	Delete page

Pages Reference →

Tasks

Method	Endpoint	Description
GET	/tasks	List tasks
GET	/tasks/:id	Get task
POST	/tasks	Create task
PUT	/tasks/:id	Update task
DELETE	/tasks/:id	Delete task

Tasks Reference →

SDK

TypeScript/JavaScript

npm install @raven-docs/sdk

import { RavenDocs } from '@raven-docs/sdk';

const client = new RavenDocs({
  apiKey: process.env.RAVEN_API_KEY,
});

// List pages
const pages = await client.pages.list({
  workspaceId: 'ws_123',
  spaceId: 'space_456',
});

// Create a page
const page = await client.pages.create({
  workspaceId: 'ws_123',
  spaceId: 'space_456',
  title: 'New Page',
  content: { type: 'doc', content: [] },
});

Python (Coming Soon)

from ravendocs import RavenDocs

client = RavenDocs(api_key="your-api-key")

pages = client.pages.list(workspace_id="ws_123")

Rate Limits

Rate limits can be configured in your environment. Default limits:

Scope	Requests/minute
Default	60

See Rate Limits for configuration options.

Webhooks

Subscribe to events via webhooks:

// Configure in dashboard or via API
await client.webhooks.create({
  url: 'https://your-server.com/webhooks/raven',
  events: ['page.created', 'task.completed'],
});

Related

• Authentication - API key setup
• Errors - Error handling
• Rate Limits - Usage limits