Skip to content

Chat history

Read saved chats, their files and captures, and the sessions your computers publish.

OperationRequest
List saved chatsGET /v1/history
List history projectsGET /v1/history/projects
List computer sessionsGET /v1/history/sessions
Publish computer sessionsPUT /v1/history/sessions/computers/{device}
Forget computer sessionsDELETE /v1/history/sessions/computers/{device}
Read session move requestsGET /v1/history/sessions/computers/{device}/moves
Set project session transcriptsPUT /v1/history/sessions/projects/{project}/transcript
Read computer sessionGET /v1/history/sessions/{id}
Upload session transcriptPUT /v1/history/sessions/{id}/messages
Set session transcriptPUT /v1/history/sessions/{id}/transcript
Read saved captureGET /v1/history/{id}/captures/{capture}
Read saved fileGET /v1/history/{id}/files/{file}
Read saved messagesGET /v1/history/{id}/messages

List saved chats

GET /v1/history · listSavedChats

List your saved chats, newest first, or the chats of one shared project.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
limitqueryintegerNo
afterquerystringNo

Last public ID from this same list. Empty filtered pages may still have next. ID-order discovery is not a snapshot; restart to find newly inserted earlier IDs.

projectquerystringNo

A currently authorized shared project ID. Omit for all owned chats, including archived.

Response

200 — A read-only saved page. No hosts are contacted and no seen/send state changes.

Type: HistoryList

FieldTypeRequiredDescription
dataarray of HistorySummaryYes
data[].idstring (uuid)Yes
data[].titlestringYes
data[].revisionintegerYes
data[].updated_unixintegerYes
data[].pinned_unixinteger or nullYes
data[].archived_unixinteger or nullYes
data[].projectstring or nullYes
data[].sourceone of "web", "terminal", "phone"Yes
data[].messagesintegerYes
data[].homeChatHome (string)No
data[].continuesnull or ChatPartRefNo
data[].continued_bynull or ChatPartRefNo
nextstring or nullYes
sessionsarray of HistorySessionNo

Computer sessions, newest first, on the first page only. They never join data or its paging.

sessions[].idstring (uuid)Yes
sessions[].sourcealways "session"Yes
sessions[].homeChatHome (string)Yes
sessions[].titlestringYes
sessions[].computerstringYes
sessions[].projectstring or nullYes
sessions[].folderstring or nullYes
sessions[].statusone of "idle", "working", "awaiting_input", "errored"Yes
sessions[].last_activity_unixintegerYes
sessions[].updated_unixintegerYes
sessions[].recapstringYes
sessions[].onlinebooleanYes
sessions[].transcriptbooleanYes

The transcript is on for this caller, so a copy may be read.

sessions[].app_linkstring or nullYes

Opens the chat in the OpenAgents app.

sessions[].continuesnull or ChatPartRefNo
sessions[].continued_bynull or ChatPartRefYes
sessions[].agentstring or nullNo

The saved agent the session runs; lists show its name with the OpenAgents mark.

sessions[].home_transferbooleanNo

This computer can move a chat through its normal continuation path.

Errors

StatusMeaningBody
400, 401, 403, 404, 409, 429, 503

Invalid page, signed out, denied, missing, changed, throttled, or unavailable. A failure is never an empty success.

AppAccountError

Example

curl 'https://api.openagents.com/v1/history' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

List history projects

GET /v1/history/projects · listHistoryProjects

List the projects your saved chats belong to.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
limitqueryintegerNo
afterquerystringNo

Last public ID from this same list. Empty filtered pages may still have next. ID-order discovery is not a snapshot; restart to find newly inserted earlier IDs.

Response

200 — A read-only saved page. No hosts are contacted and no seen/send state changes.

Type: HistoryProjects

FieldTypeRequiredDescription
dataarray of HistoryProjectYes
data[].idstringYes
data[].namestringYes
data[].sharedbooleanYes
nextstring or nullYes

Errors

StatusMeaningBody
400, 401, 403, 404, 409, 429, 503

Invalid page, signed out, denied, missing, changed, throttled, or unavailable. A failure is never an empty success.

AppAccountError

Example

curl 'https://api.openagents.com/v1/history/projects' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

List computer sessions

GET /v1/history/sessions · listComputerSessions

The caller's computer sessions, newest first, or a project's.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
projectquerystringNo

A project the caller is in. A shared project lists every member's rows in it.

Response

200 — Session rows

Type: HistorySessions

