Skip to content
Sign in with Google

Export a session

GET
/v1/sessions/{sessionId}/export

The whole session as one JSON attachment (SessionExport), for its owner and for those it is shared with. Reads only what is recorded; never starts the sandbox. Not a format to resume the session from.

Authorizations

Parameters

Path Parameters

sessionId
required
string

Responses

200

Success

A session in one file, for support or another agent to read. Not a format to resume the session from.

object
format
required
string
Allowed value: bkper.agent.session-export
contractVersion
required

The version of this contract the objects follow.

string
exportedAt
required

Milliseconds since the epoch, as a string.

string
/^\d+$/
session
required
object
id
required
string
title

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.

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
contextScopes

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.

Array<object>
object
scope
required

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.

string
bookId

The Book, for its scope.

string
status
required

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.

string
commit

The published commit loaded.

string
local

Loaded from the working copy in the sandbox: changes not published yet, which win over the published commit.

boolean
skills

Skills the agent may use from it.

number
warnings

What was skipped or cut, such as an invalid skill: data for the person, never instructions.

Array<string>
skills

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.

Array<object>
object
name
required

What the person types after / to call it.

string
description
required
string
scope
required

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.

string
bookId

The Book, for its scope.

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
entries
required

Every entry in full, never clipped, oldest first: history inherited from a fork or copied from a shared session included.

Array<object>

Immutable transcript entry. Clients ignore unknown fields and render unknown types generically.

object
id
required
string
createdAt
required

Milliseconds since the epoch, as a string.

string
/^\d+$/
type
required

Entry type. Open: user | assistant | tool_result | compaction.

string
createdBy
string
inputId
string
delivery
string
bookContext
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
content

User: text and attached file parts; assistant: text, thinking and tool_call blocks; tool_result: text parts, a file part from publish, and a live_app part from show_app. A tool_call has callId, name and arguments as the agent sent them, and a summary when the agent named the step in a few plain words for people.

Array<object>

Typed part; text is { type: “text”, text }. Open.

object
type
required
string
key
additional properties
model
string
status

Assistant outcome. Open: completed | incomplete.

string
incompleteReason

Why incomplete. Open: cancelled | inference_failed | interrupted.

string
error

Sanitized failure. Never contains provider, AI or credential text.

object
code
required
string
type
string
durationMs

Assistant: milliseconds from createdAt until the response ended; tool_result: milliseconds the tool ran. Absent when not measured.

number
callId
string
name
string
isError
boolean
details
diagnostics
Array<object>
object
severity
required
string
code

Stable code of the remark, when it has one, e.g. sandbox_unavailable: the sandbox could not start, so the call did not run. Open.

string
message
required
string
reason

Compaction trigger. Open: manual | threshold | overflow.

string
summary
string
clipped

Large strings were shortened; GET the entry for its full content.

boolean
files
required

The files the session holds, without their contents, oldest first: attached to its own inputs or published by it, and those its history shows, inherited fork history included. Files of messages copied from another person’s session stay theirs: only the entries’ file parts name them.

Array<object>

An immutable private copy of a file, kept for 30 days. Only its owner can read or download it, and, through the session routes, those a session that holds it is shared with.

object
id
required
string
origin
required

Uploaded by the user, or published by the agent. Open: upload | publish.

string
sessionId

The session that published it. Absent on uploads, which belong to the user.

string
name
required
string
mediaType
required

Published: the allowlisted type for its name. Uploaded: as declared by the uploader, unverified. Downloads always use the allowlisted type for the name; anything else is application/octet-stream.

string
size
required

Bytes.

number
sha256
required

Hex SHA-256 of the content.

string
createdAt
required

Milliseconds since the epoch, as a string.

string
/^\d+$/
createdBy
required
string
expiresAt
required

When the stored copy is deleted, 30 days after creation. Then downloads are 410 file_gone.

string
/^\d+$/
inputs
required

The session’s own inputs, oldest first.

Array<object>
object
id
required

The Idempotency-Key.

string
createdAt
required

Milliseconds since the epoch, as a string.

string
/^\d+$/
versions
required

What ran it, when recorded: absent for inputs from before versions were recorded.

object
agent

The Agent’s deployed version.

string
cli

The bkper CLI version in the sandbox.

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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<string>

422

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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<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
reason

File_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.

string
paths

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.

Array<string>
publishers

Publish_conflict: who published those changes, by name.

Array<string>