Reemplazar los bloques de un asistente
Assistant blocks
PUT /v1/assistants/{id}/blocks
Replace the whole block list of an assistant. The only way to reorder blocks or pin versions.
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.
Endpoint
Required scope
assistants:write
Headers
Path parameters
Body
Example request
Response
200 OK
The full assistant, same shape asGET /v1/assistants/{id}, with the new blocks array.
400 Bad Request
More than 50 entries, a malformedObjectId, 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 theassistants:write scope.
404 Not Found
The assistant does not exist in the token’s company and project, orerror.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, oneobjectiveand oneresponse_format. Those three are the identity family and a duplicate is a400. Instruction blocks —steps,cases_possible,do_not,response_policy— have no such limit. - A block from another company is a
404, not a403. Cross-company block ids are checked before anything is written, so a rejected call changes nothing. orderdecides the prompt, and gaps are fine. Blocks are composed in ascendingorderwithin 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_idset, 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
Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.
Path Parameters
Body
application/json
Lista completa de bloques del asistente. Los que no aparezcan quedan desadjuntados.
Maximum array length:
50Response
200 - application/json