Skip to main content
POST
Adjuntar un bloque a un asistente
Adds one block to the assistant’s list, leaving every other block where it is. The cheap counterpart to PUT /v1/assistants/{id}/blocks, which replaces everything. The block has to exist already. Create it with one of the per-type endpoints first, or reuse one from the catalogue.

Endpoint

Required scope

assistants:write

Headers

Path parameters

Body

Example request

Response

201 Created

The full assistant, same shape as GET /v1/assistants/{id}, with the block added.

400 Bad Request

A malformed ObjectId or an unknown property. error.code is ASSISTANT_DUPLICATE_IDENTITY_BLOCK when the assistant already holds an identity block of that type.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the assistants:write scope.

404 Not Found

The assistant does not exist in the token’s company and project, or error.code is ASSISTANT_BLOCK_NOT_FOUND because the block does not exist or belongs to another company.

502 Bad Gateway

The assistant service is unreachable.

Operational notes

  • Attaching is not idempotent. Calling it twice with the same block_id adds a second reference to the same block, which renders it twice in the prompt. Check the current list first, or use PUT, which is naturally idempotent.
  • Omitting order appends. The block lands after everything currently attached. To insert in the middle you have to renumber, which means PUT.
  • The duplicate-identity check looks at the resulting list, not just at what you sent, so it catches the case where the assistant already has a personification and you attach another.
  • One block, many assistants. Attaching does not move or copy anything: the same block can be wired into any number of assistants, each with its own order and pin.

Authorizations

Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Path Parameters

id
string
required

Body

application/json
block_id
string
required

ObjectId del bloque.

pinned_version_id
string

ObjectId de una version concreta. Sin este campo el asistente sigue la version vigente del bloque.

order
number
default:0

Posicion del bloque en el prompt.

Required range: x >= 0

Response

201 - application/json
assistant
object
required