FieldTypeRequiredDescription
dataarray of HistorySessionYes
data[].idstring (uuid)Yes
data[].sourcealways "session"Yes
data[].homeChatHome (string)Yes
data[].titlestringYes
data[].computerstringYes
data[].projectstring or nullYes
data[].folderstring or nullYes
data[].statusone of "idle", "working", "awaiting_input", "errored"Yes
data[].last_activity_unixintegerYes
data[].updated_unixintegerYes
data[].recapstringYes
data[].onlinebooleanYes
data[].transcriptbooleanYes

The transcript is on for this caller, so a copy may be read.

data[].app_linkstring or nullYes

Opens the chat in the OpenAgents app.

data[].continuesnull or ChatPartRefNo
data[].continued_bynull or ChatPartRefYes
data[].agentstring or nullNo

The saved agent the session runs; lists show its name with the OpenAgents mark.

data[].home_transferbooleanNo

This computer can move a chat through its normal continuation path.

Errors

StatusMeaningBody
400, 401, 404, 409, 429, 503

Invalid, signed out, missing, transcript off, throttled, or unavailable.

AppAccountError

Example

curl 'https://api.openagents.com/v1/history/sessions' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

Publish computer sessions

PUT /v1/history/sessions/computers/{device} · publishComputerSessions

A host's current rows for this computer, replacing the ones it published before. Publishing also marks the computer online for 90 seconds.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
devicepathstringYes

Request body

Content type: application/json

Type: HistorySessionPublish

FieldTypeRequiredDescription
namestringYes
sessionsarray of objectYes
sessions[].idstring (uuid)Yes
sessions[].titlestringYes
sessions[].projectstring or nullNo
sessions[].folderstring or nullNo
sessions[].statusone of "idle", "working", "awaiting_input", "errored"Yes
sessions[].last_activity_unixintegerYes
sessions[].recapstringNo
sessions[].workspacestring or nullNo
sessions[].continuesChatPartRefNo
sessions[].continues.idstring (uuid)Yes
sessions[].continues.homeChatHome (string)Yes
sessions[].agentstring or nullNo

The saved agent the session runs.

sessions[].home_transferbooleanNo

Response

200 — The sessions whose transcript is on

Type: object

FieldTypeRequiredDescription
transcriptsarray of string (uuid)Yes

Errors

StatusMeaningBody
400, 401, 404, 409, 429, 503

Invalid, signed out, missing, transcript off, throttled, or unavailable.

AppAccountError

Example

curl -X PUT 'https://api.openagents.com/v1/history/sessions/computers/{device}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "sessions": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "title": "string",
      "status": "idle",
      "last_activity_unix": 0
    }
  ]
}'

In the Rust SDK

Forget computer sessions

DELETE /v1/history/sessions/computers/{device} · forgetComputerSessions

Remove this computer's rows and transcript copies.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
devicepathstringYes

Response

200 — Removed

Type: object

FieldTypeRequiredDescription
removedbooleanYes

Errors

StatusMeaningBody
400, 401, 404, 409, 429, 503

Invalid, signed out, missing, transcript off, throttled, or unavailable.

AppAccountError

Example

curl -X DELETE 'https://api.openagents.com/v1/history/sessions/computers/{device}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

Read session move requests

GET /v1/history/sessions/computers/{device}/moves · readSessionMoveRequests

Account-owned requests to continue on the web, plus existing cloud destinations whose local metadata may need repair. The owning computer freezes its old part before claiming the destination through continueChatOnComputer.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
devicepathstringYes

Response

200 — Requests for this computer

Type: HistorySessionMoves

FieldTypeRequiredDescription
movesarray of objectYes
moves[].sourcestring (uuid)Yes
moves[].targetChatPartRefYes
moves[].target.idstring (uuid)Yes
moves[].target.homeChatHome (string)Yes
moves[].expires_unixintegerYes

Errors

StatusMeaningBody
400, 401, 404, 409, 429, 503

Invalid, signed out, missing, transcript off, throttled, or unavailable.

AppAccountError

Example

curl 'https://api.openagents.com/v1/history/sessions/computers/{device}/moves' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

Set project session transcripts

PUT /v1/history/sessions/projects/{project}/transcript · setProjectSessionTranscripts

Turn the transcripts of every session in a project on or off. Shared project members read a copy only by this choice.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
projectpathstringYes

Request body

Content type: application/json

Type: HistorySessionChoice

FieldTypeRequiredDescription
onbooleanYes

Response

200 — The choice

Type: HistorySessionChoice

FieldTypeRequiredDescription
onbooleanYes

Errors

StatusMeaningBody
400, 401, 404, 409, 429, 503

Invalid, signed out, missing, transcript off, throttled, or unavailable.

AppAccountError

Example

curl -X PUT 'https://api.openagents.com/v1/history/sessions/projects/{project}/transcript' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "on": false
}'

In the Rust SDK

Read computer session

GET /v1/history/sessions/{id} · readComputerSession

