PATCH /v1/agents/{id}

Actualizar un agente

curl --request PATCH \
  --url https://api.keebai.com/v1/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "model": "<string>",
  "language": "es-CL",
  "timezone": "America/Santiago",
  "prompts": [
    {
      "section": "business_context",
      "markdown": "# Quienes somos\n\nBarberia en Providencia, atendemos con hora.",
      "label": "<string>"
    }
  ],
  "channels": [
    "<string>"
  ],
  "reengagement": {},
  "tools": [
    "<string>"
  ],
  "knowledge_node_ids": [
    "<string>"
  ],
  "is_active": true
}
'

import requests

url = "https://api.keebai.com/v1/agents/{id}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "model": "<string>",
    "language": "es-CL",
    "timezone": "America/Santiago",
    "prompts": [
        {
            "section": "business_context",
            "markdown": "# Quienes somos

Barberia en Providencia, atendemos con hora.",
            "label": "<string>"
        }
    ],
    "channels": ["<string>"],
    "reengagement": {},
    "tools": ["<string>"],
    "knowledge_node_ids": ["<string>"],
    "is_active": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    model: '<string>',
    language: 'es-CL',
    timezone: 'America/Santiago',
    prompts: [
      {
        section: 'business_context',
        markdown: '# Quienes somos\n\nBarberia en Providencia, atendemos con hora.',
        label: '<string>'
      }
    ],
    channels: ['<string>'],
    reengagement: {},
    tools: ['<string>'],
    knowledge_node_ids: ['<string>'],
    is_active: true
  })
};

fetch('https://api.keebai.com/v1/agents/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/agents/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'model' => '<string>',
    'language' => 'es-CL',
    'timezone' => 'America/Santiago',
    'prompts' => [
        [
                'section' => 'business_context',
                'markdown' => '# Quienes somos

Barberia en Providencia, atendemos con hora.',
                'label' => '<string>'
        ]
    ],
    'channels' => [
        '<string>'
    ],
    'reengagement' => [
        
    ],
    'tools' => [
        '<string>'
    ],
    'knowledge_node_ids' => [
        '<string>'
    ],
    'is_active' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/agents/{id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"es-CL\",\n  \"timezone\": \"America/Santiago\",\n  \"prompts\": [\n    {\n      \"section\": \"business_context\",\n      \"markdown\": \"# Quienes somos\\n\\nBarberia en Providencia, atendemos con hora.\",\n      \"label\": \"<string>\"\n    }\n  ],\n  \"channels\": [\n    \"<string>\"\n  ],\n  \"reengagement\": {},\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"is_active\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.keebai.com/v1/agents/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"es-CL\",\n  \"timezone\": \"America/Santiago\",\n  \"prompts\": [\n    {\n      \"section\": \"business_context\",\n      \"markdown\": \"# Quienes somos\\n\\nBarberia en Providencia, atendemos con hora.\",\n      \"label\": \"<string>\"\n    }\n  ],\n  \"channels\": [\n    \"<string>\"\n  ],\n  \"reengagement\": {},\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"is_active\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/agents/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"es-CL\",\n  \"timezone\": \"America/Santiago\",\n  \"prompts\": [\n    {\n      \"section\": \"business_context\",\n      \"markdown\": \"# Quienes somos\\n\\nBarberia en Providencia, atendemos con hora.\",\n      \"label\": \"<string>\"\n    }\n  ],\n  \"channels\": [\n    \"<string>\"\n  ],\n  \"reengagement\": {},\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"is_active\": true\n}"

response = http.request(request)
puts response.read_body

{
  "agent": {
    "id": "<string>",
    "name": "<string>",
    "model": "<string>",
    "voice_response_enabled": true,
    "description": "<string>",
    "avatar_url": "<string>",
    "created_at": "<string>"
  }
}

PATCH

agents

{id}

Actualizar un agente

curl --request PATCH \
  --url https://api.keebai.com/v1/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "model": "<string>",
  "language": "es-CL",
  "timezone": "America/Santiago",
  "prompts": [
    {
      "section": "business_context",
      "markdown": "# Quienes somos\n\nBarberia en Providencia, atendemos con hora.",
      "label": "<string>"
    }
  ],
  "channels": [
    "<string>"
  ],
  "reengagement": {},
  "tools": [
    "<string>"
  ],
  "knowledge_node_ids": [
    "<string>"
  ],
  "is_active": true
}
'

import requests

url = "https://api.keebai.com/v1/agents/{id}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "model": "<string>",
    "language": "es-CL",
    "timezone": "America/Santiago",
    "prompts": [
        {
            "section": "business_context",
            "markdown": "# Quienes somos

Barberia en Providencia, atendemos con hora.",
            "label": "<string>"
        }
    ],
    "channels": ["<string>"],
    "reengagement": {},
    "tools": ["<string>"],
    "knowledge_node_ids": ["<string>"],
    "is_active": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    model: '<string>',
    language: 'es-CL',
    timezone: 'America/Santiago',
    prompts: [
      {
        section: 'business_context',
        markdown: '# Quienes somos\n\nBarberia en Providencia, atendemos con hora.',
        label: '<string>'
      }
    ],
    channels: ['<string>'],
    reengagement: {},
    tools: ['<string>'],
    knowledge_node_ids: ['<string>'],
    is_active: true
  })
};

