Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orchata.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

EnvironmentBase URL
Productionhttps://api.orchata.ai
Developmenthttp://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

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

​
Pagination

List endpoints support pagination via query parameters:
​
page
integer
default:"1"
Page number (1-indexed)
​
pageSize
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.
EndpointMetadata Usage
GET /spacesFilter spaces by metadata
POST /spacesAttach metadata when creating
PATCH /spaces/:idUpdate space metadata
GET /documentsFilter documents by metadata
POST /queryFilter query results by document metadata

​
API Endpoints Overview

​
Spaces

MethodEndpointDescription
GET/spacesList all spaces
POST/spacesCreate a space
GET/spaces/:idGet a space
PATCH/spaces/:idUpdate a space
DELETE/spaces/:idArchive a space

​
Documents

MethodEndpointDescription
GET/spaces/:spaceId/documentsList documents
POST/spaces/:spaceId/documentsUpload document
GET/spaces/:spaceId/documents/:idGet document
PATCH/spaces/:spaceId/documents/:idUpdate document
DELETE/spaces/:spaceId/documents/:idDelete document

​
Queries

MethodEndpointDescription
POST/querySemantic search
POST/query/smartSmart space discovery

​
Rate Limiting

The API implements rate limiting to ensure fair usage:
TierRequests/minute
Free60
Pro300
EnterpriseCustom
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.