POST /v1/agents

Crear un agente

curl --request POST \
  --url https://api.keebai.com/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Agente de ventas",
  "description": "<string>",
  "model": "gpt-5",
  "language": "es-CL",
  "timezone": "America/Santiago",
  "prompts": [
    {
      "section": "business_context",
      "markdown": "# Quienes somos\n\nBarberia en Providencia, atendemos con hora.",
      "label": "<string>"
    }
  ],
  "channels": [
    "whatsapp",
    "webchat"
  ],
  "reengagement": {
    "enabled": true,
    "max_attempts": 2,
    "delay_minutes": 1440
  },
  "tools": [
    "<string>"
  ],
  "knowledge_node_ids": [
    "<string>"
  ],
  "stages": [
    "Nuevo",
    "Contactado",
    "Agendado",
    "Cerrado"
  ]
}
'

import requests

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

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

Barberia en Providencia, atendemos con hora.",
            "label": "<string>"
        }
    ],
    "channels": ["whatsapp", "webchat"],
    "reengagement": {
        "enabled": True,
        "max_attempts": 2,
        "delay_minutes": 1440
    },
    "tools": ["<string>"],
    "knowledge_node_ids": ["<string>"],
    "stages": ["Nuevo", "Contactado", "Agendado", "Cerrado"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Agente de ventas',
    description: '<string>',
    model: 'gpt-5',
    language: 'es-CL',
    timezone: 'America/Santiago',
    prompts: [
      {
        section: 'business_context',
        markdown: '# Quienes somos\n\nBarberia en Providencia, atendemos con hora.',
        label: '<string>'
      }
    ],
    channels: ['whatsapp', 'webchat'],
    reengagement: {enabled: true, max_attempts: 2, delay_minutes: 1440},
    tools: ['<string>'],
    knowledge_node_ids: ['<string>'],
    stages: ['Nuevo', 'Contactado', 'Agendado', 'Cerrado']
  })
};

fetch('https://api.keebai.com/v1/agents', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Agente de ventas',
    'description' => '<string>',
    'model' => 'gpt-5',
    'language' => 'es-CL',
    'timezone' => 'America/Santiago',
    'prompts' => [
        [
                'section' => 'business_context',
                'markdown' => '# Quienes somos

Barberia en Providencia, atendemos con hora.',
                'label' => '<string>'
        ]
    ],
    'channels' => [
        'whatsapp',
        'webchat'
    ],
    'reengagement' => [
        'enabled' => true,
        'max_attempts' => 2,
        'delay_minutes' => 1440
    ],
    'tools' => [
        '<string>'
    ],
    'knowledge_node_ids' => [
        '<string>'
    ],
    'stages' => [
        'Nuevo',
        'Contactado',
        'Agendado',
        'Cerrado'
    ]
  ]),
  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"

	payload := strings.NewReader("{\n  \"name\": \"Agente de ventas\",\n  \"description\": \"<string>\",\n  \"model\": \"gpt-5\",\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    \"whatsapp\",\n    \"webchat\"\n  ],\n  \"reengagement\": {\n    \"enabled\": true,\n    \"max_attempts\": 2,\n    \"delay_minutes\": 1440\n  },\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"stages\": [\n    \"Nuevo\",\n    \"Contactado\",\n    \"Agendado\",\n    \"Cerrado\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.keebai.com/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Agente de ventas\",\n  \"description\": \"<string>\",\n  \"model\": \"gpt-5\",\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    \"whatsapp\",\n    \"webchat\"\n  ],\n  \"reengagement\": {\n    \"enabled\": true,\n    \"max_attempts\": 2,\n    \"delay_minutes\": 1440\n  },\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"stages\": [\n    \"Nuevo\",\n    \"Contactado\",\n    \"Agendado\",\n    \"Cerrado\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Agente de ventas\",\n  \"description\": \"<string>\",\n  \"model\": \"gpt-5\",\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    \"whatsapp\",\n    \"webchat\"\n  ],\n  \"reengagement\": {\n    \"enabled\": true,\n    \"max_attempts\": 2,\n    \"delay_minutes\": 1440\n  },\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"stages\": [\n    \"Nuevo\",\n    \"Contactado\",\n    \"Agendado\",\n    \"Cerrado\"\n  ]\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>"
  }
}

POST

agents

Crear un agente

curl --request POST \
  --url https://api.keebai.com/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Agente de ventas",
  "description": "<string>",
  "model": "gpt-5",
  "language": "es-CL",
  "timezone": "America/Santiago",
  "prompts": [
    {
      "section": "business_context",
      "markdown": "# Quienes somos\n\nBarberia en Providencia, atendemos con hora.",
      "label": "<string>"
    }
  ],
  "channels": [
    "whatsapp",
    "webchat"
  ],
  "reengagement": {
    "enabled": true,
    "max_attempts": 2,
    "delay_minutes": 1440
  },
  "tools": [
    "<string>"
  ],
  "knowledge_node_ids": [
    "<string>"
  ],
  "stages": [
    "Nuevo",
    "Contactado",
    "Agendado",
    "Cerrado"
  ]
}
'

