Agents
The agents an integration may use (all agents of the workspace, or the ones chosen when the integration was created), with their Business Context and behavior rules.
- GET
/v1/agentsList agents - GET
/v1/agents/{agent_id}Get an agent - GET
/v1/agents/{agent_id}/business-contextRead the Business Context - PUT
/v1/agents/{agent_id}/business-contextReplace the Business Context - GET
/v1/agents/{agent_id}/behaviorsRead the behavior rules
List agents
GET/v1/agents
The agents this integration may use.
Parameters
| Parameter | Type | Description |
|---|---|---|
limit | integerquery | Items per page. Default 25. 1 to 100. |
after | stringquery | The next_cursor of the previous page. Up to 200 characters. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
data | array of objects | The items on this page. |
data[].api_access | boolean | false: the plan of this agent does not include the API; calls for it answer 403 plan_restricted. Default true. |
data[].created_at | string or null | When it was created, in UTC (ISO 8601). |
data[].id | string | Agent id. Use it as agent_id in paths and in POST /v1/responses. |
data[].name | string or null | Name of the agent. |
data[].object | string | Always agent. |
data[].status | string or null | Set-up state of the agent, completed when it is ready. |
data[].website_url | string or null | The website the agent was created for. |
next_cursor | string or null | Pass it as after to get the next page. null on the last page. |
object | string | Always list. |
Example request
curl "https://api.ultimo-bots.com/v1/agents" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"data": [
{
"api_access": true,
"created_at": "2026-11-01T09:00:00Z",
"id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"name": "Sonnenhang Winery",
"object": "agent",
"status": "completed",
"website_url": "https://example.com"
}
],
"next_cursor": null,
"object": "list"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Get an agent
GET/v1/agents/{agent_id}
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
api_access | boolean | false: the plan of this agent does not include the API; calls for it answer 403 plan_restricted. Default true. |
created_at | string or null | When it was created, in UTC (ISO 8601). |
id | string | Agent id. Use it as agent_id in paths and in POST /v1/responses. |
name | string or null | Name of the agent. |
object | string | Always agent. |
status | string or null | Set-up state of the agent, completed when it is ready. |
website_url | string or null | The website the agent was created for. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"api_access": true,
"created_at": "2026-11-01T09:00:00Z",
"id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"name": "Sonnenhang Winery",
"object": "agent",
"status": "completed",
"website_url": "https://example.com"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Read the Business Context
GET/v1/agents/{agent_id}/business-context
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
business_context | string | The Business Context: what the agent knows about the business. |
version | integer | Pass it as expected_version when you replace the text. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/business-context" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/business-context",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/business-context", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"business_context": "Sonnenhang Winery sells wines from the Palatinate. Farm shop open Mon-Fri 9-18, Sat 9-14.",
"version": 5
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Replace the Business Context
PUT/v1/agents/{agent_id}/business-context
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Idempotency-Key | stringheader | Any unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries. |
Request body
| Field | Type | Description |
|---|---|---|
business_contextrequired | string | The whole text (replaces it). Empty clears it. Up to 1000 characters. |
expected_version | integer or null | Version from GET; a changed version answers 409. At least 1. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
context | object | The Business Context after the change. |
context.agent_id | string | The agent's id. |
context.business_context | string | The Business Context: what the agent knows about the business. |
context.version | integer | Pass it as expected_version when you replace the text. |
replayed | boolean | true: this Idempotency-Key was used before, the stored result is returned. |
Example request
curl -X PUT "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/business-context" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"business_context": "Sonnenhang Winery sells wines from the Palatinate. Farm shop open Mon-Sat 9-18.",
"expected_version": 5
}'import os, uuid, requests
r = requests.put(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/business-context",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"business_context": "Sonnenhang Winery sells wines from the Palatinate. Farm shop open Mon-Sat 9-18.",
"expected_version": 5,
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/business-context", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"business_context": "Sonnenhang Winery sells wines from the Palatinate. Farm shop open Mon-Sat 9-18.",
"expected_version": 5
})
});
console.log(res.status, await res.json());Response 200 OK
{
"context": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"business_context": "Sonnenhang Winery sells wines from the Palatinate. Farm shop open Mon-Fri 9-18, Sat 9-14.",
"version": 6
},
"replayed": false
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
Read the behavior rules
GET/v1/agents/{agent_id}/behaviors
The owner's behavior rules and the platform's system instructions, as the AI Studio shows them.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
allowance | object | How many behavior rules the plan allows and how many exist. |
allowance.can_add | boolean | true while the plan allows another rule. |
allowance.current_count | integer | Rules the agent has. |
allowance.limit | integer | Rules the plan allows. |
behaviors | array of objects | The owner's behavior rules as the AI Studio shows them. |
behaviors[].enabled | boolean | true when the rule applies. |
behaviors[].id | string | Id of the rule. |
behaviors[].text | string | The rule itself. |
behaviors[].title | string | Short name of the rule. |
definition_version | integer | Version of the agent's AI Studio definition. It rises with every change. |
system_instructions | array of objects | The platform's built-in instructions and whether they are on. |
system_instructions[].enabled | boolean | true when the instruction is on. |
system_instructions[].id | string | Key of the instruction. |
system_instructions[].summary | string | What the instruction does. |
system_instructions[].title | string | Name of the instruction. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/behaviors" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/behaviors",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/behaviors", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"allowance": {
"can_add": true,
"current_count": 1,
"limit": 30
},
"behaviors": [
{
"enabled": true,
"id": "b1",
"text": "Address customers formally.",
"title": "Formal address"
}
],
"definition_version": 3,
"system_instructions": [
{
"enabled": true,
"id": "stay_on_topic",
"summary": "Helps only with the business's topics and politely steers back.",
"title": "Stay on topic"
}
]
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.