> ## Documentation Index
> Fetch the complete documentation index at: https://docs.co-mind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

The co-mind.ai API follows RESTful conventions and is fully documented via our OpenAPI 3.1 specification. All endpoints listed below are auto-generated from `openapi.yaml`.

## Base URL

```
https://your-comind-instance.example.com
```

All endpoints are prefixed with `/v1/` unless otherwise noted.

## Authentication

All API requests (except `/health` and public auth endpoints) require a Bearer token:

```
Authorization: Bearer <token>
```

<Tabs>
  <Tab title="Personal Access Token (Recommended)">
    ```bash theme={null}
    curl https://your-instance/v1/models \
      -H "Authorization: Bearer cmnd_your-token-here"
    ```

    PATs are long-lived, scoped tokens ideal for programmatic access. See [API Tokens](/guides/api-tokens).
  </Tab>

  <Tab title="JWT Token">
    ```bash theme={null}
    curl https://your-instance/v1/models \
      -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
    ```

    JWTs are short-lived tokens from `POST /v1/auth/login`. See [Authentication](/guides/authentication).
  </Tab>
</Tabs>

## Request Format

* **Content-Type:** `application/json` for all JSON request bodies
* **File uploads:** `multipart/form-data`
* **Character encoding:** UTF-8

## Response Format

All responses return JSON with consistent structure:

<CodeGroup>
  ```json Success Response theme={null}
  {
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1730822400,
    "model": "tiiuae/Falcon3-7B-Instruct",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Response content here."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 20,
      "completion_tokens": 8,
      "total_tokens": 28
    }
  }
  ```

  ```json Error Response theme={null}
  {
    "error": {
      "message": "Detailed error description",
      "type": "error_type",
      "code": "error_code"
    }
  }
  ```

  ```json List Response theme={null}
  {
    "object": "list",
    "data": [
      { "id": "item_1", "object": "model", "...": "..." },
      { "id": "item_2", "object": "model", "...": "..." }
    ]
  }
  ```
</CodeGroup>

## Status Codes

| Code  | Description                                      |
| ----- | ------------------------------------------------ |
| `200` | Success                                          |
| `201` | Created                                          |
| `204` | No Content (successful deletion)                 |
| `400` | Bad Request — invalid parameters                 |
| `401` | Unauthorized — invalid or missing token          |
| `403` | Forbidden — insufficient permissions             |
| `404` | Not Found — resource doesn't exist               |
| `409` | Conflict — capability not supported or duplicate |
| `415` | Unsupported Media Type                           |
| `429` | Rate Limited — retry after delay                 |
| `500` | Server Error — retry with backoff                |

## Streaming

Chat and completion endpoints support Server-Sent Events (SSE) streaming by setting `"stream": true`:

```bash theme={null}
curl -X POST https://your-instance/v1/chat/completions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tiiuae/Falcon3-7B-Instruct",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'
```

Streamed responses arrive as `data:` lines:

```
data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"The"},"index":0}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":" capital"},"index":0}]}

data: [DONE]
```

## Rate Limiting

When you exceed rate limits, the API returns `429 Too Many Requests`. Implement exponential backoff in your client:

```python theme={null}
import time
import requests

def api_call_with_retry(url, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json_data)
        if response.status_code == 429:
            wait = 2 ** attempt
            time.sleep(wait)
            continue
        return response
    raise Exception("Max retries exceeded")
```

## Endpoint Categories

The API is organized into these categories — browse them in the sidebar:

<CardGroup cols={2}>
  <Card title="Authentication" icon="key">
    Login, SSO, token refresh, registration, password management.
  </Card>

  <Card title="Chat & Completions" icon="comments">
    OpenAI-compatible chat, text completion, and streaming.
  </Card>

  <Card title="Knowledge Bases" icon="book">
    Create KBs, upload files, query for context, RAG chat.
  </Card>

  <Card title="Echo Engine" icon="microphone">
    Audio transcription (STT), text-to-speech (TTS), recordings.
  </Card>

  <Card title="Researcher" icon="magnifying-glass">
    Web search, content scraping, deep research, report synthesis.
  </Card>

  <Card title="Document Analyzer" icon="file-lines">
    Upload documents, extract data, human-in-the-loop review.
  </Card>

  <Card title="Admin" icon="gear">
    Tenant management, directory sync, sanitizer policies, audit logs.
  </Card>

  <Card title="Discovery" icon="compass">
    Models, backends, capabilities, health checks.
  </Card>
</CardGroup>