API Reference

Complete REST API documentation. See Quickstart for authentication setup.

Error Handling

All errors follow a consistent response shape. Authenticated endpoints require an X-API-Key header.

Common Status Codes

Code	Meaning
400	Bad Request — invalid input
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
409	Conflict — duplicate resource
500	Internal Server Error

Error Response

{
  "error": "Not Found",
  "message": "Agent not found",
  "statusCode": 404
}

Users

Create and retrieve user accounts. User endpoints do not require authentication.

POST/api/usersNo auth

Create a new user account.

Request Body

Field	Type	Required	Description
email	string	Yes	User email address
name	string	No	Display name

Request

{
  "email": "dev@example.com",
  "name": "Developer"
}

Response 201

{
  "id": "clx123abc456",
  "email": "dev@example.com",
  "name": "Developer",
  "createdAt": "2025-11-29T10:30:00.000Z"
}

GET/api/users/:userIdNo auth

Retrieve a user by ID, including their API keys.

Path Parameters

Field	Type	Required	Description
userId	string	Yes	User ID

Response 200

{
  "id": "clx123abc456",
  "email": "dev@example.com",
  "name": "Developer",
  "createdAt": "2025-11-29T10:30:00.000Z",
  "apiKeys": [
    {
      "id": "clx456def789",
      "keyPreview": "...9kL",
      "name": "Production Key",
      "lastUsedAt": "2025-12-01T08:00:00.000Z",
      "expiresAt": null,
      "createdAt": "2025-11-29T10:35:00.000Z"
    }
  ]
}

API Keys

Manage API keys for authenticating requests. API key endpoints do not require authentication.

POST/api/users/:userId/api-keysNo auth

Create a new API key for a user. The full key is only returned once.

Path Parameters

Field	Type	Required	Description
userId	string	Yes	User ID

Request Body

Field	Type	Required	Description
name	string	No	Key name for identification
expiresAt	string	No	Expiration date (ISO 8601)

Request

{
  "name": "Production Key"
}

Response 201

{
  "id": "clx456def789",
  "key": "ak_Xk9mP2qR4tV6wY8zA1bC3dE5fG7hJ9kL",
  "keyPreview": "...9kL",
  "name": "Production Key",
  "lastUsedAt": null,
  "expiresAt": null,
  "createdAt": "2025-11-29T10:35:00.000Z"
}

GET/api/users/:userId/api-keysNo auth

List all API keys for a user.

Path Parameters

Field	Type	Required	Description
userId	string	Yes	User ID

Response 200

{
  "data": [
    {
      "id": "clx456def789",
      "key": "ak_Xk9mP2qR4tV6wY8zA1bC3dE5fG7hJ9kL",
      "keyPreview": "...9kL",
      "name": "Production Key",
      "lastUsedAt": "2025-12-01T08:00:00.000Z",
      "expiresAt": null,
      "createdAt": "2025-11-29T10:35:00.000Z"
    }
  ]
}

DELETE/api/users/:userId/api-keys/:keyIdNo auth

Revoke an API key.

Path Parameters

Field	Type	Required	Description
userId	string	Yes	User ID
keyId	string	Yes	API key ID

Response 204

Empty response body.

POST/api/users/:userId/api-keys/:keyId/regenerateNo auth

Regenerate an API key. The old key is invalidated and a new one is returned.

Path Parameters

Field	Type	Required	Description
userId	string	Yes	User ID
keyId	string	Yes	API key ID

Response 200

{
  "id": "clx456def789",
  "key": "ak_NewKey123abc456def789ghi",
  "keyPreview": "...ghi",
  "name": "Production Key",
  "lastUsedAt": null,
  "expiresAt": null,
  "createdAt": "2025-11-29T10:35:00.000Z"
}

Agents

Create and manage agent instances. All agent endpoints require authentication.

GET/api/agents

List agents with optional filtering. Response includes nested state and apiKey for each agent.

Query Parameters

Field	Type	Required	Description
status	string	No	Filter by status (active, inactive)
agentType	string	No	Filter by agent type
apiKeyId	string	No	Filter by API key ID
limit	integer	No	Max results (default 50)
offset	integer	No	Offset for pagination (default 0)

Response 200