One session row, and its transcript copy when the transcript is on for the caller.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes
projectquerystringNo

A project the caller is in. A shared project lists every member's rows in it.

Response

200 — One session

Type: HistorySessionDetail

FieldTypeRequiredDescription
sessionHistorySessionYes

A computer session's summary. It holds no transcript.

session.idstring (uuid)Yes
session.sourcealways "session"Yes
session.homeChatHome (string)Yes
session.titlestringYes
session.computerstringYes
session.projectstring or nullYes
session.folderstring or nullYes
session.statusone of "idle", "working", "awaiting_input", "errored"Yes
session.last_activity_unixintegerYes
session.updated_unixintegerYes
session.recapstringYes
session.onlinebooleanYes
session.transcriptbooleanYes

The transcript is on for this caller, so a copy may be read.

session.app_linkstring or nullYes

Opens the chat in the OpenAgents app.

session.continuesnull or ChatPartRefNo
session.continued_bynull or ChatPartRefYes
session.agentstring or nullNo

The saved agent the session runs; lists show its name with the OpenAgents mark.

session.home_transferbooleanNo

This computer can move a chat through its normal continuation path.

messagesnull or array of HistorySessionMessageYes

Errors

StatusMeaningBody
400, 401, 404, 409, 429, 503

Invalid, signed out, missing, transcript off, throttled, or unavailable.

AppAccountError

Example

curl 'https://api.openagents.com/v1/history/sessions/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

Upload session transcript

PUT /v1/history/sessions/{id}/messages · uploadSessionTranscript

Replace the read-only transcript copy. Refused with transcript_off while the transcript is off. Text is bounded and screened.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Request body

Content type: application/json

Type: HistorySessionUpload

FieldTypeRequiredDescription
messagesarray of HistorySessionMessageYes
messages[].roleone of "user", "assistant", "tool"Yes
messages[].textstringYes

Response

200 — Saved

Type: object

FieldTypeRequiredDescription
savedintegerYes

Errors

StatusMeaningBody
400, 401, 404, 409, 429, 503

Invalid, signed out, missing, transcript off, throttled, or unavailable.

AppAccountError

Example

curl -X PUT 'https://api.openagents.com/v1/history/sessions/{id}/messages' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "role": "user",
      "text": "string"
    }
  ]
}'

In the Rust SDK

Set session transcript

PUT /v1/history/sessions/{id}/transcript · setSessionTranscript

Turn one chat's transcript on or off on the web. Off by default; off deletes the copy.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Request body

Content type: application/json

Type: HistorySessionChoice

FieldTypeRequiredDescription
onbooleanYes

Response

200 — The choice

Type: object

FieldTypeRequiredDescription
onbooleanYes
transcriptbooleanYes

Errors

StatusMeaningBody
400, 401, 404, 409, 429, 503

Invalid, signed out, missing, transcript off, throttled, or unavailable.

AppAccountError

Example

curl -X PUT 'https://api.openagents.com/v1/history/sessions/{id}/transcript' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "on": false
}'

In the Rust SDK

Read saved capture

GET /v1/history/{id}/captures/{capture} · readSavedCapture

Download a screen capture saved with a chat.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes
capturepathstring (uuid)Yes

Response

200 — Saved attachment bytes. Current chat/project authorization is checked; missing saved bytes return 404.

Content type: application/octet-stream

Type: string (binary)

Errors

StatusMeaningBody
400, 401, 403, 404, 409, 429, 503

Invalid page, signed out, denied, missing, changed, throttled, or unavailable. A failure is never an empty success.

AppAccountError

Example

curl 'https://api.openagents.com/v1/history/{id}/captures/{capture}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Read saved file

GET /v1/history/{id}/files/{file} · readSavedFile

Download a file attached to a saved chat.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes
filepathstringYes

Response

200 — Saved attachment bytes. Current chat/project authorization is checked; missing saved bytes return 404.

Content type: application/octet-stream

Type: string (binary)

Errors

StatusMeaningBody
400, 401, 403, 404, 409, 429, 503

Invalid page, signed out, denied, missing, changed, throttled, or unavailable. A failure is never an empty success.

AppAccountError

Example

curl 'https://api.openagents.com/v1/history/{id}/files/{file}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Read saved messages

GET /v1/history/{id}/messages · readSavedMessages

Read one saved chat's messages, oldest first, a page at a time.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes
limitqueryintegerNo
afterquerystringNo

Last public ID from this same list. Empty filtered pages may still have next. ID-order discovery is not a snapshot; restart to find newly inserted earlier IDs.

revisionqueryintegerNo

Required with after. A changed transcript returns 409; restart without after.

Response

200 — A read-only saved page. No hosts are contacted and no seen/send state changes.

