Skip to main content
POST
Crear un bloque de personalidad
Who the assistant is: its role, its tone, and how it addresses people. This is the block that makes an assistant sound like your business rather than like a generic bot. The block is created in the project catalogue and is not attached to anything. Wire it into an assistant with POST /v1/assistants/{id}/blocks afterwards.
Identity block: one per assistant. Attaching a second personification to the same assistant fails with ASSISTANT_DUPLICATE_IDENTITY_BLOCK.

Endpoint

Required scope

assistants:write

Headers

Body

type and family are not accepted: the type is the endpoint you called, and family is derived from it (identity for this one).

Example request

Response

201 Created

400 Bad Request

Missing name, content over 100,000 characters, or a property the endpoint does not accept.

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

  • Every assistant created with POST /v1/assistants already comes with an empty one of these attached. Check its block list before creating another — you probably want to fill in the existing one instead.
  • Creating a block also creates its first version. The response already carries a current_version_id, even when you omit content — the block starts with one empty version rather than none.
  • Creation is not idempotent. Nothing enforces unique names, so a retry after a timeout leaves you with two blocks. Check the catalogue filtered by type before retrying.
  • Content is plain text with three markdown conventions: - for bullets, 1. for numbered items, # for headings. Everything else is a paragraph. More on how content is stored.
  • The block belongs to the token’s project, and a token on another project can neither see it nor read it by id.

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

Nombre con el que el bloque aparece en el portal.

Maximum string length: 150
Example:

"Tono cercano"

content
string

Contenido inicial en texto. Se reconocen listas con '-' y con '1.', y encabezados con '#'. Sin este campo el bloque nace vacio.

Maximum string length: 100000

Response

201 - application/json
block
object
required