Skip to main content
Client Update Agent
curl --request PATCH \
  --url https://agents-api.kolena.com/api/v1/client/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {}
}'
{
  "id": 123,
  "workspace_id": 123,
  "name": "<string>",
  "objective": "<string>",
  "created": "2023-11-07T05:31:56Z",
  "updated": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "n_runs": 123,
  "prompts": [
    {
      "id": 123,
      "name": "<string>",
      "created": "2023-11-07T05:31:56Z",
      "updated": "2023-11-07T05:31:56Z",
      "options": {},
      "documents": [
        {
          "filename": "<string>"
        }
      ],
      "input_prompt_ids": [
        123
      ],
      "last_updated_by": "<string>"
    }
  ],
  "output_templates": [
    {
      "id": 123,
      "filename": "<string>",
      "created": "2023-11-07T05:31:56Z",
      "updated": "2023-11-07T05:31:56Z"
    }
  ],
  "metadata": {}
}
Rate Limit: This endpoint is limited to requests per minute per user.

​
Overview

Update properties of an Agent. Only metadata is currently supported for updates.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>. The <token> represents your API key, which must be acquired from the Kolena platform.

Path Parameters

​
agent_id
integer
required

Body

application/json
​
metadata
Metadata · object

Object of key-value pairs; useful for organizing, filtering, and tracking purposes. Metadata keys must be strings. Metadata values can be primitives (strings, numbers, booleans, or null) or lists of primitives. Updating metadata completely replaces the existing metadata on that Agent (not merged). To remove all metadata from an Agent, send an empty object {} as the metadata value.

Response

Successful Response

​
id
integer
required

The ID of this Agent.

​
workspace_id
integer
required

The ID of the workspace hosting this Agent.

​
name
string
required

The name of this Agent.

​
objective
string
required

A short description of this Agent's objective, e.g. "Extract key information from leases and addendum documents".

​
created
string<date-time>
required

When this Agent was created, formatted as an ISO 8601 timestamp (e.g. 2025-12-31T10:15:45+00:00)

​
updated
string<date-time>
required

When this Agent was last updated, formatted as an ISO 8601 timestamp (e.g. 2025-12-31T10:15:45+00:00)

​
created_by
string
required

The email address of the user who created this Agent.

​
n_runs
integer
required

The number of times this Agent has been Run.

​
prompts
Prompt · object[]
required

The Prompts configured for this Agent.

Example:
[
  {
    "created": "2025-01-01T00:00:00",
    "documents": [],
    "id": 1,
    "input_prompt_ids": [],
    "last_updated_by": "user@example.com",
    "name": "Account number",
    "options": {
      "code_generation": false,
      "enhanced_vision": false,
      "prompt": "Find the account number",
      "type": "string",
      "web_search": false
    },
    "updated": "2025-01-01T00:00:00"
  },
  {
    "created": "2025-01-01T00:00:00",
    "documents": [],
    "id": 2,
    "input_prompt_ids": [1],
    "last_updated_by": "user@example.com",
    "name": "Account info",
    "options": {
      "code_generation": false,
      "enhanced_vision": false,
      "fields": ["full name", "address"],
      "prompt": "Extract form fields using account number: <kolena-prompt id='1'/>",
      "type": "form",
      "web_search": false
    },
    "updated": "2025-01-02T00:00:00"
  }
]
​
output_templates
OutputTemplate · object[]

The Templates configured for this Agent, used to generate formatted output documents.

​
metadata
Metadata · object

Metadata for this Agent.

Example:
{
  "department": "finance",
  "environment": "production",
  "tags": ["invoice-processing", "high-priority"],
  "version": 2
}