List Agents
Find the organization's Agents (the Dashboard calls them Workers), newest first, to get the agentId you need before reading or changing one. Filter by status (active, paused), modality (voice for calls, text for WhatsApp and web chat) or q (name). Each item shows whether it is ready to hold conversations and, for voice Agents, synced. Next: get_agent for its full setup, or list_conversations with agentId for what it talked about.
- Scopes: any one of
raiz:agents:read,raiz:agents:write - Credentials: an API key, a client-credentials token or a person's access token
- Effect: read-only; safe to retry
- Limits: response up to 1 MB
- CLI:
arbol raiz agents list· MCP tool:raiz_agents_list
https://api.getarbol.com/v1/raiz/agentsAuthorization
- Authorizationstringrequired
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopesraiz:agents:read,raiz:agents:write. Get an API key.
Query parameters
Returns
200
Successful operation.
- dataobjectrequired
- dataarray ofobjectrequired
Items admitted by this resource contract within the verified organization.
- knowledgeDocumentIdsarray ofstringrequired
The Knowledge documents the Agent consults.
pattern: ^(?:kdc_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:con)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$ - settingsobjectrequired
- recoveryManagerobject | nullrequired
Optional WhatsApp recovery advisor. Null or enabled=false disables it. A journaled evidence check precedes any paid review. One tool-free model call per turn before autonomous escalation or after terminal provider failure; unresolved terminal recovery hands off. Completed handoffs and conservatively recognized human requests bypass generation. Model selects the existing provider route. Prices must be conservative upper bounds including provider overhead; missing or invalid prices disable recovery. The cost bound covers only the advisor. No tools or automatic provider retries.
- modelarbolito/agileorarbolito/balancedorarbolito/advancedorarbolito/toprequired
arbolito/agile: quickest and least expensive, for direct conversations.arbolito/balanced: more deliberate answers at moderate cost.arbolito/advanced: strong reasoning for complex instructions and many tools, with an adjustablereasoningEffort.arbolito/top: the most capable, for the hardest cases, with an adjustablereasoningEffortup toxhigh. Every tier reads images and PDF documents. - advisorAgentIdoptionalstring | null
Optional active text Agent in the same organization, other than this Agent, whose instructions and procedures provide specialist guidance. The configured recovery model and cost bounds stay unchanged; no specialist tools or conversation history are accessed.
pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- attachmentReadervisionorocrornullrequired
Text Agents on WhatsApp. Who reads an image or PDF when the Agent calls
read_attachment:vision(a vision model describes and transcribes it, with a stronger one when the first reads nothing) orocr(text recognition, which also answers thefieldsthe Agent asks for, each null when absent or unclear; the vision model reads the file when recognition cannot). Withocrthe Agent sees files as markers and reads them withread_attachment; withvision, tiers that read files themselves see the original. Null:vision. - budgetExhaustedMessagestring | nullrequired
Text Agents on WhatsApp. What the contact reads when the Agent has used its
monthlyTokenBudget: the conversation then goes to the team, as an escalation does, and the Agent writes nothing until the budget is raised or the month ends. Null:handoffMessage, including an empty notice when disabled.maxLength: 1000 · minLength: 1 - closingMessagestring | nullrequired
Text Agents on WhatsApp. After a reply that completed an action (an integration tool that changes data succeeded), explicitly finished the case with end_conversation and left nothing pending (no question, no offered choices, no handoff), a contact message that only thanks or closes («gracias», «ok», «listo», an emoji) gets this text at once, without the model; the Agent still reads both in its next turn. Write it in the Agent's language and ask nothing in it. Null: the Agent answers such messages itself.
maxLength: 1000 · minLength: 1 - evalGateboolean | nullrequired
Text and voice Agents. When true, an
updateAgentthat changes what the model reads (instructions, procedures, connection procedures,modelorreasoningEffort) must sendevalRunId: a completedcreateEvalRunof this Agent with exactly that content, in which every case passed (EVAL_GATE_UNMET otherwise). Null: no requirement. - handoffMessagestring | nullrequired
Text Agents on WhatsApp. The notice appended after an escalation or a requested human handoff. Null: the current localized review notice or the case-specific notice supplied under the Agent's instructions. An empty string disables the notice; the handoff and pause still happen. The model does not write this notice.
maxLength: 1000 - humanReplyTimeoutMinutesinteger | nullrequired
Text Agents on WhatsApp. After a manual takeover, resume automatic replies when the contact's newest message waits this many minutes. An Agent handoff always stays with the team until a person explicitly resumes AI. Null: only a person resumes automatic replies.
maximum: 1440 · minimum: 1 - investigationsEnabledboolean | nullrequired
Opt this Agent into internal root-cause investigations of tool failures, human escalations, failed outcomes and negative feedback. Incidents are grouped only with participating Agents in the same organization. Null or false: disabled. Turning this off stops new events and pending dispatch when no participating Agent remains; an already active investigation may finish.
- modelarbolito/agileorarbolito/balancedorarbolito/advancedorarbolito/topornullrequired
Text Agents. The tier that writes replies.
arbolito/agile: quickest and least expensive, for direct conversations.arbolito/balanced: more deliberate answers at moderate cost.arbolito/advanced: strong reasoning for complex instructions and many tools, with an adjustablereasoningEffort.arbolito/top: the most capable, for the hardest cases, with an adjustablereasoningEffortup toxhigh. Every tier reads images and PDF documents. Null: the default, asarbolito/agile. - modelTrialrequired}
One of the following:
- RaizAgentModelTrial
- modelarbolito/agileorarbolito/balancedorarbolito/advancedorarbolito/toprequired
The tier the trial's conversations are answered with.
- percentintegerrequired
The share of new conversations in the trial, in percent.
maximum: 50 · minimum: 1 - reasoningEffortnoneorlowormediumorhighorxhighornullrequired
The trial tier's reasoning, as
reasoningEffort. Null: the tier's default.
- null
- monthlyTokenBudgetinteger | nullrequired
Text Agents. Tokens (input, cached input included, plus output) the Agent may use per calendar month (UTC), on every channel. On WhatsApp, a reply that would start past it does not run: the contact reads
budgetExhaustedMessageand the team continues; at 80 % the API logs an alert once a month. Null: no limit.maximum: 1000000000000 · minimum: 10000 - pauseOnHumanReplyboolean | nullrequired
Text Agents on WhatsApp: pause automatic replies when a live WhatsApp Business App message that says something (not a reaction, an edit or a deletion) proves a person took over. Null: disabled. The recipient stays paused until resumed or until that conversation closes; their next conversation starts with the AI.
- policyrequired}
One of the following:
- RaizAgentTurnPolicy
- maxOutputTokensoptionalinteger
Output tokens per model call, reasoning included. Default 4096.
maximum: 16384 · minimum: 256 - maxStepsoptionalinteger
Model calls one reply may make: tool rounds plus the answer. The last call never offers tools, so the contact always gets an answer. Default 16.
maximum: 32 · minimum: 2 - maxWritesPerStepoptionalinteger
Integration tool calls that change data (
effect: write) one model step may run. A further one is refused with a fixed reason, and the Agent runs it in its next step after reading the first result. 0 forbids writes. Default 1.maximum: 3 · minimum: 0 - repeatedReadLimitoptionalinteger
Identical reads (same tool, same arguments) one reply may run; the next is refused with a fixed reason. Omitted: no limit, as an Agent that polls a pending operation repeats one read on purpose.
maximum: 10 · minimum: 1 - toolsoptionalobject
Per-tool rules, by the name the model sees.
- null
- pollPendingOperationsboolean | nullrequired
Text Agents on WhatsApp: when a reply ends while an integration answered that its work is still pending (
status: pendingwith anoperationId) and the same connection offersgetOperation, Raíz checks it again on its own and the Agent answers with the result, without waiting for the contact to write. Null: disabled. - reasoningEffortnoneorlowormediumorhighorxhighornullrequired
Text Agents whose tier reasons (
arbolito/advanced,arbolito/top, or an Agent already running a model that reasons):noneanswers fastest,highdeliberates most, andxhigh, onarbolito/advancedandarbolito/top, deliberates past it. Null: the tier's default. A tier that does not reason refuses it (AGENT_SETTINGS_INVALID). - voicerequired}
One of the following:
- RaizAgentVoiceSettings
- keywordsarray ofstringrequired
Names and terms the transcriber should favor (people, places, products).
maxLength: 64 · minLength: 1 - maxDurationSecondsinteger | nullrequired
Hard limit of one call. Null: 600 seconds.
maximum: 7200 · minimum: 30 - recordCallsbooleanrequired
Keep the call recording (copied to Raíz after the call).
- silenceEndCallTimeoutSecondsinteger | nullrequired
Hang up after this much caller silence. Null: the platform default.
maximum: 600 · minimum: 10 - similarityBoostnumber | nullrequiredmaximum: 1 · minimum: 0
- speednumber | nullrequiredmaximum: 1.2 · minimum: 0.7
- stabilitynumber | nullrequiredmaximum: 1 · minimum: 0
- turnTimeoutSecondsinteger | nullrequired
Seconds to wait for the caller before prompting again. Null: the platform default.
maximum: 30 · minimum: 1 - llmarbolito/agileorarbolito/balancedorarbolito/advancedorarbolito/topornullrequired
The tier the Agent thinks with on calls.
arbolito/agile: quickest and least expensive, for direct conversations.arbolito/balanced: more deliberate answers at moderate cost.arbolito/advanced: strong reasoning for complex instructions and many tools, with an adjustablereasoningEffort.arbolito/top: the most capable, for the hardest cases, with an adjustablereasoningEffortup toxhigh. Every tier reads images and PDF documents. Null: the default, asarbolito/agile. - voiceIdstring | nullrequired
A voice from
listVoices. Null uses the default voice.pattern: ^vce_[A-Za-z0-9_-]{20,156}$ - redactKeypadInputoptionalboolean
Replace numbers entered on the phone keypad with <REDACTED> in stored transcripts and analysis. False (the default) keeps them visible. Applies to future calls; the Agent still receives the digits during the call.
default: false - reasoningEffortoptionalnoneorminimalorlowormediumorhighorxhigh+2 more
Reasoning effort on calls, when supported by the selected model. Null uses the model default.
- responseDelayMessagesoptionalboolean
Speak a short contextual message while preparing a slow response. False disables automatic delay messages. Omitted preserves the current runtime setting.
- toolCallSoundoptionaltypingornull
typing: Play a typing sound while this Agent's tools execute. Null disables the sound; omitted preserves the current setting. Applies to future calls after synchronization.
- backupModelsoptionalarray | null
Ordered backup tiers when the primary voice model fails. Null restores the runtime default. Omitted preserves the current runtime setting. An empty list is not allowed because calls need a fallback.
- null
400
INVALID_INPUT: The request does not match the published schema.INVALID_CURSOR: The cursor is malformed or belongs to a different list.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
401
UNAUTHORIZED: A valid access token is required.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
403
FORBIDDEN: The token does not authorize this operation.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
404
NOT_FOUND: The requested operation does not exist.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
405
HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
413
REQUEST_TOO_LARGE: The request exceeds the allowed size.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
415
UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
429
RATE_LIMITED: The request rate limit was exceeded. Try again later.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
500
INTERNAL_ERROR: The service could not complete the operation.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
502
OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
503
UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.VOICE_UNAVAILABLE: Calls are unavailable right now. Try again in a few minutes.INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
504
UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object