Skip to main content
PUT
Reemplazar los bloques de un asistente
Sets the assistant’s entire block list in one call. This is the only endpoint that can reorder blocks or change which version each one is pinned to. Because it replaces rather than merges, read the current list first and send the whole thing back with your change applied. Any block you leave out is detached.
Send a partial list and you detach everything missing from it. Start from GET /v1/assistants/{id}/blocks, not from memory.

Endpoint

Required scope

assistants:write

Headers

Path parameters

Body

Example request

Response

200 OK

The full assistant, same shape as GET /v1/assistants/{id}, with the new blocks array.

400 Bad Request

More than 50 entries, a malformed ObjectId, or an unknown property. error.code is ASSISTANT_DUPLICATE_IDENTITY_BLOCK when the list would give the assistant two identity blocks of the same 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 one of the block_id values does not exist or belongs to another company.

502 Bad Gateway

The assistant service is unreachable.

Operational notes

  • At most one personification, one objective and one response_format. Those three are the identity family and a duplicate is a 400. Instruction blocks — steps, cases_possible, do_not, response_policy — have no such limit.
  • A block from another company is a 404, not a 403. Cross-company block ids are checked before anything is written, so a rejected call changes nothing.
  • order decides the prompt, and gaps are fine. Blocks are composed in ascending order within their family; the families themselves always render identity, then instructions, then information. Reordering across families does nothing.
  • Pinning is how you freeze an assistant against edits. With pinned_version_id set, later content saves on that block do not reach this assistant. Useful when one block is shared by a production and a staging assistant.
  • Detaching does not archive. Blocks dropped from the list stay in the catalogue and keep their history.

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
blocks
object[]
required

Lista completa de bloques del asistente. Los que no aparezcan quedan desadjuntados.

Maximum array length: 50

Response

200 - application/json
assistant
object
required