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>

Personal Access Token (Recommended)
JWT Token

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.

curl https://your-instance/v1/models \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

JWTs are short-lived tokens from POST /v1/auth/login. See Authentication.

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:

{
  "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
  }
}

{
  "error": {
    "message": "Detailed error description",
    "type": "error_type",
    "code": "error_code"
  }
}

{
  "object": "list",
  "data": [
    { "id": "item_1", "object": "model", "...": "..." },
    { "id": "item_2", "object": "model", "...": "..." }
  ]
}

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:

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:

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 by audience. Choose the authentication method that fits your use case, then browse the endpoints in the sidebar.

Who uses what

Audience	Auth methods	Description
Users	PAT (recommended) or JWT	The full user-tier API. Personal Access Tokens are the recommended way to integrate — long-lived, scoped, no refresh flow required.
Tenant Admin	Session JWT only	Tenant-scoped management operations. PATs are not accepted on these routes; see the Tenant Admin API page.
System Admin	Session JWT only	Cross-tenant / system-wide operations. PATs are not accepted; see the System Admin API page.

User APIs (PAT-friendly)

Discovery

List available models on your instance.

Authentication & Session

Personal Access Tokens

Create, list, rotate, and revoke long-lived API tokens for programmatic access.

AI Inference

OpenAI-compatible chat completions and text completions.

Chat / Sessions

Preview — not currently enabled. Session-based chat management will be enabled in an upcoming release.

Knowledge Bases

Create knowledge bases, upload files, query for context, retrieval-augmented chat.

Researcher

Web search, content scraping, deep research, report synthesis, source credibility.

Quota

View the caller’s remaining quota for chat, embeddings, and other metered operations.

Admin APIs

Tenant Admin

Tenant management, sub-organizations, tenant-tier API keys, sanitizer policies, directory sync. Contact support for programmatic access.

System Admin

Cross-tenant provisioning, tier configuration, model defaults, governance (EU AI Act), audit logs, system health. Contact support for programmatic access.

Admin APIs

Authentication

API Tokens

Discovery

Completions

Chat

Knowledge Base

Chat Sessions (Preview)

Responses

Embeddings

Translation

Quota

Researcher

API Reference

Base URL

Authentication

Request Format

Response Format

Status Codes

Streaming

Rate Limiting

Endpoint Categories

Who uses what

User APIs (PAT-friendly)

Discovery

Authentication & Session

Personal Access Tokens

AI Inference

Chat / Sessions

Knowledge Bases

Researcher

Quota

Admin APIs

Tenant Admin

System Admin

​Base URL

​Authentication

​Request Format

​Response Format

​Status Codes

​Streaming

​Rate Limiting

​Endpoint Categories

​Who uses what

​User APIs (PAT-friendly)

Discovery

Authentication & Session

Personal Access Tokens

AI Inference

Chat / Sessions

Knowledge Bases

Researcher

Quota

​Admin APIs

Tenant Admin

System Admin

Base URL

Authentication

Request Format

Response Format

Status Codes

Streaming

Rate Limiting

Endpoint Categories

Who uses what

User APIs (PAT-friendly)

Admin APIs