Skip to main content
POST
Crear un bloque de formato de respuesta
How the assistant writes: message length, emoji usage, and formatting rules. Separate from what it says, so you can change the voice without touching the content. 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. A second response_format on 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

  • Channel-specific rules belong here. The same assistant answering on WhatsApp and on web chat reads the same formatting block, so say which rule applies where.
  • 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