Skip to content
Bkper
Sign in with Google

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

Idempotency-Key
required
string
/^[A-Za-z0-9_-]{1,128}$/

Request Body required

object
title
string
>= 1 characters <= 200 characters
model
object
id
required
string
thinkingLevel

Sent to Bkper AI as it is. Without one, its default for the model applies.

string
parent

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
sessionId
required
string
>= 1 characters <= 128 characters
entryId
required
string
>= 1 characters <= 128 characters
kind
required
string
Allowed value: fork
position

Default at: inherit through a finished assistant reply. Before: inherit history before a user message; does not send it.

string
Allowed values: at before
input
object
content
required

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.

Array
>= 1 items <= 16 items
One of:
object
type
required
string
Allowed value: text
text
required
string
delivery
string
Allowed values: prompt steer followUp
bookContext

Advisory Book/query context, frozen with this input. Never identity or authorization.

object
bookId
required
string
/^[A-Za-z0-9_-]{1,128}$/
query
required
string
<= 4000 characters /^[^\u0000-\u001f]*$/
attributes

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
key
additional properties
string
<= 16000 characters
instructions

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.

string
<= 16000 characters

Responses

201

Success

object
id
required
string
title
string
createdAt
required

Milliseconds since the epoch, as a string.

string
/^\d+$/
updatedAt
required

Milliseconds since the epoch, as a string.

string
/^\d+$/
status
required

Run state. Open: idle | working | stopping.

string
archived
required
boolean
parent
object
sessionId
required
string
>= 1 characters <= 128 characters
entryId
required
string
>= 1 characters <= 128 characters
kind
required
string
Allowed value: fork
position
required

Fork boundary: at inherits history through entryId; before inherits history before it. Open: at | before.

string
model
required
object
id
required
string
thinkingLevel

Sent to Bkper AI as it is. Without one, its default for the model applies.

string
context
required

Current conversation.

object
tokens
required
number
window
required
number
usage
required

This conversation only; inherited history is not counted again.

object
inputTokens
required
number
outputTokens
required
number
cacheReadTokens
required
number
cacheWriteTokens
required
number
estimatedCost
required

USD estimate from catalog prices; Bkper AI accounting is authoritative.

string
properties
required
object
key
additional properties
string
instructions

Present when set. Without it the agent runs with Bkper’s base only.

string
<= 16000 characters
shared
required

Whether the owner shares this session with its audience, read-only.

boolean
bookId

The Book the session was started in: its first input’s bookContext. Fixed once set; absent when that input had none.

string
owner

Present when the session is someone else’s, shared with the caller: the caller can read and continue it, never change it.

object
name

The owner’s display name, as Bkper verified it.

string
continuedFrom

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
sessionId
required
string
entryId
required
string
position
required

Where the copy ends: through entryId, or before it. Open: at | before.

string
owner
required
object
name

The original’s owner, as Bkper verified them when copied.

string

400

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string

401

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string

403

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string

404

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string

409

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string

410

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string

411

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string

413

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string

503

Rejected; never contains credentials or upstream payloads.

object
error
required
object
code
required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string
type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string
message
string
host

Host_in_use: the host another service holds.

string
service

Host_in_use: the id of the service that holds the host.

string