Skip to main content

API Reference

AI-Native Enterprise Operating System API

Version: 2.0.0 Base URL: https://api.kosmos.nuvanta-holding.com

Auto-Generated

This documentation is automatically extracted from the OpenAPI schema.

Authentication​

All API requests require authentication using JWT tokens from Zitadel:

curl -X GET "https://api.kosmos.nuvanta-holding.com/api/v1/agents" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Agents​

GET /api/v1/agents​

List agents

Get status of all 11 KOSMOS agents.

Responses:

StatusDescription
200List of agent statuses

GET /api/v1/agents/{id}​

Get agent status

Get detailed status of a specific agent.

Parameters:

NameInTypeRequiredDescription
idpathstringYesAgent ID (e.g., zeus, athena)

Responses:

StatusDescription
200Agent status

GET /api/v1/agents/{id}/metrics​

Get agent metrics

Get performance metrics for an agent.

Responses:

StatusDescription
200Agent metrics

Chat​

POST /api/v1/chat​

Send a message to KOSMOS

Sends a user message and receives AI responses from the agent network.

Request Body:

{
  "message": <string>,
  "conversation_id": <string>,
  "context": <object>,
}

Responses:

StatusDescription
200Successful response
401Unauthorized
429Rate limited

POST /api/v1/chat/stream​

Stream chat response

Stream AI responses using Server-Sent Events.

Responses:

StatusDescription
200SSE stream

Conversations​

GET /api/v1/conversations​

List conversations

Get paginated list of user conversations.

Parameters:

NameInTypeRequiredDescription
pagequeryintegerNoPage number
limitqueryintegerNoItems per page

Responses:

StatusDescription
200List of conversations

POST /api/v1/conversations​

Create conversation

Start a new conversation.

Responses:

StatusDescription
201Conversation created

GET /api/v1/conversations/{id}​

Get conversation

Get conversation details and messages.

Parameters:

NameInTypeRequiredDescription
idpathstringYesConversation UUID

Responses:

StatusDescription
200Conversation details
404Not found

DELETE /api/v1/conversations/{id}​

Delete conversation

Archive a conversation.

Responses:

StatusDescription
204Deleted

Costs​

GET /api/v1/costs/usage​

Get usage costs

Get cost breakdown for current period.

Responses:

StatusDescription
200Cost breakdown

GET /api/v1/costs/limits​

Get cost limits

Get configured cost limits.

Responses:

StatusDescription
200Cost limits

Governance​

GET /api/v1/governance/proposals​

List proposals

Get list of governance proposals.

Responses:

StatusDescription
200List of proposals

POST /api/v1/governance/proposals/{id}/vote​

Cast vote

Cast a Pentarchy vote on a proposal.

Responses:

StatusDescription
200Vote recorded

Knowledge​

GET /api/v1/knowledge/documents​

List documents

Get indexed documents.

Responses:

StatusDescription
200Document list

POST /api/v1/knowledge/documents​

Upload document

Upload and index a new document.

Responses:

StatusDescription
201Document indexed

POST /api/v1/knowledge/search​

Search knowledge base

Semantic search across documents and memories.

Request Body:

{
  "query": <string>,
  "limit": <integer>,
  "filters": <object>,
  "include_memories": <boolean>,
}

Responses:

StatusDescription
200Search results

MCP​

GET /api/v1/mcp/servers​

List MCP servers

Get connected MCP servers.

Responses:

StatusDescription
200Server list

GET /api/v1/mcp/{server}/tools​

List MCP tools

Get available tools from an MCP server.

Parameters:

NameInTypeRequiredDescription
serverpathstringYesMCP server name

Responses:

StatusDescription
200List of tools

POST /api/v1/mcp/{server}/call​

Call MCP tool

Execute a tool on an MCP server.

Responses:

StatusDescription
200Tool result

Memory​

GET /api/v1/memory/entities​

List memory entities

Get entities from knowledge graph.

Responses:

StatusDescription
200Entity list

GET /api/v1/memory/relations​

List relations

Get relations between entities.

Responses:

StatusDescription
200Relation list

System​

GET /health​

Health check

Check API health status.

Responses:

StatusDescription
200Healthy

GET /ready​

Readiness check

Check if API is ready to serve requests.

Responses:

StatusDescription
200Ready

GET /metrics​

Prometheus metrics

Get Prometheus-formatted metrics.

Responses:

StatusDescription
200Metrics

Data Models​

ChatRequest​

Request to send a chat message

FieldTypeRequiredDescription
messagestringYesUser message content
conversation_idstringNoOptional existing conversation ID
contextobjectNoAdditional context for the request

ChatResponse​

Response from KOSMOS agents

FieldTypeRequiredDescription
idstringNoMessage ID
conversation_idstringNoConversation ID
contentstringNoAgent response
agent_idstringNoResponding agent
tool_callsarrayNoTools used
cost_usdnumberNoRequest cost

SearchRequest​

Semantic search request

FieldTypeRequiredDescription
querystringYesSearch query
limitintegerNoMax results
filtersobjectNoOptional filters
include_memoriesbooleanNoInclude memory entities

AgentStatus​

Agent status information

FieldTypeRequiredDescription
idstringNoAgent ID
namestringNoAgent name
domainstringNoAgent domain
statestringNoCurrent state
metricsobjectNoPerformance metrics

Proposal​

Governance proposal

FieldTypeRequiredDescription
idstringNoProposal ID
actionstringNoProposed action
estimated_costnumberNoEstimated cost
statusstringNoProposal status
votesarrayNoVotes cast

Rate Limiting​

KOSMOS API implements rate limiting to ensure fair usage:

TierRequests/minBurst
Free6010
Pro30050
Enterprise1000200

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

Error Handling​

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "message",
      "reason": "Required field missing"
    }
  }
}
Error CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid authentication
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
VALIDATION_ERROR422Invalid request data
RATE_LIMITED429Too many requests
COST_EXCEEDED402Cost limit exceeded
INTERNAL_ERROR500Server error

Webhooks​

KOSMOS supports webhooks for async notifications:

{
  "event": "conversation.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "conversation_id": "uuid",
    "total_cost": 0.05
  }
}

SDKs​

Official SDKs are available:

  • Python: pip install kosmos-sdk
  • TypeScript: npm install @kosmos/sdk
  • Go: go get github.com/nuvanta/kosmos-go