The data model
Assistant
Name, model, knowledge nodes, and an ordered list of references to blocks.
Block
One named piece of the prompt, with a type that decides where it lands.
Version
An immutable snapshot of a block’s content. Saving never overwrites.
Function
An HTTPS webhook the assistant can call mid-conversation.
The three-step drill-down
The read path is deliberately three calls, because the second one is the cheap one you will make most:Block types
There is one creation endpoint per type, because the type is what decides where the block lands in the prompt and what it is expected to say.family is derived from the type and is read-only. It decides which section of the prompt the block is composed into, so it is not something a caller gets to choose.
One identity block of each type per assistant. Attaching a second
personification, objective or response_format to the same assistant fails with ASSISTANT_DUPLICATE_IDENTITY_BLOCK. Instruction blocks have no such limit — an assistant can hold several steps blocks.Catalogue blocks are read-only here
Five more types exist and you will see them inGET /v1/blocks and in an assistant’s block list: product_info, store_info, reservation_info, tables_info and tags. You can read their content, rename them and archive them, but saving their content returns 409 BLOCK_TYPE_NOT_WRITABLE.
Content is text
Blocks written through this API are free blocks: their content is plain text, not a structured object. Three markdown conventions are recognised, because the portal editor renders them as real list and heading elements rather than literal characters:
Everything else is a paragraph. Reading the content back returns the same text.
Rich formatting authored in the portal flattens. Bold, italics, colours and inline function chips do not survive a round trip through this API: reading gives you the text, and writing replaces the document with a plain-text rendering. If an assistant was carefully styled in the portal, prefer editing it there.
Saving content never overwrites
PUT /v1/blocks/{id}/content appends an immutable version and points the block at it. The previous one stays in the history and can be restored, which also appends rather than overwrites. Nothing in this API destroys a version.
The same is true of deletes at the block level: DELETE /v1/blocks/{id} archives. Assistants that still reference an archived block keep using it — archiving hides it from the catalogue, it does not switch it off. To take a block out of an assistant, detach it.
Functions
A function is an HTTPS webhook the assistant can call while it answers. You describe what it does, the model decides when to call it, and Keebai makes the request. Placeholders written{{name}} in the path, the query string or the body are filled at call time from the arguments the model chose, so https://erp.example.com/stock/{{sku}} with a sku parameter is the normal shape.
Two things about them are worth reading before your first write: how secret values are masked and which URLs are rejected.
Scoping
Two tokens on two projects of the same company see different assistants and different blocks, and neither can read the other’s by id. They see the same functions.
Endpoints
Assistants
Wiring blocks to an assistant
Blocks
Functions
A full round trip
Next steps
Create an assistant
The first call, and what it gives you for free.
Save block content
Writing prompts as text, and which types refuse.
Webhook security
Which URLs are rejected, and how secrets are masked.
Scopes
assistants:read and assistants:write, and what each unlocks.