> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Management APIs

The management APIs provide endpoints for discovering agents, managing project-level agent definitions, creating deployments, and coordinating between agents via handoffs and delegation. For authentication and error handling conventions, see [API overview](/agent-platform/api-reference/index).

## Agent Management API

### Agent discovery

List and inspect agents across your tenant.

**Base path**: `/api/agents`

#### GET /api/agents

List all agents accessible to the authenticated tenant.

Auth is required.

**Response body**

| Field     | Type    | Description                     |
| --------- | ------- | ------------------------------- |
| `success` | boolean | Whether the operation succeeded |
| `total`   | number  | Total number of agents          |
| `agents`  | array   | List of agent metadata objects  |

Each agent object:

| Field  | Type   | Description |
| ------ | ------ | ----------- |
| `id`   | string | Agent ID    |
| `name` | string | Agent name  |

**Example request**

```bash theme={null}
curl https://agents.kore.ai/api/agents \
  -H "Authorization: Bearer abl_sk-your-api-key"
```

**Example response**

```json theme={null}
{
  "success": true,
  "total": 3,
  "agents": [
    { "id": "ag_001", "name": "support-agent" },
    { "id": "ag_002", "name": "sales-agent" },
    { "id": "ag_003", "name": "onboarding-agent" }
  ]
}
```

***

#### GET /api/agents/:name

Get full details for a specific agent by name, including the compiled specification.

Auth is required.

**Path parameters**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `name`    | string | Agent name  |

**Response body**

| Field     | Type    | Description                     |
| --------- | ------- | ------------------------------- |
| `success` | boolean | Whether the operation succeeded |
| `agent`   | object  | Agent detail object             |

Agent detail object:

| Field        | Type   | Description           |
| ------------ | ------ | --------------------- |
| `id`         | string | Agent ID              |
| `name`       | string | Agent name            |
| `dslContent` | string | Agent DSL source code |

**Example request**

```bash theme={null}
curl https://agents.kore.ai/api/agents/support-agent \
  -H "Authorization: Bearer abl_sk-your-api-key"
```

**Example response**

```json theme={null}
{
  "success": true,
  "agent": {
    "id": "ag_001",
    "name": "support-agent",
    "dslContent": "AGENT: support-agent\n..."
  }
}
```

**Cache behavior**

Agent detail responses include `Cache-Control: private, max-age=300` since agent specifications change infrequently.

***

### Project agents

Manage agents within a specific project. Project agents are tenant-scoped and include version tracking.

**Base path**: `/api/projects/:projectId/agents`

#### GET /api/projects/:projectId/agents

List all agents in a project.

Auth is required.
**Permission**: `agent:read`

**Response body**

| Field     | Type    | Description                  |
| --------- | ------- | ---------------------------- |
| `success` | boolean | Always `true` on success     |
| `agents`  | array   | List of agent detail objects |

Each agent object:

| Field            | Type           | Description                                 |
| ---------------- | -------------- | ------------------------------------------- |
| `id`             | string         | Agent ID                                    |
| `name`           | string         | Agent name                                  |
| `agentPath`      | string         | Full agent path (e.g., `domain/agent-name`) |
| `description`    | string or null | Agent description                           |
| `versionCount`   | number         | Number of saved versions                    |
| `activeVersions` | object         | Map of environment to active version        |
| `createdAt`      | string         | ISO 8601 creation timestamp                 |
| `updatedAt`      | string         | ISO 8601 last update timestamp              |

**Example request**

```bash theme={null}
curl https://agents.kore.ai/api/projects/proj_abc/agents \
  -H "Authorization: Bearer abl_sk-your-api-key"
```

**Example response**

```json theme={null}
{
  "success": true,
  "agents": [
    {
      "id": "ag_001",
      "name": "support-agent",
      "agentPath": "helpdesk/support-agent",
      "description": "Customer support automation agent",
      "versionCount": 5,
      "activeVersions": {
        "dev": "3",
        "production": "2"
      },
      "createdAt": "2026-02-15T08:00:00.000Z",
      "updatedAt": "2026-03-10T14:30:00.000Z"
    }
  ]
}
```

***

