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

# Developer Guide

This guide provides a comprehensive reference of all API endpoints organized by service area, with request/response examples.

## Core Platform Endpoints

| Endpoint               | Method | Auth   | Purpose                              |
| ---------------------- | ------ | ------ | ------------------------------------ |
| `/health`              | GET    | None   | Health check                         |
| `/v1/chat/completions` | POST   | Bearer | Chat completions (OpenAI-compatible) |
| `/v1/completions`      | POST   | Bearer | Text completions                     |
| `/v1/embeddings`       | POST   | Bearer | Generate embeddings                  |
| `/v1/models`           | GET    | Bearer | List available models                |
| `/v1/backends`         | GET    | Bearer | List backend providers               |
| `/v1/capabilities`     | GET    | Bearer | Check backend capabilities           |
| `/v1/backends/health`  | GET    | Bearer | Backend health status                |

## Knowledge Base & Sessions

| Endpoint                                  | Method | Auth   | Purpose                        |
| ----------------------------------------- | ------ | ------ | ------------------------------ |
| `/v1/knowledgebases`                      | POST   | Bearer | Create knowledge base          |
| `/v1/knowledgebases`                      | GET    | Bearer | List knowledge bases           |
| `/v1/knowledgebases/{id}`                 | GET    | Bearer | Get KB details                 |
| `/v1/knowledgebases/{id}`                 | DELETE | Bearer | Delete KB and all files        |
| `/v1/knowledgebases/{id}/files`           | POST   | Bearer | Upload file to KB              |
| `/v1/knowledgebases/{id}/files`           | GET    | Bearer | List files in KB               |
| `/v1/knowledgebases/{id}/files/{file_id}` | DELETE | Bearer | Delete file from KB            |
| `/v1/knowledgebases/query`                | POST   | Bearer | Query KB for context retrieval |
| `/v1/knowledgebase/chat/completions`      | POST   | Bearer | Chat with KBs (stateless RAG)  |

### Chat Sessions (Stateful)

| Endpoint                          | Method | Auth   | Purpose               |
| --------------------------------- | ------ | ------ | --------------------- |
| `/v1/chat/sessions`               | POST   | Bearer | Create chat session   |
| `/v1/chat/sessions`               | GET    | Bearer | List sessions         |
| `/v1/chat/sessions/{id}`          | GET    | Bearer | Get session details   |
| `/v1/chat/sessions/{id}`          | PATCH  | Bearer | Update session        |
| `/v1/chat/sessions/{id}`          | DELETE | Bearer | Delete session        |
| `/v1/chat/sessions/{id}/messages` | POST   | Bearer | Send message          |
| `/v1/chat/sessions/{id}/messages` | GET    | Bearer | Get message history   |
| `/v1/chat/sessions/{id}/clear`    | POST   | Bearer | Clear session history |

## Echo Engine (Audio / STT / TTS)

### Transcription

| Endpoint                      | Method | Purpose                              |
| ----------------------------- | ------ | ------------------------------------ |
| `/v1/echo/health`             | GET    | Echo engine health check             |
| `/v1/echo/languages`          | GET    | Supported transcription languages    |
| `/v1/echo/metrics`            | GET    | Echo engine metrics                  |
| `/v1/echo/transcribe`         | POST   | Synchronous audio transcription      |
| `/v1/echo/transcribe/async`   | POST   | Async transcription (returns job ID) |
| `/v1/echo/transcribe/{jobId}` | GET    | Get transcription job status         |
| `/v1/echo/transcribe/{jobId}` | DELETE | Delete transcription job             |

### Recordings

| Endpoint                            | Method | Purpose                             |
| ----------------------------------- | ------ | ----------------------------------- |
| `/v1/echo/recordings`               | POST   | Create recording entry              |
| `/v1/echo/recordings`               | GET    | List recordings                     |
| `/v1/echo/recordings/{id}`          | GET    | Get recording                       |
| `/v1/echo/recordings/{id}`          | PATCH  | Update recording                    |
| `/v1/echo/recordings/{id}`          | DELETE | Delete recording                    |
| `/v1/echo/recordings/{id}/link-job` | POST   | Link recording to transcription job |

### Text-to-Speech

| Endpoint                  | Method | Purpose                   |
| ------------------------- | ------ | ------------------------- |
| `/v1/echo/tts/voices`     | GET    | List available TTS voices |
| `/v1/echo/tts/languages`  | GET    | List TTS languages        |
| `/v1/echo/tts/synthesize` | POST   | Text-to-speech synthesis  |

## Document Analyzer

