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.aiDevelopment 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"
You can also use standard Bearer token authentication:
curl -X GET https://api.orchata.ai/spaces \ -H "Authorization: Bearer your-api-key"
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 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
List endpoints support pagination via query parameters:
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 } }
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 /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 Method Endpoint Description GET/spacesList all spaces POST/spacesCreate a space GET/spaces/:idGet a space PATCH/spaces/:idUpdate a space DELETE/spaces/:idArchive a space
Documents Method Endpoint Description 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 Method Endpoint Description POST/querySemantic search POST/query/smartSmart 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.
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.