import requests

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

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

Barberia en Providencia, atendemos con hora.",
            "label": "<string>"
        }
    ],
    "channels": ["whatsapp", "webchat"],
    "reengagement": {
        "enabled": True,
        "max_attempts": 2,
        "delay_minutes": 1440
    },
    "tools": ["<string>"],
    "knowledge_node_ids": ["<string>"],
    "stages": ["Nuevo", "Contactado", "Agendado", "Cerrado"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Agente de ventas',
    description: '<string>',
    model: 'gpt-5',
    language: 'es-CL',
    timezone: 'America/Santiago',
    prompts: [
      {
        section: 'business_context',
        markdown: '# Quienes somos\n\nBarberia en Providencia, atendemos con hora.',
        label: '<string>'
      }
    ],
    channels: ['whatsapp', 'webchat'],
    reengagement: {enabled: true, max_attempts: 2, delay_minutes: 1440},
    tools: ['<string>'],
    knowledge_node_ids: ['<string>'],
    stages: ['Nuevo', 'Contactado', 'Agendado', 'Cerrado']
  })
};

fetch('https://api.keebai.com/v1/agents', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Agente de ventas',
    'description' => '<string>',
    'model' => 'gpt-5',
    'language' => 'es-CL',
    'timezone' => 'America/Santiago',
    'prompts' => [
        [
                'section' => 'business_context',
                'markdown' => '# Quienes somos

Barberia en Providencia, atendemos con hora.',
                'label' => '<string>'
        ]
    ],
    'channels' => [
        'whatsapp',
        'webchat'
    ],
    'reengagement' => [
        'enabled' => true,
        'max_attempts' => 2,
        'delay_minutes' => 1440
    ],
    'tools' => [
        '<string>'
    ],
    'knowledge_node_ids' => [
        '<string>'
    ],
    'stages' => [
        'Nuevo',
        'Contactado',
        'Agendado',
        'Cerrado'
    ]
  ]),
  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"

	payload := strings.NewReader("{\n  \"name\": \"Agente de ventas\",\n  \"description\": \"<string>\",\n  \"model\": \"gpt-5\",\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    \"whatsapp\",\n    \"webchat\"\n  ],\n  \"reengagement\": {\n    \"enabled\": true,\n    \"max_attempts\": 2,\n    \"delay_minutes\": 1440\n  },\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"stages\": [\n    \"Nuevo\",\n    \"Contactado\",\n    \"Agendado\",\n    \"Cerrado\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.keebai.com/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Agente de ventas\",\n  \"description\": \"<string>\",\n  \"model\": \"gpt-5\",\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    \"whatsapp\",\n    \"webchat\"\n  ],\n  \"reengagement\": {\n    \"enabled\": true,\n    \"max_attempts\": 2,\n    \"delay_minutes\": 1440\n  },\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"stages\": [\n    \"Nuevo\",\n    \"Contactado\",\n    \"Agendado\",\n    \"Cerrado\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Agente de ventas\",\n  \"description\": \"<string>\",\n  \"model\": \"gpt-5\",\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    \"whatsapp\",\n    \"webchat\"\n  ],\n  \"reengagement\": {\n    \"enabled\": true,\n    \"max_attempts\": 2,\n    \"delay_minutes\": 1440\n  },\n  \"tools\": [\n    \"<string>\"\n  ],\n  \"knowledge_node_ids\": [\n    \"<string>\"\n  ],\n  \"stages\": [\n    \"Nuevo\",\n    \"Contactado\",\n    \"Agendado\",\n    \"Cerrado\"\n  ]\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>"
  }
}

Creates an agent in the token’s project and returns it with its _id. The goal is the decision that matters. It is what switches the toolkits on, so an agent created to inform cannot later be made to book without changing it. Everything else — sections, channels, tools — can be adjusted afterwards. You can send the prompt sections here, or create the agent bare and write them one at a time. Valid values for section, goal.type and channels come from the catalogue.

Endpoint

POST https://api.keebai.com/v1/agents

Required scope

agents:write

Body

Field	Type	Required	Description
`name`	`string`	Yes	Up to 150 characters.
`description`	`string`	No	Up to 500 characters. Internal, the customer never sees it.
`model`	`string`	No	Model id, for example `gpt-5`. An unsupported one fails with `INVALID_MODEL`.
`language`	`string`	No	Locale. The country matters: `es-CL` and `es-MX` do not conjugate the same.
`timezone`	`string`	No	IANA name, for example `America/Santiago`.
`goal`	`object`	No	`{ type, instructions? }`. `instructions` only applies to the `custom` goal.
`prompts`	`array`	No	`{ section, label?, markdown }`, up to 20.
`channels`	`string[]`	No	Channel types from the catalogue, up to 10.
`reengagement`	`object`	No	How often it comes back to a conversation that went cold.
`tools`	`string[]`	No	`ObjectId`s from `GET /v1/tools`, up to 100.
`knowledge_node_ids`	`string[]`	No	Up to 200.

