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:

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

Example error responses

Invalid API Key:

{
  "error": {
    "message": "Invalid authentication credentials",
    "type": "permission_error",
    "code": "invalid_api_key"
  }
}

Model Not Found:

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

Rate Limited:

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

Capability Not Supported:

{
  "error": {
    "message": "Model does not support vision capabilities",
    "type": "capability_error",
    "code": "vision_not_supported"
  }
}

Using the OpenAPI Specification

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

View interactive docs: Import into Swagger Editor or use Redoc
Generate client SDKs 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

Support

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

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

Getting Started

Guides

Core Platform Endpoints

Knowledge Base & Sessions

Chat Sessions (Stateful)

Echo Engine (Audio / STT / TTS)

Transcription

Recordings

Text-to-Speech

Document Analyzer

Researcher

Service Endpoints

Error Handling

Common HTTP Status Codes

Using the OpenAPI Specification

Support

​Core Platform Endpoints

​Knowledge Base & Sessions

​Chat Sessions (Stateful)

​Echo Engine (Audio / STT / TTS)

​Transcription

​Recordings

​Text-to-Speech

​Document Analyzer

​Researcher

​Service Endpoints

​Error Handling

​Common HTTP Status Codes

​Using the OpenAPI Specification

​Support

Core Platform Endpoints

Knowledge Base & Sessions

Chat Sessions (Stateful)

Echo Engine (Audio / STT / TTS)

Transcription

Recordings

Text-to-Speech

Document Analyzer

Researcher

Service Endpoints

Error Handling

Common HTTP Status Codes

Using the OpenAPI Specification

Support