API Reference - Orchata

The Orchata API is a RESTful API that provides full access to all platform features. Use it to build applications that create, search, and manage knowledge bases.

Base URL

Environment	Base URL
Production	`https://api.orchata.ai`
Development	`http://localhost:4748`

Authentication

All API endpoints (except health checks) require authentication via the Oai-Api-Key header.

curl -X GET https://api.orchata.ai/spaces \
  -H "Oai-Api-Key: your-api-key"

Get your API key from the Orchata dashboard → Settings → API Keys.

You can also use standard Bearer token authentication:

curl -X GET https://api.orchata.ai/spaces \
  -H "Authorization: Bearer your-api-key"

Response Format

All responses are JSON. Successful responses return the requested data directly:

{
  "id": "spc_abc123",
  "name": "Product Documentation",
  "description": "Technical docs",
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Handling

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": "Not Found",
  "message": "Space not found",
  "statusCode": 404
}

Common Status Codes

Status	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing or invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limited
`500`	Internal Server Error

Pagination

List endpoints support pagination via query parameters:

integer

default:"1"

Page number (1-indexed)

integer

default:"10"

Items per page (max: 100)

Example:

curl "https://api.orchata.ai/spaces?page=2&pageSize=20" \
  -H "Oai-Api-Key: your-api-key"

Paginated Response:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "pageSize": 20,
    "total": 45,
    "totalPages": 3
  }
}

Metadata Filtering

List endpoints for spaces and documents support filtering by custom metadata. Pass a JSON-encoded object as the metadata query parameter:

curl "https://api.orchata.ai/spaces?metadata=%7B%22team%22%3A%22engineering%22%7D" \
  -H "Oai-Api-Key: your-api-key"

Metadata filtering uses partial matching (the JSONB @> containment operator) - the resource’s metadata must contain all the key-value pairs you specify, but may also have additional keys.

Endpoint	Metadata Usage
`GET /spaces`	Filter spaces by metadata
`POST /spaces`	Attach metadata when creating
`PATCH /spaces/:id`	Update space metadata
`GET /documents`	Filter documents by metadata
`POST /query`	Filter query results by document metadata

API Endpoints Overview

Spaces

Method	Endpoint	Description
`GET`	`/spaces`	List all spaces
`POST`	`/spaces`	Create a space
`GET`	`/spaces/:id`	Get a space
`PATCH`	`/spaces/:id`	Update a space
`DELETE`	`/spaces/:id`	Archive a space

Documents

Method	Endpoint	Description
`GET`	`/spaces/:spaceId/documents`	List documents
`POST`	`/spaces/:spaceId/documents`	Upload document
`GET`	`/spaces/:spaceId/documents/:id`	Get document
`PATCH`	`/spaces/:spaceId/documents/:id`	Update document
`DELETE`	`/spaces/:spaceId/documents/:id`	Delete document

Queries

Method	Endpoint	Description
`POST`	`/query`	Semantic search
`POST`	`/query/smart`	Smart space discovery

Rate Limiting

The API implements rate limiting to ensure fair usage:

Tier	Requests/minute
Free	60
Pro	300
Enterprise	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800

When rate limited, you’ll receive a 429 Too Many Requests response. Wait until X-RateLimit-Reset before retrying.

SDK & Tools

MCP Server

Connect AI assistants via Model Context Protocol.

TypeScript SDK

Type-safe SDK for Node.js, Deno, Bun, and browsers with AI SDK integration.

Interactive API Reference

Explore the full API with our interactive documentation below. You can test endpoints directly from your browser.

Click on any endpoint to see request/response examples and try it out.

​Base URL

​Authentication

​Response Format

​Error Handling

​Common Status Codes

​Pagination

​Metadata Filtering

​API Endpoints Overview

​Spaces

​Documents

​Queries

​Rate Limiting

​SDK & Tools

MCP Server

TypeScript SDK

​Interactive API Reference

Base URL

Authentication

Response Format

Error Handling

Common Status Codes

Pagination

Metadata Filtering

API Endpoints Overview

Spaces

Documents

Queries

Rate Limiting

SDK & Tools

Interactive API Reference