Developer Guide

This guide is the developer’s overview of the public co-mind.ai API — what’s available, how authentication and errors work, and how to generate a typed client. For the exact endpoint list, request/response schemas, and a try-it-out console, see the API Reference tab; the machine-readable spec is openapi.yaml at the repository root. For a step-by-step tour that exercises the whole surface with real requests, follow the API Walkthrough.

Authentication

Every request (except the unauthenticated /v1/auth/* bootstrap endpoints) needs a Bearer token:

Authorization: Bearer <token>

Two token types:

Type	Best for	How you get one
Personal Access Token (PAT) — recommended for automation	Scripts, CI/CD, integrations, any long-lived caller	Mint from an authenticated session — see API Tokens
Session JWT	Interactive sessions, ad-hoc testing	Log in with email + password (or SSO) — see Authentication

PATs are single-tenant by design — a PAT stays scoped to the workspace active on your session at creation time. Multi-tenant users can switch the active tenant on their session JWT before minting a new PAT for another workspace.

What the API covers

The public surface exposes the following areas. See the API Reference for the complete endpoint list and payload schemas in each area.

Discovery — list models available on this deployment
Authentication — login (email + password, SSO), token refresh, current-user info, password management
API Tokens — create, list, rotate, and revoke Personal Access Tokens; discover available scopes
Chat completions — stateless, OpenAI-compatible chat
Knowledge bases — create and manage knowledge bases, upload and index files, query for retrieved chunks, and chat with retrieval-augmented generation
Researcher — single-shot web search, multi-step research sessions with pause/resume/critique/improve, content analysis and synthesis
Translation — text translation between languages with ISO 639-1 codes and optional source-language detection
Embeddings — turn text into fixed-length vectors for your own similarity search or reranking
Chat Sessions (Preview) — stateful, server-orchestrated conversations. Not currently enabled; documented for integrator preparation

Admin surfaces (not in the public reference)

Administrator endpoints are session-JWT only and are not documented in the public reference. If your integration needs programmatic access:

Tenant Admin — tenant management, sub-organizations, tenant-tier API keys, sanitizer policies, directory sync (Tenant Admin API)
System Admin — cross-tenant provisioning, tier configuration, model defaults, governance, audit logs, system health (System Admin API)

Reach out at support@co-mind.ai and we will share the endpoint specification scoped to your use case.

Error format

Every error follows the same envelope:

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

HTTP status codes

Code	Meaning	When to retry
`400`	Bad request — invalid parameters or malformed JSON	No — fix the request
`401`	Unauthorized — invalid or missing token	No — refresh or re-authenticate
`403`	Forbidden — insufficient scope or role	No — request access
`404`	Not found — endpoint or resource does not exist	No
`409`	Conflict — capability not supported, or duplicate resource	No
`415`	Unsupported media type	No — check `Content-Type`
`429`	Rate limited	Yes — respect `Retry-After` header, then exponential backoff
`500`	Server error	Yes — exponential backoff
`502` / `503` / `504`	Upstream / gateway error	Yes — exponential backoff

Example error responses

Invalid or missing token (401):

{
  "error": {
    "message": "Invalid authentication credentials",
    "type": "authentication_error",
    "code": "invalid_token"
  }
}

Model not found (404):

{
  "error": {
    "message": "Model 'invalid-model' not found",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Rate limited (429):

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

Streaming

Chat and completion endpoints support Server-Sent Events (SSE) by setting "stream": true in the request body. Streamed responses arrive as data: lines terminated by data: [DONE].

Generating a client SDK

The published openapi.yaml is the source of truth. Generate typed clients in 50+ languages with OpenAPI Generator:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./python-client

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./typescript-client

openapi-generator-cli generate \
  -i openapi.yaml \
  -g go \
  -o ./go-client

Or import into Swagger Editor or Redoc for another interactive view.

Support

Email: support@co-mind.ai Response time: 24-48 hours (business days) When contacting support, include:

The exact request (curl command or code snippet)
The complete error response, including HTTP status
Expected vs. actual behavior
Language / framework version and network setup

Getting Started

Guides

API Walkthrough

Authentication

What the API covers

Admin surfaces (not in the public reference)

Error format

HTTP status codes

Streaming

Generating a client SDK

Support

​Authentication

​What the API covers

​Admin surfaces (not in the public reference)

​Error format

​HTTP status codes

​Streaming

​Generating a client SDK

​Support

Authentication

What the API covers

Admin surfaces (not in the public reference)

Error format

HTTP status codes

Streaming

Generating a client SDK

Support