Crear un asistente
Assistants
POST /v1/assistants
Create an assistant. It comes with an empty personality block and an empty response-policy block already attached.
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
Missingname, 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 theassistants:write scope.
502 Bad Gateway
The assistant service is unreachable.Operational notes
- The two starting blocks are real catalogue blocks,
order: 0is thepersonificationandorder: 1theresponse_policy. They belong to the project like any other, so they show up inGET /v1/blocksand can be renamed, archived or reused. Read their type fromGET /v1/assistants/{id}/blocksrather 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 byqbefore retrying. - The assistant is created in the token’s project. There is no
projectfield to send; it comes from the token, and a token scoped to another project creates it there instead. - Sending
metadata,company,project,blocksoris_activeis rejected, not ignored — unknown properties return400. 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
Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.
Body
application/json
Maximum string length:
150Example:
"Asistente de ventas"
Maximum string length:
500URL https de la imagen del avatar.
Example:
"https://cdn.example.com/avatars/ventas.png"
Maximum string length:
16Example:
"🤖"
Identificador del modelo. Se valida contra los modelos soportados; uno desconocido devuelve 400 INVALID_MODEL.
Example:
"gemini-2.5-flash"
ObjectIds de nodos de la base de conocimiento a asignar.
Maximum array length:
200Response
201 - application/json