Type: HistoryMessages

FieldTypeRequiredDescription
capturesarray of HistoryCaptureYes
captures[].idstring (uuid)Yes
captures[].namestringYes
captures[].stateone of "saved", "unavailable", "not_saved"Yes
captures[].sizeinteger or nullYes
captures[].mediastring or nullYes
threadHistorySummaryYes
thread.idstring (uuid)Yes
thread.titlestringYes
thread.revisionintegerYes
thread.updated_unixintegerYes
thread.pinned_unixinteger or nullYes
thread.archived_unixinteger or nullYes
thread.projectstring or nullYes
thread.sourceone of "web", "terminal", "phone"Yes
thread.messagesintegerYes
thread.homeChatHome (string)No
thread.continuesnull or ChatPartRefNo
thread.continued_bynull or ChatPartRefNo
revisionintegerYes
dataarray of HistoryMessageYes
data[].idstringYes
data[].roleone of "user", "assistant", "tool", "thinking"Yes
data[].textstringYes
data[].filesarray of HistoryFileYes
data[].files[].idstringYes
data[].files[].namestringYes
data[].files[].kindone of "png", "jpeg", "gif", "webp", "pdf", "text", "step", "stl"Yes
data[].files[].sizeintegerYes
data[].toolHistoryTool (object or null)Yes
data[].tool.namestringYes
data[].tool.summarystringYes
data[].tool.statusone of "running", "done", "failed"Yes
data[].tool.inputstringYes
data[].tool.outputstringYes
data[].cardsarray of LabCard and objectNo
data[].cards[].schemastringNo

Default: "lab.card.v1".

data[].cards[].kindstringYes
data[].cards[].documentstringYes
data[].cards[].versioninteger (uint64)Yes
data[].cards[].titlestringYes
data[].cards[].summarystringNo

Default: "".

data[].cards[].stateone of "queued", "running", "done", "failed", "cancelled" or always "uncertain" or nullNo

The job the card waits on, if any. Default: null.

data[].cards[].state_textstring or nullNo

Plain words about the state ("Rendering the preview, about 3 min"). Default: null.

data[].cards[].refusalobject or nullNo

A change a kind won't accept, with the sentence every surface shows. Default: null.

data[].cards[].refusal.codestringYes

A stable code clients can branch on (beat_grid, stale_base, ...).

data[].cards[].refusal.messagestringYes

Plain words, shown as is.

data[].cards[].viewone of "video", "image", "compare", "model3d", "playable", "report", "none" or always "unknown"Yes
data[].cards[].primarystring or nullNo

Artifact ids; clients fetch them through the API with their own access. Default: null.

data[].cards[].posterstring or nullNo

Default: null.

data[].cards[].striparray of stringNo

Default: [].

data[].cards[].compareobject or nullNo

Default: null.

data[].cards[].compare.aobjectYes

An immutable version, possibly of another kind's document (a CAD part placed in a Robot Lab scene). Reading through it checks access to both.

data[].cards[].compare.a.documentstringYes
data[].cards[].compare.a.versioninteger (uint64)Yes
data[].cards[].compare.bobjectYes

An immutable version, possibly of another kind's document (a CAD part placed in a Robot Lab scene). Reading through it checks access to both.

data[].cards[].compare.b.documentstringYes
data[].cards[].compare.b.versioninteger (uint64)Yes
data[].cards[].compare.atobjectNo

Where in a version a note points. Default: {"at":"none"}.

data[].cards[].compare.a_primarystring or nullNo

Default: null.

data[].cards[].compare.b_primarystring or nullNo

Default: null.

data[].cards[].notesarray of objectNo

Default: [].

data[].cards[].notes[].locatorobjectYes

Where in a version a note points.

data[].cards[].notes[].authorstringYes
data[].cards[].notes[].textstringYes
data[].cards[].pagestring or nullNo

The kind's deeper page (player, viewport, game). Default: null.

data[].cards[].private_localbooleanNo

Set when an input must stay on its host; shown on the card. Default: false.

data[].cards[].detailanyNo

Kind-specific; clients that don't know it ignore it. Default: null.

data[].cards[].spacestringNo

The space used for artifact reads with the reader's own credentials.

data[].generated_filesarray of anyYes
data[].artifactsarray of anyYes
data[].replyobject or nullNo

Person-visible cards only; model-routing evidence is not included.

data[].reply.cardsarray of objectNo
nextstring or nullYes

Errors

StatusMeaningBody
400, 401, 403, 404, 409, 429, 503

Invalid page, signed out, denied, missing, changed, throttled, or unavailable. A failure is never an empty success.

AppAccountError

Example

curl 'https://api.openagents.com/v1/history/{id}/messages' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"