Create an agent

A Raíz agent talks to your organization’s contacts, on phone calls (voice) or on WhatsApp and web chat (text). This guide creates a text agent with raiz.agents.create, then reads it, changes it and puts it on a channel.

Before you start

You need a credential for your organization that holds raiz:agents:write (see Authentication). The examples read an API key from ARBOL_API_KEY.

Each accepts an API key, a machine token or a person’s sign-in. An API key needs the scope among those chosen when it was created; a person’s token counts only as far as their roles grant it.

Create the agent

Only modality and name are required. Add instructions, language and timeZone so the agent knows its job and speaks in the right language and time zone:

curl https://api.getarbol.com/v1/raiz/agents \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "modality": "text",
    "name": "Appointment reminders",
    "instructions": "You remind patients of Example Clinic about upcoming appointments and confirm whether they will attend. You never give medical advice.",
    "language": "es-CO",
    "timeZone": "America/Bogota"
  }'

The body accepts only the fields its schema declares; any other field answers 400 INVALID_INPUT. The optional ones:

A successful call answers 200 with the agent in data. The response below is abridged: the full object also carries status, ready, settings, skills, integrationSkills and toolCount.

{
  "success": true,
  "data": {
    "id": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b",
    "name": "Appointment reminders",
    "modality": "text",
    "version": 1,
    "instructions": "You remind patients of Example Clinic about upcoming appointments and confirm whether they will attend. You never give medical advice.",
    "language": "es-CO",
    "timeZone": "America/Bogota",
    "firstMessage": null,
    "description": null,
    "synced": true,
    "syncErrorCode": null,
    "channelCount": 0,
    "channels": [],
    "knowledgeDocumentIds": [],
    "integrationTools": [],
    "createdAt": "2026-10-30T15:04:05Z",
    "updatedAt": "2026-10-30T15:04:05Z"
  },
  "error": null,
  "metadata": { "requestId": "3f6c2a8e-1b4d-4e7a-9c0f-5d2e8b1a7c64" }
}

Keep data.id: every other operation on the agent takes it as agentId. Two fields say where the agent stands:

• ready: whether it can hold conversations. It must be active and have instructions, and a voice agent must also be published for calls.
• synced: whether calls already use the current version. Voice agents are published in the background, so check it after each change; syncErrorCode says why publishing failed. It is always true for text agents.

Read it back

raiz.agents.get takes agentId in the URL path and answers the agent’s complete setup:

curl "https://api.getarbol.com/v1/raiz/agents/agt_01jd8x5k2m7q9r3t6v8w0y4z1b" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

To find agents, raiz.agents.list filters by status, modality and q (the name, ignoring accents and case), newest first:

curl "https://api.getarbol.com/v1/raiz/agents?modality=text&q=reminders" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

The agents are in data.data, 25 per page by default; pass data.pageInfo.nextCursor as cursor for the next page. See Pagination.

Update it

Put agentId in the URL path and send the fields to change and, as expectedVersion, the version you read:

curl https://api.getarbol.com/v1/raiz/agents/agt_01jd8x5k2m7q9r3t6v8w0y4z1b \
  --request PATCH \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "expectedVersion": 1,
    "instructions": "You remind patients of Example Clinic about upcoming appointments, confirm whether they will attend and pass reschedule requests to the team. You never give medical advice."
  }'

• Fields you leave out stay as they are, and null clears a field that accepts it.
• settings, integrationTools, integrationSkills, skills and knowledgeDocumentIds replace the whole value. Read the agent first and send the complete new value; settings you leave out return to their default.
• With expectedVersion, the change applies only if nobody changed the agent since you read it. Otherwise it answers 409 VERSION_CONFLICT: read the agent again and reapply your change.
• "status": "paused" stops the agent from answering and calling.
• modality changes only while the agent has no channels and no published voice line.

Put it on a channel

Assign the agent to a WhatsApp number, phone number or web chat widget so it answers there. Find the channel with raiz.channels.list, then send its id and the agent’s to raiz.channels.update:

{
  "channelId": "chn_01jd8x6b3c4d5e6f7g8h9j0k1m",
  "agentId": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b"
}

The agent’s modality must fit the channel: text for WhatsApp and web chat, voice for phone numbers.

Errors

Every failure carries error.code, error.message, error.retryable and metadata.requestId. See Responses and errors.