Example request

curl -X POST https://api.keebai.com/v1/agents \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camila",
    "model": "gpt-5",
    "language": "es-CL",
    "timezone": "America/Santiago",
    "goal": { "type": "appointment_management" },
    "channels": ["whatsapp"],
    "prompts": [
      {
        "section": "business_context",
        "markdown": "# Quiénes somos\n\nBarbería en Providencia. Atendemos con hora, de martes a sábado."
      }
    ]
  }'

const resp = await fetch("https://api.keebai.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Camila",
    model: "gpt-5",
    language: "es-CL",
    goal: { type: "appointment_management" },
    channels: ["whatsapp"],
  }),
});
const { agent } = await resp.json();

import os, requests

resp = requests.post(
    "https://api.keebai.com/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
    json={
        "name": "Camila",
        "model": "gpt-5",
        "language": "es-CL",
        "goal": {"type": "appointment_management"},
        "channels": ["whatsapp"],
    },
    timeout=10,
)
resp.raise_for_status()
agent = resp.json()["agent"]

Response

201 Created

{
  "agent": {
    "_id": "6650a1b2c3d4e5f6a7b8c9d0",
    "name": "Camila",
    "description": null,
    "model": "gpt-5",
    "language": "es-CL",
    "timezone": "America/Santiago",
    "goal": { "type": "appointment_management", "instructions": null },
    "prompts": [
      { "section": "business_context", "label": null, "markdown": "# Quiénes somos\n\nBarbería en Providencia..." }
    ],
    "channels": ["whatsapp"],
    "reengagement": null,
    "tools": [],
    "knowledge_node_ids": [],
    "voice_response_enabled": false,
    "is_active": true,
    "created_at": "2026-08-18T09:04:21.100Z",
    "updated_at": "2026-08-18T09:04:21.100Z"
  }
}

400 Bad Request

A field over its length limit, a malformed ObjectId, an unknown property, or INVALID_MODEL.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the agents:write scope.

502 Bad Gateway

The agent service is unreachable.

Operational notes

An agent created here is not yet answering. The channel has to be connected on the company as well as enabled on the agent, and a goal that uses tools needs the data behind them — services, staff, catalogue — to exist.
Every section you send is versioned from the start. The creation is version 1 of each.
language carries the country and it is not cosmetic. It is what decides how the agent conjugates; getting it wrong is the first thing a customer notices.
Leaving a section out is better than inventing one. An empty section is filled later; an invented one is discovered by a customer.

Authorizations

Authorization

string

header

required

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

Body

application/json

name

string

required

Maximum string length: 150

Example:

"Agente de ventas"

description

string

Maximum string length: 500

model

string

Identificador del modelo. Se valida contra los modelos soportados; uno desconocido devuelve 400 INVALID_MODEL.

Example:

"gpt-5"

language

string

Locale del agente. El pais importa: es-CL y es-MX no conjugan igual.

Example:

"es-CL"

timezone

string

Example:

"America/Santiago"

goal

object

Show child attributes

prompts

object[]

Las secciones del prompt. Se pueden mandar aca al crear, o una por una con PUT /v1/agents/{id}/prompts/{section}.

Maximum array length: 20

Show child attributes

channels

string[]

Canales por los que atiende, del catalogo (GET /v1/prompt-types?kind=channel).

Maximum array length: 10

Example:

["whatsapp", "webchat"]

reengagement

object

Reenganche: cuantas veces vuelve sobre una conversacion enfriada y cada cuanto.

Example:

{
  "enabled": true,
  "max_attempts": 2,
  "delay_minutes": 1440
}

tools

string[]

ObjectIds de herramientas (GET /v1/tools) que puede usar.

Maximum array length: 100

knowledge_node_ids

string[]

ObjectIds de nodos de la base de conocimiento a asignar.

Maximum array length: 200

stages

string[]

Etapas del embudo, por NOMBRE y en orden. Se crea un pipeline en el CRM con el nombre del agente y esas etapas, y el agente queda habilitado para mover tickets solo entre ellas. Sin esto no se crea ningun pipeline y el agente no mueve tickets.

Maximum array length: 20

Example:

[
  "Nuevo",
  "Contactado",
  "Agendado",
  "Cerrado"
]

Response

201 - application/json

agent

object

required

Show child attributes

Get started

Agents

Prompt sections

Section history

Tools

Reference

POST /v1/agents

Endpoint

Required scope

Body

Example request

Response

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

502 Bad Gateway

Operational notes

Authorizations

Body

Response

​Endpoint

​Required scope

​Body

​Example request

​Response

​201 Created

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​502 Bad Gateway

​Operational notes

Authorizations

Body

Response

Endpoint

Required scope

Body

Example request

Response

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

502 Bad Gateway

Operational notes