Skip to main content

​
Developer Guide

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

​
Core Platform Endpoints

EndpointMethodAuthPurpose
/healthGETNoneHealth check
/v1/chat/completionsPOSTBearerChat completions (OpenAI-compatible)
/v1/completionsPOSTBearerText completions
/v1/embeddingsPOSTBearerGenerate embeddings
/v1/modelsGETBearerList available models
/v1/backendsGETBearerList backend providers
/v1/capabilitiesGETBearerCheck backend capabilities
/v1/backends/healthGETBearerBackend health status

​
Knowledge Base & Sessions

EndpointMethodAuthPurpose
/v1/knowledgebasesPOSTBearerCreate knowledge base
/v1/knowledgebasesGETBearerList knowledge bases
/v1/knowledgebases/{id}GETBearerGet KB details
/v1/knowledgebases/{id}DELETEBearerDelete KB and all files
/v1/knowledgebases/{id}/filesPOSTBearerUpload file to KB
/v1/knowledgebases/{id}/filesGETBearerList files in KB
/v1/knowledgebases/{id}/files/{file_id}DELETEBearerDelete file from KB
/v1/knowledgebases/queryPOSTBearerQuery KB for context retrieval
/v1/knowledgebase/chat/completionsPOSTBearerChat with KBs (stateless RAG)

​
Chat Sessions (Stateful)

EndpointMethodAuthPurpose
/v1/chat/sessionsPOSTBearerCreate chat session
/v1/chat/sessionsGETBearerList sessions
/v1/chat/sessions/{id}GETBearerGet session details
/v1/chat/sessions/{id}PATCHBearerUpdate session
/v1/chat/sessions/{id}DELETEBearerDelete session
/v1/chat/sessions/{id}/messagesPOSTBearerSend message
/v1/chat/sessions/{id}/messagesGETBearerGet message history
/v1/chat/sessions/{id}/clearPOSTBearerClear session history

​
Echo Engine (Audio / STT / TTS)

​
Transcription

EndpointMethodPurpose
/v1/echo/healthGETEcho engine health check
/v1/echo/languagesGETSupported transcription languages
/v1/echo/metricsGETEcho engine metrics
/v1/echo/transcribePOSTSynchronous audio transcription
/v1/echo/transcribe/asyncPOSTAsync transcription (returns job ID)
/v1/echo/transcribe/{jobId}GETGet transcription job status
/v1/echo/transcribe/{jobId}DELETEDelete transcription job

​
Recordings

EndpointMethodPurpose
/v1/echo/recordingsPOSTCreate recording entry
/v1/echo/recordingsGETList recordings
/v1/echo/recordings/{id}GETGet recording
/v1/echo/recordings/{id}PATCHUpdate recording
/v1/echo/recordings/{id}DELETEDelete recording
/v1/echo/recordings/{id}/link-jobPOSTLink recording to transcription job

​
Text-to-Speech

EndpointMethodPurpose
/v1/echo/tts/voicesGETList available TTS voices
/v1/echo/tts/languagesGETList TTS languages
/v1/echo/tts/synthesizePOSTText-to-speech synthesis

​
Document Analyzer

EndpointMethodPurpose
/v1/document-analyzer/uploadPOSTUpload document (multipart, 200MB max)
/v1/document-analyzer/sessionsGETList analysis sessions
/v1/document-analyzer/sessionsPOSTCreate analysis session
/v1/document-analyzer/sessions/{id}GETGet session details
/v1/document-analyzer/sessions/{id}PATCHUpdate session
/v1/document-analyzer/sessions/{id}DELETEDelete session
/v1/document-analyzer/sessions/{id}/candidatesGETList extraction candidates
/v1/document-analyzer/sessions/{id}/candidatesPUTUpdate candidates
/v1/document-analyzer/sessions/{id}/rowsetsGETList extracted rowsets
/v1/document-analyzer/sessions/{id}/rowsetsPUTUpdate rowsets
/v1/document-analyzer/sessions/{id}/exportGETGet export download token
/v1/document-analyzer/sessions/{id}/export/downloadGETDownload exported file
/v1/document-analyzer/sessions/{id}/review/manifestGETGet review manifest
/v1/document-analyzer/sessions/{id}/review/items/{itemId}GETGet review item
/v1/document-analyzer/sessions/{id}/review/items/{itemId}/resolvePOSTResolve review item
/v1/document-analyzer/sessions/{id}/review/bulk-resolvePOSTBulk resolve items
/v1/document-analyzer/sessions/{id}/review/completePOSTComplete review
/v1/document-analyzer/sessions/{id}/sse-tokenPOSTGet SSE connection token
/v1/document-analyzer/sessions/{id}/auditGETSession audit trail

​
Researcher

EndpointMethodPurpose
/v1/researcher/searchPOSTMulti-provider web search
/v1/researcher/scrapePOSTExtract content from URL
/v1/researcher/researchPOSTDeep research with iterative reasoning
/v1/researcher/sessionsGETList research sessions
/v1/researcher/sessions/{id}GETGet session status
/v1/researcher/sessions/{id}/fullGETGet full session data
/v1/researcher/sessions/{id}/pausePOSTPause research session
/v1/researcher/sessions/{id}/resumePOSTResume research session
/v1/researcher/sessions/{id}DELETEDelete research session
/v1/researcher/sessions/{id}/critiquePOSTCritique research results
/v1/researcher/sessions/{id}/improvePOSTImprove research results
/v1/researcher/analyzePOSTAnalyze content with AI
/v1/researcher/synthesizePOSTSynthesize into report
/v1/researcher/grant-proposalPOSTGenerate grant proposal
/v1/researcher/credibilityGET/POSTCredibility configuration CRUD
/v1/researcher/credibility/{id}GET/PUT/DELETEManage specific config

​
Service Endpoints

EndpointMethodAuthPurpose
/v1/services/entra-configGETBearerDiscover tenant Entra config (no secrets)
/v1/services/token/exchangePOSTBearerExchange auth code for tokens (PKCE)
/v1/services/token/refreshPOSTHybridRefresh 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

CodeError TypeDescription
400Bad RequestInvalid request parameters or malformed JSON
403ForbiddenInvalid or missing API key
404Not FoundEndpoint or resource not found
409ConflictRequested capability not supported by model
415Unsupported MediaInvalid image/audio format
429Rate LimitedToo many requests, retry later
500Server ErrorInternal server error, retry with backoff
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: 
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./python-client

​
Support

Email: 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