REST API

The Komand Gateway exposes a REST API for all platform operations. All endpoints require JWT authentication (except /api/auth/* and /health) and return responses in the ApiResponse<T> envelope format.

Base URL

http://localhost:5000   # Development
https://app.komand.ai   # Managed cloud

Authentication

All API requests (except auth endpoints) require a JWT Bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Tokens are obtained via the login endpoint and expire after 60 minutes. Use the refresh endpoint to obtain a new token without re-authenticating.

Response Format

All endpoints return the ApiResponse<T> envelope:

{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": null
}

Error responses:

{
  "success": false,
  "data": null,
  "error": "Descriptive error message"
}

Paginated responses include metadata:

{
  "success": true,
  "data": [ ... ],
  "error": null,
  "meta": {
    "total": 150,
    "page": 1,
    "pageSize": 50
  }
}

Headers

Header	Description
`Authorization`	`Bearer {token}` — required for all authenticated endpoints
`Content-Type`	`application/json` — required for POST/PUT requests
`X-Request-Id`	Correlation ID for request tracing (auto-generated if not provided)

Health

`GET /health`

Returns the system health status. No authentication required.

curl http://localhost:5000/health

Auth

`POST /api/auth/login`

Authenticate with email and password. Returns a JWT token and user info.

Request:

{ "email": "[email protected]", "password": "your-password" }

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "rt_abc123...",
    "user": {
      "id": "user-001",
      "name": "Jane",
      "email": "[email protected]",
      "initials": "J"
    }
  }
}

`POST /api/auth/refresh`

Refresh an expired access token.

Request:

{ "refreshToken": "rt_abc123..." }

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "rt_def456..."
  }
}

JWT Configuration

Setting	Default
Issuer	`komand.ai`
Audience	`komand.ai`
Token expiration	60 minutes
Refresh token expiration	7 days

Token claims: sub (user ID), email, name, jti (unique token ID).

WebChat

`POST /api/webchat/message`

Send a message through the WebChat channel. Requires authentication. The session is created automatically on first contact.

Request:

Field	Type	Required	Default	Max Length	Description
`senderId`	string	Yes	—	128	Unique user identifier
`text`	string	Yes	—	10,000	Message content
`displayName`	string	No	`null`	256	User display name
`accountId`	string	No	`"default"`	128	Account identifier

curl -X POST http://localhost:5000/api/webchat/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "senderId": "user-1", "text": "Hello!", "displayName": "Alice" }'

Response:

{
  "success": true,
  "data": {
    "text": "Hi Alice! How can I help you today?",
    "timestamp": "2026-02-23T10:30:02Z",
    "sessionId": "WebChat:default:user-1"
  }
}

Session key format: WebChat:{accountId}:{senderId}

Agents

`POST /api/agents/`

Create or update an agent configuration. Returns 201 Created.

Request: AgentConfig object.

Field	Type	Required	Default	Max Length
`agentId`	string	Yes	—	128
`name`	string	Yes	—	256
`description`	string	No	`null`	1,000
`systemPrompt`	string	No	`"You are a helpful enterprise AI assistant."`	50,000
`modelProvider`	string	No	`"anthropic"`	128
`modelId`	string	No	`"claude-sonnet-4-20250514"`	128
`maxContextTokens`	int	No	`100,000`	—
`enabledSkillIds`	string[]	No	`[]`	—
`allowedChannels`	string[]	No	`[]`	—

curl -X POST http://localhost:5000/api/agents/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "agentId": "sales-bot",
    "name": "Sales Assistant",
    "systemPrompt": "You are a friendly sales assistant.",
    "enabledSkillIds": ["crm-contact-lookup"]
  }'

`GET /api/agents/{agentId}`

Retrieve an agent’s configuration.

Parameter	Max Length
`agentId`	128

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:5000/api/agents/sales-bot

`GET /api/agents/{agentId}/history/{sessionId}`

Get conversation history for a session.

Parameter	Type	Default	Range
`agentId`	path	—	max 128 chars
`sessionId`	path	—	max 256 chars
`maxTurns`	query	50	1–500

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:5000/api/agents/sales-bot/history/WebChat:default:user-1?maxTurns=20"

Response:

{
  "success": true,
  "data": [
    {
      "role": "user",
      "content": "What's the pricing?",
      "timestamp": "2026-02-23T10:30:00Z",
      "toolCallIds": null
    },
    {
      "role": "assistant",
      "content": "The Pro plan is $49/month...",
      "timestamp": "2026-02-23T10:30:02Z",
      "toolCallIds": ["exec-abc-123"]
    }
  ]
}

`DELETE /api/agents/{agentId}/history/{sessionId}`

Clear conversation history for a session. Returns 204 No Content.

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:5000/api/agents/sales-bot/history/WebChat:default:user-1

`POST /api/agents/{agentId}/memory`

Store a key-value memory entry.

Request:

{ "key": "company_timezone", "value": "Australia/Brisbane" }

Field	Max Length
`key`	256
`value`	100,000

`GET /api/agents/{agentId}/memory/{key}`

Recall a memory value by key.

Parameter	Max Length
`key`	256

Response:

{
  "success": true,
  "data": { "key": "company_timezone", "value": "Australia/Brisbane" }
}

Sessions

`GET /api/sessions/{sessionId}`

Get session information.

Parameter	Max Length
`sessionId`	256

Response:

{
  "success": true,
  "data": {
    "sessionId": "WebChat:default:user-1",
    "channel": "WebChat",
    "channelAccountId": "default",
    "senderId": "user-1",
    "boundAgentId": "default",
    "messageCount": 12,
    "createdAt": "2026-02-23T10:00:00Z",
    "lastActivityAt": "2026-02-23T10:15:30Z"
  }
}

`POST /api/sessions/{sessionId}/bind`

Bind an agent to a session.

Request:

{ "agentId": "sales-bot" }

`DELETE /api/sessions/{sessionId}`

End a session and clear its state. Returns 204 No Content.

Skills

`POST /api/skills/`

Request: SkillDefinition object (see Skills guide for the full contract). Required fields: skillId, name, version.

`GET /api/skills/`

List skills with pagination and filtering.

Parameter	Type	Default	Range	Description
`publisherId`	string	`null`	—	Filter by publisher
`verifiedOnly`	bool	`null`	—	Only verified skills

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:5000/api/skills/?verifiedOnly=true&publisherId=komand-official"

`GET /api/skills/{skillId}`

Get a skill definition.

Parameter	Max Length
`skillId`	128

`DELETE /api/skills/{skillId}`

Unregister a skill. Returns 204 No Content.

Error Codes

HTTP Status	Meaning	Example
`200`	Success	Successful GET or POST
`201`	Created	Agent or skill created
`204`	No Content	Successful DELETE
`400`	Bad Request	Validation error (missing field, invalid range)
`401`	Unauthorized	Missing or invalid JWT token
`404`	Not Found	Agent, session, or skill doesn’t exist
`429`	Too Many Requests	Rate limit exceeded
`504`	Gateway Timeout	Grain didn’t respond within 30 seconds

Validation Rules

All route parameters and request bodies are validated at the Gateway:

Constraint	Value
Agent ID max length	128 characters
Session ID max length	256 characters
Skill ID max length	128 characters
Memory key max length	256 characters
Memory value max length	100,000 characters
System prompt max length	50,000 characters
WebChat text max length	10,000 characters
maxTurns range	1–500 (default 50)
pageSize range	1–200 (default 50)
Grain call timeout	30 seconds

SignalR Hub

The Gateway also exposes a SignalR hub at /hubs/chat for real-time bi-directional messaging. See Message Flow for hub methods and details.

Swagger

In development mode, Swagger UI is available at /swagger for interactive API exploration. Set DOTNET_ENVIRONMENT=Development to enable.