#### GET /api/projects/:projectId/agents/:agentName

Get a single agent with version count and DSL content.

Auth is required.
**Permission**: `agent:read`

**Path parameters**

| Parameter   | Type          | Description |
| ----------- | ------------- | ----------- |
| `projectId` | string (CUID) | Project ID  |
| `agentName` | string        | Agent name  |

**Response body**

```json theme={null}
{
  "success": true,
  "agent": {
    "id": "ag_001",
    "name": "support-agent",
    "agentPath": "helpdesk/support-agent",
    "description": "Customer support automation agent",
    "dslContent": "AGENT: support-agent\n...",
    "versionCount": 5,
    "activeVersions": { "dev": "3", "production": "2" },
    "createdAt": "2026-02-15T08:00:00.000Z",
    "updatedAt": "2026-03-10T14:30:00.000Z"
  }
}
```

***

#### PUT /api/projects/:projectId/agents/:agentName/dsl

Save a working copy of the agent's DSL content. This updates the mutable draft without triggering compilation or creating a version.

Auth is required.
**Permission**: `agent:write`

**Request body**

| Field        | Type   | Required | Description                              |
| ------------ | ------ | -------- | ---------------------------------------- |
| `dslContent` | string | Yes      | ABL DSL source content (cannot be empty) |

**Response body**

```json theme={null}
{
  "success": true,
  "updatedAt": "2026-03-11T10:30:00.000Z"
}
```

***

### Deployments

Manage the deployment lifecycle for agent projects. Deployments bundle specific agent versions for a target environment.

**Base path**: `/api/projects/:projectId/deployments`

#### POST /api/projects/:projectId/deployments

Create a new deployment with specified agent versions and configuration.

Auth is required.
**Permission**: `deployment:create`

**Request body**

| Field                     | Type   | Required | Description                                           |
| ------------------------- | ------ | -------- | ----------------------------------------------------- |
| `environment`             | string | Yes      | Target environment: `dev`, `staging`, or `production` |
| `agentVersionManifest`    | object | Yes      | Map of agent names to version strings (or `"auto"`)   |
| `entryAgentName`          | string | Yes      | Name of the entry-point agent                         |
| `label`                   | string | No       | Human-readable deployment label                       |
| `description`             | string | No       | Deployment description                                |
| `modelOverrides`          | object | No       | Model configuration overrides per agent               |
| `settingsVersionId`       | string | No       | Pin a specific project settings version               |
| `workflowVersionManifest` | object | No       | Map of workflow names to versions                     |

**Example request**

```bash theme={null}
curl -X POST https://agents.kore.ai/api/projects/proj_abc/deployments \
  -H "Authorization: Bearer abl_sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "agentVersionManifest": {
      "support-agent": "3",
      "escalation-agent": "2"
    },
    "entryAgentName": "support-agent",
    "label": "v2.1 production release"
  }'
```

**Example response (201 Created)**

```json theme={null}
{
  "success": true,
  "deployment": {
    "id": "dep_xyz789",
    "projectId": "proj_abc",
    "environment": "production",
    "status": "active",
    "label": "v2.1 production release",
    "description": null,
    "endpointSlug": "proj_abc-production-lk3m-a1b2c3",
    "entryAgentName": "support-agent",
    "agentVersionManifest": {
      "support-agent": "3",
      "escalation-agent": "2"
    },
    "createdAt": "2026-03-11T10:00:00.000Z",
    "createdBy": "user_123"
  }
}
```

***

#### GET /api/projects/:projectId/deployments

List all deployments for a project.

Auth is required.

**Response body**

```json theme={null}
{
  "success": true,
  "deployments": [
    {
      "id": "dep_xyz789",
      "projectId": "proj_abc",
      "environment": "production",
      "status": "active",
      "label": "v2.1 production release",
      "endpointSlug": "proj_abc-production-lk3m-a1b2c3",
      "createdAt": "2026-03-11T10:00:00.000Z"
    }
  ]
}
```

***

#### GET /api/projects/:projectId/deployments/:deploymentId

Get deployment details including channel count.

Auth is required.

**Response body**

