Skip to main content
POST
Crear un bloque de pasos
The procedure the assistant follows, in order. Use it when the conversation has a shape: gather, confirm, act. 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.
Instruction block: an assistant can hold several. Split long procedures into named blocks rather than one giant one — they are easier to reorder and to reuse.

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 (instructions 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

  • Write each step on a line starting with a number so it renders as an ordered list. Indent a line by two spaces to nest it under the step above.
  • 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