Sessions

4 operations. {prefix} is the route prefix passed to MapAgentPrism; the template uses /agentprism.

GET {prefix}/api/sessions

Operation ID: AgentPrismListSessions

Lists sessions from most recently updated to oldest.

Paging is offset based: ‘skip’ defaults to 0 and ‘take’ to 50, and ‘take’ is clamped to the 1..200 range rather than rejected, so an out-of-range value never fails the request. ‘agentName’ narrows the list to one agent. Because the order is by last update, a session that changes while a client pages can move between pages; use the session id, not the position, as the identity.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
agentName	query	no	string	—
skip	query	no	integer (int32)	pattern `^-?(?:0\
take	query	no	integer (int32)	pattern `^-?(?:0\

Response	Body	Headers
200 OK	application/json → array of SessionRecord	—

GET {prefix}/api/sessions/{sessionId}

Operation ID: AgentPrismGetSession

Returns a session’s metadata and chat history.

‘messages’ is the readable chat history and is null when the configured session storage cannot expose one — with an in-memory setup the history lives inside an opaque state blob. ‘state’ always carries that raw provider state. Messages come back in sequence order, so the index of a message is the sequence number the branch endpoint expects.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
sessionId	path	yes	string	—

Response	Body	Headers
200 OK	application/json → SessionDetailResponse	—

DELETE {prefix}/api/sessions/{sessionId}

Operation ID: AgentPrismDeleteSession

Deletes a session.

Attachments linked to the session are deleted with it, and this call is the only way they are cleaned up: an attachment may be uploaded before any session exists, so the link is deliberately not a database foreign key. The attachments are removed only after the session itself is found, so a 404 leaves no side effect. Runs recorded under the session are kept — run history does not depend on the session still existing.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
sessionId	path	yes	string	—

Response	Body	Headers
204 No Content	—	—

POST {prefix}/api/sessions/{sessionId}/branch

Operation ID: AgentPrismBranchSession

Branches a conversation from a specific point and opens a new session.

Items up to and including ‘upToSequence’ are COPIED into a NEW conversation; the pointer is only provenance information. Writing to the branch does not change the parent conversation. Branching only works while a persistent SQL provider is enabled; in an in-memory setup, chat history lives in an opaque blob of session state and this returns 501.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
sessionId	path	yes	string	—

Request body (required):

• application/json → SessionBranchRequest

Response	Body	Headers
201 Created	application/json → SessionBranchResult	—
400 Bad Request	application/problem+json → ProblemDetails	—
404 Not Found	application/problem+json → ProblemDetails	—
409 Conflict	application/problem+json → ProblemDetails	—
501 Not Implemented	application/problem+json → ProblemDetails	—