{
  "agents": [
    {
      "id": "clx1abc123",
      "name": "Coach Alex",
      "description": "Fitness coach agent",
      "agentType": "HUMA-0.1",
      "status": "active",
      "metadata": { ... },
      "ttlSeconds": 600,
      "lastConnectedAt": null,
      "createdAt": "2025-11-29T10:30:00.000Z",
      "updatedAt": "2025-11-29T10:30:00.000Z",
      "state": {
        "id": "cls1abc123",
        "agentStatus": "idle",
        ...
      },
      "apiKey": {
        "id": "clx456def789",
        "name": "Production Key",
        "keyPreview": "...9kL"
      }
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

POST/api/agents

Create a new agent instance. Response is a flat Agent object without nested relations.

Request Body

Field	Type	Required	Description
name	string	No	Agent name
description	string	No	Agent description
metadata	object	No	Agent class definition (personality, instructions, tools)
agentType	string	No	Agent type (default "HUMA-0.1")
ttlSeconds	integer	No	Time to live in seconds (default 600, min 10, max 604800)

Request

{
  "name": "Coach Alex",
  "description": "Fitness coach agent",
  "agentType": "HUMA-0.1",
  "ttlSeconds": 3600,
  "metadata": {
    "className": "Coach Alex",
    "personality": "You are Coach Alex...",
    "instructions": "Help users with fitness...",
    "tools": [
      {
        "name": "send_message",
        "description": "Send a message to the user",
        "parameters": [
          { "name": "message", "type": "string", "required": true }
        ]
      }
    ]
  }
}

Response 201

{
  "id": "clx1abc123",
  "name": "Coach Alex",
  "description": "Fitness coach agent",
  "agentType": "HUMA-0.1",
  "status": "active",
  "metadata": { ... },
  "ttlSeconds": 3600,
  "lastConnectedAt": null,
  "createdAt": "2025-11-29T10:30:00.000Z",
  "updatedAt": "2025-11-29T10:30:00.000Z"
}

GET/api/agents/:agentId

Retrieve a single agent by ID. Response includes nested state but not apiKey.

Path Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent ID

Response 200

{
  "id": "clx1abc123",
  "name": "Coach Alex",
  "description": "Fitness coach agent",
  "agentType": "HUMA-0.1",
  "status": "active",
  "metadata": { ... },
  "ttlSeconds": 3600,
  "lastConnectedAt": null,
  "createdAt": "2025-11-29T10:30:00.000Z",
  "updatedAt": "2025-11-29T10:30:00.000Z",
  "state": {
    "id": "cls1abc123",
    "agentStatus": "idle",
    "personalityId": null,
    "systemPromptId": null,
    ...
  }
}

PUT/api/agents/:agentId

Update an agent. Response is a flat Agent object without nested relations.

Path Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent ID

Request Body

Field	Type	Required	Description
name	string	No	Agent name
description	string	No	Agent description
metadata	object	No	Agent metadata
status	string	No	Agent status (active, inactive)
agentType	string	No	Agent type

Request

{
  "name": "Coach Alex v2",
  "status": "inactive"
}

Response 200

{
  "id": "clx1abc123",
  "name": "Coach Alex v2",
  "description": "Fitness coach agent",
  "agentType": "HUMA-0.1",
  "status": "inactive",
  "metadata": { ... },
  "ttlSeconds": 3600,
  "lastConnectedAt": null,
  "createdAt": "2025-11-29T10:30:00.000Z",
  "updatedAt": "2025-11-29T11:00:00.000Z"
}

DELETE/api/agents/:agentId

Soft-delete an agent.

Path Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent ID

Response 204

Empty response body.

Agent State

Manage an agent's runtime state including personality and system prompt associations. All endpoints require authentication.

GET/api/agents/:agentId/state

Retrieve the current state for an agent. Includes nested personality, systemPrompt, and agent relations.

Path Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent ID

Response 200

{
  "id": "cls1abc123",
  "agentId": "clx1abc123",
  "agentStatus": "idle",
  "personalityId": "clp1abc123",
  "systemPromptId": null,
  "createdAt": "2025-11-29T10:30:00.000Z",
  "updatedAt": "2025-11-29T10:30:00.000Z",
  "personality": {
    "id": "clp1abc123",
    "name": "Friendly Coach",
    "description": "An encouraging personality",
    "styleInstructions": "Be enthusiastic..."
  },
  "systemPrompt": null,
  "agent": {
    "id": "clx1abc123",
    "name": "Coach Alex",
    ...
  }
}

PUT/api/agents/:agentId/state

Update an agent's state. All fields are optional. Response includes nested relations.

Path Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent ID

Request Body

Field	Type	Required	Description
personalityId	string	No	Personality to associate
systemPromptId	string	No	System prompt to associate
agentStatus	string	No	Agent status (idle, thinking, etc.)

Request

{
  "personalityId": "clp1abc123",
  "agentStatus": "idle"
}

Response 200

{
  "id": "cls1abc123",
  "agentId": "clx1abc123",
  "agentStatus": "idle",
  "personalityId": "clp1abc123",
  "systemPromptId": null,
  "personality": { ... },
  "systemPrompt": null,
  "agent": { ... }
}

DELETE/api/agents/:agentId/state

Reset an agent's state to defaults. Returns the fresh default state with nested relations.

Path Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent ID

Response 200

{
  "id": "cls1abc123",
  "agentId": "clx1abc123",
  "agentStatus": "idle",
  "personalityId": null,
  "systemPromptId": null,
  "personality": null,
  "systemPrompt": null,
  "agent": { ... }
}

Personalities

Manage reusable personality definitions. All endpoints require authentication. Note: the list endpoint returns an unwrapped array, not a paginated object.

GET/api/personalities

List all personalities. Returns a direct array (not a paginated wrapper).

Response 200

[
  {
    "id": "clp1abc123",
    "name": "Friendly Coach",
    "description": "An encouraging personality",
    "styleInstructions": "Be enthusiastic and supportive...",
    "createdAt": "2025-11-29T10:30:00.000Z",
    "updatedAt": "2025-11-29T10:30:00.000Z"
  }
]

GET/api/personalities/:id

Retrieve a single personality by ID.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Personality ID

Response 200

{
  "id": "clp1abc123",
  "name": "Friendly Coach",
  "description": "An encouraging personality",
  "styleInstructions": "Be enthusiastic and supportive...",
  "createdAt": "2025-11-29T10:30:00.000Z",
  "updatedAt": "2025-11-29T10:30:00.000Z"
}

POST/api/personalities

Create a new personality.

Request Body

Field	Type	Required	Description
name	string	Yes	Personality name
styleInstructions	string	Yes	Style instructions for the agent
description	string	No	Description of the personality

Request

{
  "name": "Friendly Coach",
  "styleInstructions": "Be enthusiastic and supportive. Use encouraging language.",
  "description": "An encouraging personality for fitness agents"
}

Response 201

{
  "id": "clp1abc123",
  "name": "Friendly Coach",
  "description": "An encouraging personality for fitness agents",
  "styleInstructions": "Be enthusiastic and supportive. Use encouraging language.",
  "createdAt": "2025-11-29T10:30:00.000Z",
  "updatedAt": "2025-11-29T10:30:00.000Z"
}

PUT/api/personalities/:id

Update a personality. At least one field must be provided.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Personality ID

Request Body

Field	Type	Required	Description
name	string	No	Personality name
description	string	No	Description
styleInstructions	string	No	Style instructions

Request

{
  "name": "Friendly Coach v2"
}

Response 200

{
  "id": "clp1abc123",
  "name": "Friendly Coach v2",
  "description": "An encouraging personality for fitness agents",
  "styleInstructions": "Be enthusiastic and supportive. Use encouraging language.",
  "createdAt": "2025-11-29T10:30:00.000Z",
  "updatedAt": "2025-11-29T11:00:00.000Z"
}

DELETE/api/personalities/:id

Delete a personality.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Personality ID

Response 204

Empty response body.

Events

Retrieve persisted events for an agent. For WebSocket event schemas, see HUMA-0.1. Requires authentication.

GET/api/agents/:agentId/events

List events for an agent with optional filtering.

Path Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent ID

Query Parameters

Field	Type	Required	Description
type	string	No	Filter by event type
since	string	No	Events after this timestamp (ISO 8601)
limit	integer	No	Max results (default 50)
offset	integer	No	Offset for pagination (default 0)

Response 200

{
  "events": [
    {
      "id": "cle1abc123",
      "agentId": "clx1abc123",
      "type": "huma-0.1-event",
      "content": {
        "name": "new-message",
        "context": { ... },
        "description": "User sent: Hello!"
      },
      "receivedAt": "2025-11-29T10:35:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Knowledge Bases

Store and query content for agent context. See Knowledge Bases guide for integration details. All endpoints require authentication.

POST/api/knowledge-bases

Create a new knowledge base.

Request Body

Field	Type	Required	Description
name	string	Yes	Knowledge base name
description	string	No	Description
tags	string[]	No	Tags for categorization
metadata	object	No	Additional metadata

Request

{
  "name": "Product Documentation",
  "description": "Help docs and product guides",
  "tags": ["docs", "support"]
}

Response 201

{
  "id": "cmk123abc456",
  "name": "Product Documentation",
  "description": "Help docs and product guides",
  "tags": ["docs", "support"],
  "status": "active",
  "documentCount": 0,
  "createdAt": "2025-01-13T10:30:00.000Z"
}

GET/api/knowledge-bases

List knowledge bases with optional filtering.

Query Parameters

Field	Type	Required	Description
tags	string	No	Filter by tags (comma-separated)
status	string	No	Filter by status
limit	integer	No	Max results (default 50)
offset	integer	No	Offset for pagination (default 0)

Response 200

{
  "items": [
    {
      "id": "cmk123abc456",
      "name": "Product Documentation",
      "description": "Help docs and product guides",
      "tags": ["docs", "support"],
      "status": "active",
      "documentCount": 42,
      "createdAt": "2025-01-13T10:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET/api/knowledge-bases/:id

Retrieve a single knowledge base by ID.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Knowledge base ID

Response 200

{
  "id": "cmk123abc456",
  "name": "Product Documentation",
  "description": "Help docs and product guides",
  "tags": ["docs", "support"],
  "status": "active",
  "documentCount": 42,
  "createdAt": "2025-01-13T10:30:00.000Z"
}

PUT/api/knowledge-bases/:id

Update a knowledge base.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Knowledge base ID

Request Body

Field	Type	Required	Description
name	string	No	Knowledge base name
description	string	No	Description
tags	string[]	No	Tags
metadata	object	No	Metadata

Request

{
  "name": "Updated Documentation",
  "tags": ["docs", "support", "v2"]
}

Response 200

{
  "id": "cmk123abc456",
  "name": "Updated Documentation",
  "description": "Help docs and product guides",
  "tags": ["docs", "support", "v2"],
  "status": "active",
  "documentCount": 42,
  "createdAt": "2025-01-13T10:30:00.000Z"
}

DELETE/api/knowledge-bases/:id

Delete a knowledge base and all its documents.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Knowledge base ID

Response 204

Empty response body.

POST/api/knowledge-bases/:id/query

Query a knowledge base using natural language. Returns the most relevant content chunks.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Knowledge base ID

Request Body

Field	Type	Required	Description
query	string	Yes	Natural language search query
topK	integer	No	Number of results (default 5)

Request

{
  "query": "How do I reset my password?",
  "topK": 3
}

Response 200

{
  "kbId": "cmk123abc456",
  "kbName": "Product Documentation",
  "query": "How do I reset my password?",
  "chunks": [
    {
      "content": "To reset your password, click 'Forgot Password'...",
      "source": "https://docs.example.com/account/password-reset",
      "score": 0.92,
      "metadata": { ... }
    }
  ]
}

Intakes

Manage content import pipelines (web crawlers). See Knowledge Bases guide for usage details. All endpoints require authentication.

POST/api/intakes

Create a new intake to import content into a knowledge base.

Request Body

Field	Type	Required	Description
knowledgeBaseId	string	Yes	Target knowledge base ID
type	string	Yes	Intake type ("WEB_CRAWLER")
name	string	No	Intake name
configuration	object	Yes	{ url: string } — the URL to crawl

Request

{
  "knowledgeBaseId": "cmk123abc456",
  "type": "WEB_CRAWLER",
  "name": "Docs Crawler",
  "configuration": {
    "url": "https://docs.example.com"
  }
}

Response 201

{
  "id": "cmi789xyz123",
  "type": "WEB_CRAWLER",
  "name": "Docs Crawler",
  "status": "pending",
  "knowledgeBaseId": "cmk123abc456",
  "createdAt": "2025-01-13T11:00:00.000Z",
  "message": "Intake created, pipeline started."
}

GET/api/intakes

List intakes with optional filtering.

Query Parameters

Field	Type	Required	Description
knowledgeBaseId	string	No	Filter by knowledge base ID
type	string	No	Filter by type
status	string	No	Filter by status
limit	integer	No	Max results (default 50)
offset	integer	No	Offset for pagination (default 0)

Response 200

{
  "items": [
    {
      "id": "cmi789xyz123",
      "type": "WEB_CRAWLER",
      "name": "Docs Crawler",
      "status": "completed",
      "errorMessage": null,
      "progress": {
        "pagesFound": 150,
        "pagesScraped": 4,
        "pagesIngested": 4
      },
      "knowledgeBase": {
        "id": "cmk123abc456",
        "name": "Product Documentation"
      },
      "createdAt": "2025-01-13T11:00:00.000Z",
      "updatedAt": "2025-01-13T11:15:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET/api/intakes/:id

Retrieve intake status and progress.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Intake ID

Response 200

{
  "id": "cmi789xyz123",
  "type": "WEB_CRAWLER",
  "name": "Docs Crawler",
  "status": "scraping",
  "errorMessage": null,
  "progress": {
    "pagesFound": 150,
    "pagesAfterLlmFilter": 142,
    "pagesAfterFilter": 4,
    "pagesScraped": 2,
    "pagesIngested": 0
  },
  "knowledgeBase": {
    "id": "cmk123abc456",
    "name": "Product Documentation"
  },
  "createdAt": "2025-01-13T11:00:00.000Z",
  "updatedAt": "2025-01-13T11:05:00.000Z"
}

DELETE/api/intakes/:id

Delete an intake and all its imported documents.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Intake ID

Response 200

{
  "success": true,
  "documentsDeleted": 4,
  "documentsFailed": 0,
  "message": "Intake and 4 documents deleted successfully."
}