| Endpoint                                                            | Method | Purpose                                |
| ------------------------------------------------------------------- | ------ | -------------------------------------- |
| `/v1/document-analyzer/upload`                                      | POST   | Upload document (multipart, 200MB max) |
| `/v1/document-analyzer/sessions`                                    | GET    | List analysis sessions                 |
| `/v1/document-analyzer/sessions`                                    | POST   | Create analysis session                |
| `/v1/document-analyzer/sessions/{id}`                               | GET    | Get session details                    |
| `/v1/document-analyzer/sessions/{id}`                               | PATCH  | Update session                         |
| `/v1/document-analyzer/sessions/{id}`                               | DELETE | Delete session                         |
| `/v1/document-analyzer/sessions/{id}/candidates`                    | GET    | List extraction candidates             |
| `/v1/document-analyzer/sessions/{id}/candidates`                    | PUT    | Update candidates                      |
| `/v1/document-analyzer/sessions/{id}/rowsets`                       | GET    | List extracted rowsets                 |
| `/v1/document-analyzer/sessions/{id}/rowsets`                       | PUT    | Update rowsets                         |
| `/v1/document-analyzer/sessions/{id}/export`                        | GET    | Get export download token              |
| `/v1/document-analyzer/sessions/{id}/export/download`               | GET    | Download exported file                 |
| `/v1/document-analyzer/sessions/{id}/review/manifest`               | GET    | Get review manifest                    |
| `/v1/document-analyzer/sessions/{id}/review/items/{itemId}`         | GET    | Get review item                        |
| `/v1/document-analyzer/sessions/{id}/review/items/{itemId}/resolve` | POST   | Resolve review item                    |
| `/v1/document-analyzer/sessions/{id}/review/bulk-resolve`           | POST   | Bulk resolve items                     |
| `/v1/document-analyzer/sessions/{id}/review/complete`               | POST   | Complete review                        |
| `/v1/document-analyzer/sessions/{id}/sse-token`                     | POST   | Get SSE connection token               |
| `/v1/document-analyzer/sessions/{id}/audit`                         | GET    | Session audit trail                    |

## Researcher

| Endpoint                                | Method         | Purpose                                |
| --------------------------------------- | -------------- | -------------------------------------- |
| `/v1/researcher/search`                 | POST           | Multi-provider web search              |
| `/v1/researcher/scrape`                 | POST           | Extract content from URL               |
| `/v1/researcher/research`               | POST           | Deep research with iterative reasoning |
| `/v1/researcher/sessions`               | GET            | List research sessions                 |
| `/v1/researcher/sessions/{id}`          | GET            | Get session status                     |
| `/v1/researcher/sessions/{id}/full`     | GET            | Get full session data                  |
| `/v1/researcher/sessions/{id}/pause`    | POST           | Pause research session                 |
| `/v1/researcher/sessions/{id}/resume`   | POST           | Resume research session                |
| `/v1/researcher/sessions/{id}`          | DELETE         | Delete research session                |
| `/v1/researcher/sessions/{id}/critique` | POST           | Critique research results              |
| `/v1/researcher/sessions/{id}/improve`  | POST           | Improve research results               |
| `/v1/researcher/analyze`                | POST           | Analyze content with AI                |
| `/v1/researcher/synthesize`             | POST           | Synthesize into report                 |
| `/v1/researcher/grant-proposal`         | POST           | Generate grant proposal                |
| `/v1/researcher/credibility`            | GET/POST       | Credibility configuration CRUD         |
| `/v1/researcher/credibility/{id}`       | GET/PUT/DELETE | Manage specific config                 |

## Service Endpoints

| Endpoint                      | Method | Auth   | Purpose                                   |
| ----------------------------- | ------ | ------ | ----------------------------------------- |
| `/v1/services/entra-config`   | GET    | Bearer | Discover tenant Entra config (no secrets) |
| `/v1/services/token/exchange` | POST   | Bearer | Exchange auth code for tokens (PKCE)      |
| `/v1/services/token/refresh`  | POST   | Hybrid | Refresh OAuth access token                |

## Error Handling

All errors follow this structure:

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

### Common HTTP Status Codes

| Code  | Error Type        | Description                                  |
| ----- | ----------------- | -------------------------------------------- |
| `400` | Bad Request       | Invalid request parameters or malformed JSON |
| `403` | Forbidden         | Invalid or missing API key                   |
| `404` | Not Found         | Endpoint or resource not found               |
| `409` | Conflict          | Requested capability not supported by model  |
| `415` | Unsupported Media | Invalid image/audio format                   |
| `429` | Rate Limited      | Too many requests, retry later               |
| `500` | Server Error      | Internal server error, retry with backoff    |

<Accordion title="Example error responses">
  **Invalid API Key:**

  ```json theme={null}
  {
    "error": {
      "message": "Invalid authentication credentials",
      "type": "permission_error",
      "code": "invalid_api_key"
    }
  }
  ```

  **Model Not Found:**

  ```json theme={null}
  {
    "error": {
      "message": "Model 'invalid-model' not found",
      "type": "invalid_request_error",
      "code": "model_not_found"
    }
  }
  ```

  **Rate Limited:**

  ```json theme={null}
  {
    "error": {
      "message": "Rate limit exceeded. Please retry after 60 seconds.",
      "type": "rate_limit_exceeded",
      "code": "rate_limit"
    }
  }
  ```

  **Capability Not Supported:**

  ```json theme={null}
  {
    "error": {
      "message": "Model does not support vision capabilities",
      "type": "capability_error",
      "code": "vision_not_supported"
    }
  }
  ```
</Accordion>

## Using the OpenAPI Specification

The included `openapi.yaml` contains the complete API specification. You can:

* **View interactive docs:** Import into [Swagger Editor](https://editor.swagger.io/) or use [Redoc](https://redocly.github.io/redoc/)
* **Generate client SDKs** in 50+ languages with [OpenAPI Generator](https://openapi-generator.tech/):

<CodeGroup>
  ```bash Python Client theme={null}
  openapi-generator-cli generate \
    -i openapi.yaml \
    -g python \
    -o ./python-client
  ```

  ```bash TypeScript Client theme={null}
  openapi-generator-cli generate \
    -i openapi.yaml \
    -g typescript-axios \
    -o ./typescript-client
  ```
</CodeGroup>

## Support

**Email:** [support@co-mind.ai](mailto:support@co-mind.ai)
**Response Time:** 24-48 hours (business days)

When contacting support, include:

1. Full curl command or code snippet
2. Complete error response with status code
3. Expected vs actual behavior
4. Language/framework version and network setup