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). 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
string
parent
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]*$/
instructions

Omitted on a fork: the parent’s current instructions. 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
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

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

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

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

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

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

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

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

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

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