Update a session
PATCH /v1/sessions/{sessionId}
Authorizations
Parameters
Path Parameters
Request Body required
object
object
Sent to Bkper AI as it is. Without one, its default for the model applies.
object
Context to ground the agent’s reasoning in this session: the task, the audience, a channel’s format, or the brief of a script. Rendered after Bkper’s fixed base, which it cannot relax, and before domain, user and Book AGENTS.md. Grants nothing beyond the caller’s own permissions. Empty means none.
Share the session read-only, or stop sharing it. Audience: everyone in the owner’s verified hosted domain and, for a session started in a Book, everyone who can view that Book. Only in the user’s own workspace, never an App’s (409 share_unavailable). Outside a Book it needs a hosted domain (409 share_unavailable); in a Book, that the owner can view it (409 book_access_required). Turning it off always succeeds.
Responses
200
Success
object
Milliseconds since the epoch, as a string.
Milliseconds since the epoch, as a string.
Run state. Open: idle | working | stopping.
object
Fork boundary: at inherits history through entryId; before inherits history before it. Open: at | before.
object
Sent to Bkper AI as it is. Without one, its default for the model applies.
Current conversation.
object
This conversation only; inherited history is not counted again.
object
USD estimate from catalog prices; Bkper AI accounting is authoritative.
object
Present when set. Without it the agent runs with Bkper’s base only.
Whether the owner shares this session with its audience, read-only.
The Book the session was started in: its first input’s bookContext. Fixed once set; absent when that input had none.
Present when the session is someone else’s, shared with the caller: the caller can read and continue it, never change it.
object
The owner’s display name, as Bkper verified it.
Present when the session was copied from another person’s shared session, to continue it as the caller’s own. The original is unchanged; the copy carries its history, not its files or instructions. Such a session has no parent.
object
Where the copy ends: through entryId, or before it. Open: at | before.
object
The original’s owner, as Bkper verified them when copied.
400
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.
401
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.
403
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.
404
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.
409
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.
410
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.
411
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.
413
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.
503
Rejected; never contains credentials or upstream payloads.
object
object
Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.
Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.
Host_in_use: the host another service holds.
Host_in_use: the id of the service that holds the host.