Skip to main content
POST
Crear un asistente
Creates an assistant in the token’s project and returns it with its _id and its starting blocks. The assistant is not born empty: it comes with a personification block and a response_policy block already created and attached, both with no content. Without those two an assistant has no identity and no rule about when to answer, so it would not say anything useful. Your next call is normally PUT /v1/blocks/{id}/content on the personality block.

Endpoint

Required scope

assistants:write

Headers

Body

Example request

Response

201 Created

400 Bad Request

Missing name, a field over its length limit, an avatar_url that is not https, a malformed ObjectId in knowledge_node_ids, or a property the endpoint does not accept. error.code is INVALID_MODEL when the problem is the model.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the assistants:write scope.

502 Bad Gateway

The assistant service is unreachable.

Operational notes

  • The two starting blocks are real catalogue blocks, order: 0 is the personification and order: 1 the response_policy. They belong to the project like any other, so they show up in GET /v1/blocks and can be renamed, archived or reused. Read their type from GET /v1/assistants/{id}/blocks rather than trusting the array position.
  • Creation is not idempotent. There is no uniqueness constraint on name, so a retry after a timeout creates a second assistant. Check with the list endpoint filtered by q before retrying.
  • The assistant is created in the token’s project. There is no project field to send; it comes from the token, and a token scoped to another project creates it there instead.
  • Sending metadata, company, project, blocks or is_active is rejected, not ignored — unknown properties return 400. Blocks are wired with the block endpoints after creation.
  • A new assistant is active immediately and will answer on any channel it gets routed to. Create it, configure it, then route it — not the other way round.

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:

"Asistente de ventas"

description
string
Maximum string length: 500
avatar_url
string

URL https de la imagen del avatar.

Example:

"https://cdn.example.com/avatars/ventas.png"

avatar_emoji
string
Maximum string length: 16
Example:

"🤖"

model
string

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

Example:

"gemini-2.5-flash"

knowledge_node_ids
string[]

ObjectIds de nodos de la base de conocimiento a asignar.

Maximum array length: 200

Response

201 - application/json
assistant
object
required