Agents
POST /v1/agents/{id}/keys
Section titled “POST /v1/agents/{id}/keys”Issue a new key for an agent (shown once)
- Scope:
agents:write - Idempotency: send
Idempotency-Key; a retry with the same key returns the first result.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
revoke_others |
boolean | Also revoke the agent’s other keys |
201 OK
| Field | Type | Required | Description |
|---|---|---|---|
key |
string | ||
device_id |
string | ||
revoked |
string[] | ||
connect |
object |
Errors are problem documents with a code.
DELETE /v1/agents/{id}/keys
Section titled “DELETE /v1/agents/{id}/keys”Revoke all of an agent’s keys and disconnect it
- Scope:
agents:write
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
revoked |
integer |
Errors are problem documents with a code.
DELETE /v1/agents/{id}/keys/{device}
Section titled “DELETE /v1/agents/{id}/keys/{device}”Revoke one key of an agent
- Scope:
agents:write
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
device |
path | string | yes | The key’s device id |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
revoked |
integer |
Errors are problem documents with a code.
POST /v1/agents/{id}:stop
Section titled “POST /v1/agents/{id}:stop”Stop an agent at once (kill switch): it is disconnected and cannot act until resumed
- Scope:
agents:write - Idempotency: send
Idempotency-Key; a retry with the same key returns the first result.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
reason |
string |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | ||
owner |
string | ||
team |
boolean | ||
unit |
string | ||
deactivated |
boolean | ||
stopped |
boolean | ||
keys |
Device[] |
Errors are problem documents with a code.
POST /v1/agents/{id}:resume
Section titled “POST /v1/agents/{id}:resume”Resume a stopped agent
- Scope:
agents:write - Idempotency: send
Idempotency-Key; a retry with the same key returns the first result.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | ||
owner |
string | ||
team |
boolean | ||
unit |
string | ||
deactivated |
boolean | ||
stopped |
boolean | ||
keys |
Device[] |
Errors are problem documents with a code.
POST /v1/agents/{id}:transfer
Section titled “POST /v1/agents/{id}:transfer”Give a team agent a new owner (in its unit); rotate_keys revokes its keys
- Scope:
agents:write - Idempotency: send
Idempotency-Key; a retry with the same key returns the first result.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
owner |
string | yes | |
rotate_keys |
boolean |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | ||
owner |
string | ||
team |
boolean | ||
unit |
string | ||
deactivated |
boolean | ||
stopped |
boolean | ||
keys |
Device[] |
Errors are problem documents with a code.
DELETE /v1/agents/{id}
Section titled “DELETE /v1/agents/{id}”Destroy an agent: it leaves every conversation, its keys stop working, its id is not reused
- Scope:
agents:write
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | ||
destroyed |
boolean | ||
conversations |
integer |
Errors are problem documents with a code.
PUT /v1/agents/{id}/role
Section titled “PUT /v1/agents/{id}/role”Give an agent a role (null: none); its connections are told config.updated
- Scope:
agents:write
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
role |
string,null | yes | A role in the library, or null |
200 OK
| Field | Type | Required | Description |
|---|---|---|---|
agent_id |
string | ||
role |
string,null | ||
changed |
boolean |
Errors are problem documents with a code.
GET /v1/agents/{id}/export
Section titled “GET /v1/agents/{id}/export”An agent package to move it to another server: profile, checkpoints, summaries (never keys); with_conversations also its content (needs messages:read)
- Scope:
agents:read
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Developer user id of the agent |
with_conversations |
query | boolean | Include the agent’s conversations (needs messages:read too). Default false. |
200 OK
object
Errors are problem documents with a code.
POST /v1/agents:import
Section titled “POST /v1/agents:import”Create an agent from a package; its first key is shown once
- Scope:
agents:write - Idempotency: send
Idempotency-Key; a retry with the same key returns the first result.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
package |
object | yes | |
owner |
string | yes | |
name |
string |
201 OK
| Field | Type | Required | Description |
|---|---|---|---|
agent |
object | ||
key |
string | ||
device_id |
string | ||
connect |
object | ||
imported |
object |
Errors are problem documents with a code.