```json theme={null}
{
  "success": true,
  "deployment": {
    "id": "dep_xyz789",
    "projectId": "proj_abc",
    "environment": "production",
    "status": "active",
    "label": "v2.1 production release",
    "description": null,
    "endpointSlug": "proj_abc-production-lk3m-a1b2c3",
    "entryAgentName": "support-agent",
    "agentVersionManifest": {
      "support-agent": "3",
      "escalation-agent": "2"
    },
    "channelCount": 2,
    "createdAt": "2026-03-11T10:00:00.000Z",
    "createdBy": "user_123"
  }
}
```

***

#### POST /api/projects/:projectId/deployments/:deploymentId/retire

Retire a deployment. Active sessions are drained before full retirement.

Auth is required.
**Permission**: `deployment:create`

**Response body**

```json theme={null}
{
  "success": true,
  "deployment": {
    "id": "dep_xyz789",
    "status": "retired",
    "retiredAt": "2026-03-11T12:00:00.000Z"
  }
}
```

***

#### POST /api/projects/:projectId/deployments/:deploymentId/rollback

Rollback a retired deployment to its previous active state.

Auth is required.
**Permission**: `deployment:create`

***

#### POST /api/projects/:projectId/deployments/:deploymentId/promote

Promote a deployment from one environment to another (e.g., staging to production).

Auth is required.
**Permission**: `deployment:create`

***

## Multi-Agent API

The multi-agent API enables coordination between agents through handoffs, delegation, and asynchronous callbacks. These patterns allow you to build complex agent workflows where specialized agents collaborate to handle user requests.

### Handoff

Handoffs transfer conversation control from one agent to another within the same session. The originating agent transfers full context to the target agent.

#### How handoffs work

1. Agent A determines a handoff is needed (via ABL `HANDOFF:` directive or runtime decision).
2. The platform transfers the session to Agent B with context from Agent A.
3. Agent B takes over the conversation and responds to subsequent messages.
4. Handoff events are recorded in the session trace.

