Agents

Agents are the AI assistants configured in your EK Hub dashboard. Each agent has its own knowledge base, system prompt, and configuration.

Only agents with state PUBLISHED are visible through the API.

List Agents

Returns all published AI agents belonging to your organisation.

Request

GET /agents

Response

200 OK

{
  "success": true,
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Customer Support Agent",
      "description": "Handles customer support queries",
      "state": "PUBLISHED",
      "versionNumber": 3,
      "lastUsedAt": "2026-03-19T09:00:00.000Z",
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Unique agent identifier
`name`	string	Agent display name
`description`	string	Agent description
`state`	string	Always `"PUBLISHED"` for API results
`versionNumber`	integer	Current published version number
`lastUsedAt`	string \| null	ISO 8601 timestamp of last use
`createdAt`	string	ISO 8601 creation timestamp

Code Examples

cURL

curl -H "X-API-Key: api_your_key" \
  http://localhost:3002/agents

Node.js

const res = await fetch('http://localhost:3002/agents', {
  headers: { 'X-API-Key': process.env.API_KEY! }
});
const { agents } = await res.json();
console.log(`Found ${agents.length} agents`);

Python

import requests

res = requests.get(
    'http://localhost:3002/agents',
    headers={'X-API-Key': 'api_your_key'}
)
agents = res.json()['agents']

Get Agent Details

Returns details of a specific published AI agent, including its connected knowledge hubs.

Request

GET /agents/{agentId}

Path Parameters

Parameter	Type	Required	Description
`agentId`	string (UUID)	Yes	The agent ID

Response

200 OK

{
  "success": true,
  "agent": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Customer Support Agent",
    "description": "Handles customer support queries",
    "state": "PUBLISHED",
    "versionNumber": 3,
    "lastUsedAt": "2026-03-19T09:00:00.000Z",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "knowledgeHubs": [
      { "id": "kb-uuid", "name": "Product Knowledge Base" }
    ]
  }
}

Error Responses

404 Not Found

{
  "error": "Agent not found"
}

Code Examples

cURL

curl -H "X-API-Key: api_your_key" \
  http://localhost:3002/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Node.js

const agentId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const res = await fetch(`http://localhost:3002/agents/${agentId}`, {
  headers: { 'X-API-Key': process.env.API_KEY! }
});
const { agent } = await res.json();
console.log(agent.name, '— Knowledge hubs:', agent.knowledgeHubs.length);

On this page