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.

4 min read Updated

List agents

GET/v1/agents

Permission agents:read

The agents this integration may use.

Parameters

ParameterTypeDescription
limitintegerqueryItems per page. Default 25. 1 to 100.
afterstringqueryThe next_cursor of the previous page. Up to 200 characters.

Response 200 OK

FieldTypeDescription
dataarray of objectsThe items on this page.
data[].api_accessbooleanfalse: the plan of this agent does not include the API; calls for it answer 403 plan_restricted. Default true.
data[].created_atstring or nullWhen it was created, in UTC (ISO 8601).
data[].idstringAgent id. Use it as agent_id in paths and in POST /v1/responses.
data[].namestring or nullName of the agent.
data[].objectstringAlways agent.
data[].statusstring or nullSet-up state of the agent, completed when it is ready.
data[].website_urlstring or nullThe website the agent was created for.
next_cursorstring or nullPass it as after to get the next page. null on the last page.
objectstringAlways list.

Example request

curl "https://api.ultimo-bots.com/v1/agents" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

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}

Permission agents:read

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.

Response 200 OK

FieldTypeDescription
api_accessbooleanfalse: the plan of this agent does not include the API; calls for it answer 403 plan_restricted. Default true.
created_atstring or nullWhen it was created, in UTC (ISO 8601).
idstringAgent id. Use it as agent_id in paths and in POST /v1/responses.
namestring or nullName of the agent.
objectstringAlways agent.
statusstring or nullSet-up state of the agent, completed when it is ready.
website_urlstring or nullThe 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"

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

Permission agents:context:read

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
business_contextstringThe Business Context: what the agent knows about the business.
versionintegerPass 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"

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

Permission agents:context:writeNeeds an integration with read and change access

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
Idempotency-KeystringheaderAny 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

FieldTypeDescription
business_contextrequiredstringThe whole text (replaces it). Empty clears it. Up to 1000 characters.
expected_versioninteger or nullVersion from GET; a changed version answers 409. At least 1.

Response 200 OK

FieldTypeDescription
contextobjectThe Business Context after the change.
context.agent_idstringThe agent's id.
context.business_contextstringThe Business Context: what the agent knows about the business.
context.versionintegerPass it as expected_version when you replace the text.
replayedbooleantrue: 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
}'

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

Permission agents:behaviors:read

The owner's behavior rules and the platform's system instructions, as the AI Studio shows them.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
allowanceobjectHow many behavior rules the plan allows and how many exist.
allowance.can_addbooleantrue while the plan allows another rule.
allowance.current_countintegerRules the agent has.
allowance.limitintegerRules the plan allows.
behaviorsarray of objectsThe owner's behavior rules as the AI Studio shows them.
behaviors[].enabledbooleantrue when the rule applies.
behaviors[].idstringId of the rule.
behaviors[].textstringThe rule itself.
behaviors[].titlestringShort name of the rule.
definition_versionintegerVersion of the agent's AI Studio definition. It rises with every change.
system_instructionsarray of objectsThe platform's built-in instructions and whether they are on.
system_instructions[].enabledbooleantrue when the instruction is on.
system_instructions[].idstringKey of the instruction.
system_instructions[].summarystringWhat the instruction does.
system_instructions[].titlestringName 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"

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.

Next steps