> ## 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.

# API Reference

> Complete REST API documentation for 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.

```bash theme={null}
curl -X GET https://api.orchata.ai/spaces \
  -H "Oai-Api-Key: your-api-key"
```

<Note>
  Get your API key from the [Orchata dashboard](https://app.orchata.ai) → Settings → API Keys.
</Note>

You can also use standard Bearer token authentication:

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

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

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

<ParamField query="page" type="integer" default="1">
  Page number (1-indexed)
</ParamField>

<ParamField query="pageSize" type="integer" default="10">
  Items per page (max: 100)
</ParamField>

**Example:**

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

**Paginated Response:**

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

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

<Warning>
  When rate limited, you'll receive a `429 Too Many Requests` response. Wait until `X-RateLimit-Reset` before retrying.
</Warning>

## SDK & Tools

<CardGroup cols={2}>
  <Card title="MCP Server" icon="plug" href="/mcp/overview">
    Connect AI assistants via Model Context Protocol.
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdk/quickstart">
    Type-safe SDK for Node.js, Deno, Bun, and browsers with AI SDK integration.
  </Card>
</CardGroup>

## Interactive API Reference

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

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