Agent
Headless agent conversation and run operations.
Operations
Each operation lists its specific responses. See Common error responses for errors shared by every operation on this page.
List agent conversations
GET /api/v1/agent/conversations
Operation ID: listAgentConversations
Effect: read
Confirmation: never
Required privilege: VIEW_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create an agent conversation
POST /api/v1/agent/conversations
Operation ID: createAgentConversation
Effect: write
Confirmation: conditional
Required privilege: USE_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
Archive an agent conversation
DELETE /api/v1/agent/conversations/{conversation}
Operation ID: archiveAgentConversation
Effect: destructive
Confirmation: required
Required privilege: USE_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get an agent conversation
GET /api/v1/agent/conversations/{conversation}
Operation ID: getAgentConversation
Effect: read
Confirmation: never
Required privilege: VIEW_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update an agent conversation
PATCH /api/v1/agent/conversations/{conversation}
Operation ID: updateAgentConversation
Effect: write
Confirmation: conditional
Required privilege: USE_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List agent messages
GET /api/v1/agent/conversations/{conversation}/messages
Operation ID: listAgentMessages
Effect: read
Confirmation: never
Required privilege: VIEW_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List agent runs
GET /api/v1/agent/conversations/{conversation}/runs
Operation ID: listAgentRuns
Effect: read
Confirmation: never
Required privilege: VIEW_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create an asynchronous agent run
POST /api/v1/agent/conversations/{conversation}/runs
Operation ID: createAgentRun
Effect: write
Confirmation: conditional
Required privilege: USE_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
202 |
The request has been accepted for processing, but processing has not yet completed. |
Get an agent run
GET /api/v1/agent/conversations/{conversation}/runs/{run}
Operation ID: getAgentRun
Effect: read
Confirmation: never
Required privilege: VIEW_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
run |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Cancel an agent run
POST /api/v1/agent/conversations/{conversation}/runs/{run}/cancel
Operation ID: cancelAgentRun
Effect: write
Confirmation: conditional
Required privilege: USE_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
run |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Responses
| Status | Description |
|---|---|
202 |
The request has been accepted for processing, but processing has not yet completed. |
List agent run events
GET /api/v1/agent/conversations/{conversation}/runs/{run}/events
Operation ID: listAgentEvents
Effect: read
Confirmation: never
Required privilege: VIEW_AGENT
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
run |
path | Yes | string | |
accept |
header | No | string | |
Last-Event-ID |
header | No | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Common error responses
These error responses apply to every operation on this page.
| Status | Description |
|---|---|
400 |
The server could not understand the request due to invalid syntax. |
401 |
Access is unauthorized. |
403 |
Access is forbidden. |
404 |
The server cannot find the requested resource. |
409 |
The request conflicts with the current state of the server. |
412 |
Precondition failed. |
413 |
Client error |
415 |
Client error |
422 |
Client error |
429 |
Client error |
500 |
Server error |
502 |
Server error |
503 |
Service unavailable. |