Skip to main content
POST
Crear un bloque de restricciones
What the assistant must never do. Short, absolute rules — this block exists so the prohibitions are not buried inside a procedure. 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.

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

  • Adding the reason after a rule tends to make it hold better than the rule alone.
  • 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