Handoffs are triggered automatically by the ABL runtime when an agent definition includes a `HANDOFF:` directive. You do not call a separate handoff endpoint -- the handoff occurs within the normal [agent-backed chat flow](/agent-platform/api-reference/conversation-api#agent-backed-chat).

#### Observing handoffs

Handoff events appear in the `traceEvents` array of the chat response:

```json theme={null}
{
  "sessionId": "a1b2c3d4-...",
  "response": "Let me transfer you to our billing specialist.",
  "traceEvents": [
    {
      "type": "handoff",
      "data": {
        "fromAgent": "support-agent",
        "toAgent": "billing-agent",
        "reason": "billing_inquiry",
        "timestamp": "2026-03-11T10:05:00.000Z"
      }
    }
  ]
}
```

#### Handoff count in session metrics

The `handoffCount` field on session objects tracks how many handoffs occurred:

```bash theme={null}
curl https://agents.kore.ai/api/projects/proj_abc/sessions/sess_123 \
  -H "Authorization: Bearer abl_sk-your-api-key"
```

***

### Delegation

Delegation allows one agent to request work from another agent and receive the result, without transferring conversation control. The delegating agent remains in charge of the conversation.

#### How delegation works

1. Agent A encounters a task suited for Agent B.
2. Agent A delegates the task to Agent B (via ABL `DELEGATE:` directive).
3. Agent B processes the task and returns a result.
4. Agent A incorporates the result and continues the conversation.

Delegation is orchestrated by the ABL runtime and occurs transparently during message execution. Delegation events appear in session traces:

```json theme={null}
{
  "type": "delegate",
  "data": {
    "fromAgent": "coordinator-agent",
    "toAgent": "research-agent",
    "task": "lookup_product_specs",
    "duration_ms": 1200
  }
}
```

***

### Asynchronous callbacks

The callback API enables external systems to deliver results back to a suspended agent session. When an agent invokes an async tool or delegates to an external system, the platform generates a callback URL that the external system calls when the work is complete.

**Base path**: `/api/v1/callbacks`

#### POST /api/v1/callbacks/:callbackId

Deliver a callback result to resume a suspended agent session.

**Auth required**: HMAC signature verification via `x-callback-signature` header (no JWT required)

**Path parameters**

| Parameter    | Type   | Description                                                         |
| ------------ | ------ | ------------------------------------------------------------------- |
| `callbackId` | string | Unique callback identifier provided when the suspension was created |

**Request headers**

| Header                 | Required    | Description                                                      |
| ---------------------- | ----------- | ---------------------------------------------------------------- |
| `x-callback-signature` | Recommended | HMAC-SHA256 signature of the request body: `sha256=<hex_digest>` |
| `Content-Type`         | Yes         | `application/json`                                               |

**Request body**

The request body is passed directly to the agent as the callback payload. Structure depends on the tool or delegation that created the callback:

```json theme={null}
{
  "status": "completed",
  "result": {
    "orderId": "ORD-12345",
    "trackingNumber": "1Z999AA10123456784"
  }
}
```

**Response body**

```json theme={null}
{
  "ok": true
}
```

If the callback has already been processed:

```json theme={null}
{
  "ok": true,
  "status": "already_processed"
}
```

**HMAC signature verification**

When an agent suspension includes a callback secret, the platform verifies the `x-callback-signature` header against the request body:

```python theme={null}
import hmac
import hashlib

body = '{"status":"completed","result":{"orderId":"ORD-12345"}}'
secret = "your-callback-secret"
signature = "sha256=" + hmac.new(
    secret.encode(), body.encode(), hashlib.sha256
).hexdigest()

# Include in request: x-callback-signature: sha256=abc123...
```

```bash theme={null}
curl -X POST https://agents.kore.ai/api/v1/callbacks/cb_abc123 \
  -H "Content-Type: application/json" \
  -H "x-callback-signature: sha256=abc123def456..." \
  -d '{"status":"completed","result":{"orderId":"ORD-12345"}}'
```

**Callback guarantees**

| Property    | Guarantee                                                      |
| ----------- | -------------------------------------------------------------- |
| Delivery    | At-most-once (callback ID is atomically claimed)               |
| Idempotency | Duplicate callbacks return `200` with `already_processed`      |
| Timeout     | Callbacks expire after the suspension TTL (configurable)       |
| Processing  | Callbacks are enqueued for reliable processing via a job queue |

**Error responses**

| Status | Error                           | Cause                                         |
| ------ | ------------------------------- | --------------------------------------------- |
| `200`  | `already_processed`             | Callback was already delivered                |
| `401`  | Invalid signature               | HMAC verification failed                      |
| `503`  | Service temporarily unavailable | Failed to enqueue the resume job (retry safe) |

***

### Multi-agent patterns in ABL

The ABL DSL supports several multi-agent patterns natively:

| Pattern    | ABL directive              | Description                                     |
| ---------- | -------------------------- | ----------------------------------------------- |
| Handoff    | `HANDOFF:`                 | Transfer conversation to another agent          |
| Delegation | `DELEGATE:`                | Request work from another agent, retain control |
| Fan-out    | Multiple `DELEGATE:`       | Delegate to several agents in parallel          |
| Escalation | `HANDOFF:` with conditions | Transfer based on confidence or intent signals  |

These patterns are configured in agent definitions and executed automatically by the runtime. See the [ABL SDK](/agent-platform/api-reference/sdks#abl-sdk) for programmatic access to agent definitions.

***

### Security considerations

* **Encryption at rest**: All secret values are encrypted using AES-256-GCM with tenant-scoped keys before storage.
* **No plaintext retrieval**: The API never returns secret values in responses. Only metadata (tool name, key name, environment, version) is exposed.
* **Audit logging**: All create, rotate, and delete operations are recorded in the audit log.
* **Version tracking**: Each secret rotation increments the version counter, providing a rotation history.
* **Expiration**: Secrets can include an optional `expiresAt` timestamp. Expired secrets are no longer resolved at runtime.

## Next steps

* [Conversation API](/agent-platform/api-reference/conversation-api) -- Send messages through deployed agents
* [Knowledge, Analytics & Export APIs](/agent-platform/api-reference/knowledge-analytics-export) -- Analytics and project export
* [SDKs](/agent-platform/api-reference/sdks) -- Parse agent definitions programmatically