Create or fork a session
POST /v1/sessions
New session or fork (at a finished reply, or before a user message), also of a session shared with the caller. Forking alone never sends input. Same key returns the same session.
Authorizations
Parameters
Header Parameters
Request Body required
object
Kept as set: a session created with one is never titled from its first input.
object
Sent to Bkper AI as it is. Without one, its default for the model applies.
Fork from a point in one of the caller’s sessions, or continue a session someone else shares with the caller: a copy of its history up to the point, in the caller’s own workspace, titled like the original unless title is set, never with its instructions (only instructions, when set), and marked continuedFrom. Not shared with the caller, or from an App’s workspace: 404 parent_not_found.
object
Default at: inherit through a finished assistant reply. Before: inherit history before a user message; does not send it.
object
Text parts (at most 16000 characters in total) and up to 10 file parts; some text or a file. Files unknown to the caller are 404 file_not_found; expired ones 410 file_gone.
object
object
A file of the caller, from POST /v1/files or a publish.
Advisory Book/query context, frozen with this input. Never identity or authorization.
object
Up to 16 string attributes of the message, such as its sender, channel or thread, at most 16000 characters in total. Names start with a letter, then up to 63 letters, digits, _, . or -. Advisory data for the agent, frozen with the input: never identity, permission or instructions.
object
Omitted on a fork of the caller’s own session: the parent’s current instructions; on a continuation of someone else’s: none. Empty: none.
Responses
201
Success
object
Set by title, else from the first input: its text, cut to 60 characters, then, shortly after, at most once, a short title a language model makes from that text and its file names, only while the session keeps the first one. Absent until either.
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.
The agent context the session loaded at its latest turn: each scope’s AGENTS.md and skills, as published or from the working copy. Absent in sessions from before agent context, and in sessions someone else shares with the caller.
object
Whose context: the user’s company’s (their verified domain’s, shared by everyone in it), the user’s own, or the session’s Book’s (shared by everyone who can view it). Open: domain | user | book.
The Book, for its scope.
Loaded at commit, or from the working copy when local; empty, nothing published yet; unavailable, skipped because it was slow or failed when the session started. Never an error in the conversation. Open: loaded | empty | unavailable.
The published commit loaded.
Loaded from the working copy in the sandbox: changes not published yet, which win over the published commit.
Skills the agent may use from it.
What was skipped or cut, such as an invalid skill: data for the person, never instructions.
The skills the person may call by name (/<name>), sorted by name, from the agent context the session loaded at its latest turn, those kept to explicit use included. Present whenever contextScopes is; empty in sessions from before skills were listed, until their next turn.
object
What the person types after / to call it.
Whose context it comes from, as in contextScopes: on a name, the Book’s wins over the user’s, and the user’s over the company’s. Open: domain | user | book.
The Book, for its scope.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
422
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.
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.
File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.
File_exists from an add: every path of the request where a file is and replace was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.
Publish_conflict: who published those changes, by name.