fetch('https://api.keebai.com/v1/agents/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/agents/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'model' => '<string>',
    'language' => 'es-CL',
    'timezone' => 'America/Santiago',
    'prompts' => [
        [
                'section' => 'business_context',
                'markdown' => '# Quienes somos

Barberia en Providencia, atendemos con hora.',
                'label' => '<string>'
        ]
    ],
    'channels' => [
        '<string>'
    ],
    'reengagement' => [
        
    ],
    'tools' => [
        '<string>'
    ],
    'knowledge_node_ids' => [
        '<string>'
    ],
    'is_active' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/agents/{id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"es-CL\",\n  \"timezone\": \"America/Santiago\",\n  \"prompts\": [\n    {\n      \"section\": \"business_context\",\n      \"markdown\": \"# Quienes somos\\n\\nBarberia en Providencia, atendemos con hora.\",\n      \"label\": \"<string>\"\n    }\n  ],\n  \"channels\": [\n    \"<string>\"\n  ],\n  \"reengagement\": {},\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"is_active\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.keebai.com/v1/agents/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"es-CL\",\n  \"timezone\": \"America/Santiago\",\n  \"prompts\": [\n    {\n      \"section\": \"business_context\",\n      \"markdown\": \"# Quienes somos\\n\\nBarberia en Providencia, atendemos con hora.\",\n      \"label\": \"<string>\"\n    }\n  ],\n  \"channels\": [\n    \"<string>\"\n  ],\n  \"reengagement\": {},\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"is_active\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/agents/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"es-CL\",\n  \"timezone\": \"America/Santiago\",\n  \"prompts\": [\n    {\n      \"section\": \"business_context\",\n      \"markdown\": \"# Quienes somos\\n\\nBarberia en Providencia, atendemos con hora.\",\n      \"label\": \"<string>\"\n    }\n  ],\n  \"channels\": [\n    \"<string>\"\n  ],\n  \"reengagement\": {},\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"is_active\": true\n}"

response = http.request(request)
puts response.read_body

{
  "agent": {
    "id": "<string>",
    "name": "<string>",
    "model": "<string>",
    "voice_response_enabled": true,
    "description": "<string>",
    "avatar_url": "<string>",
    "created_at": "<string>"
  }
}

Partial update. Only the fields present in the body change; everything else is left alone. To change one prompt section, use PUT /v1/agents/{id}/prompts/{section} instead. Sending prompts here replaces them all, which is what you want when your system owns the whole prompt and a mistake when it does not.

Endpoint

PATCH https://api.keebai.com/v1/agents/{id}

Required scope

agents:write

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer kbai_pk_<token>`
`Content-Type`	Yes	`application/json`

Path parameters

Parameter	Type	Description
`id`	`string`	`ObjectId` of the agent.

Body

Every field is optional.

Field	Type	Description
`name`	`string`	Up to 150 characters, non-empty.
`description`	`string`	Up to 500 characters.
`language`	`string`	Locale, for example `es-CL`.
`timezone`	`string`	IANA name.
`goal`	`object`	`{ type, instructions? }`.
`prompts`	`array`	Replaces every section.
`channels`	`string[]`	Channel types from the catalogue.
`reengagement`	`object`	Cadence for coming back to a cold conversation.
`tools`	`string[]`	`ObjectId`s of webhook tools.
`model`	`string`	Model id. Validated only when it differs from the current one.
`knowledge_node_ids`	`string[]`	Replaces the whole list. Send `[]` to unassign everything.
`is_active`	`boolean`	`false` stops the agent answering without deleting anything.

Example request

curl -X PATCH https://api.keebai.com/v1/agents/6650a1b2c3d4e5f6a7b8c9d0 \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gemini-2.5-pro", "is_active": true }'

const resp = await fetch(
  "https://api.keebai.com/v1/agents/6650a1b2c3d4e5f6a7b8c9d0",
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ model: "gemini-2.5-pro" }),
  },
);
const { agent } = await resp.json();

import os, requests

resp = requests.patch(
    "https://api.keebai.com/v1/agents/6650a1b2c3d4e5f6a7b8c9d0",
    headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
    json={"model": "gemini-2.5-pro"},
    timeout=10,
)
resp.raise_for_status()
agent = resp.json()["agent"]

Response

200 OK

The full agent, same shape as GET /v1/agents/{id}.

400 Bad Request

A field over its length limit, a malformed ObjectId, an unknown property, or INVALID_MODEL when the new model is not supported.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the agents:write scope.

404 Not Found

No agent with that id in the token’s company and project.

502 Bad Gateway

The agent service is unreachable.

Operational notes

knowledge_node_ids replaces, it does not append. Sending one id leaves the agent with exactly that one. Read the current list from GET /v1/agents/{id} and send the union if you mean to add.
The model is only validated when it changes. An agent already configured with a model that has since been retired keeps working through updates that do not touch model, and starts failing validation the moment you send it explicitly.
is_active: false is the reversible way to take an agent out of service. It keeps every section, version and knowledge assignment; deleting does not.
Changing goal.type changes which tools the agent can use. It is not a rename: an agent moved from informing to booking needs the services and availability behind it to exist.
Removing a channel stops it answering there, and a customer who writes gets nothing back.
Omitting a field and sending null are not the same. Omit it to leave the value alone. null is not accepted for these fields.
A change takes effect within about fifteen minutes at worst. The rendered prompt and bound tools are cached per agent; the cache is dropped on every write, but a request already in flight can still answer with the previous configuration.

Authorizations

Authorization

string

header

required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Path Parameters

string

required

Body

application/json

name

string

Maximum string length: 150

description

string

Maximum string length: 500

model

string

Identificador del modelo. Se valida solo si cambia respecto del actual.

language

string

Example:

"es-CL"

timezone

string

Example:

"America/Santiago"

goal

object

Show child attributes

prompts

object[]

REEMPLAZA todas las secciones. Para cambiar una sola sin tocar el resto, usar PUT /v1/agents/{id}/prompts/{section}.

Maximum array length: 20

Show child attributes

channels

string[]

Maximum array length: 10

reengagement

object

tools

string[]

Maximum array length: 100

knowledge_node_ids

string[]

Maximum array length: 200

is_active

boolean

Response

200 - application/json

agent

object

required

Show child attributes

Get started

Agents

Prompt sections

Section history

Tools

Reference

PATCH /v1/agents/{id}

Endpoint

Required scope

Headers

Path parameters

Body

Example request

Response

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

502 Bad Gateway

Operational notes

Authorizations

Path Parameters

Body

Response

​Endpoint

​Required scope

​Headers

​Path parameters

​Body

​Example request

​Response

​200 OK

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​502 Bad Gateway

​Operational notes

Authorizations

Path Parameters

Body

Response

Endpoint

Required scope

Headers

Path parameters

Body

Example request

Response

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

502 Bad Gateway

Operational notes