Sessions

4 operations. {prefix} is the route prefix passed to MapTracon; the template uses /tracon.

GET {prefix}/api/sessions

Operation ID: TraconListSessions

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. If a registered IRunAuthorizationHandler denies the caller, the response is 403 — a denied list is REJECTED, never quietly shortened. When session ownership is turned on, the list is additionally narrowed to the calling user’s own sessions before paging is applied, unless the caller satisfies the configured management policy; sessions written before ownership was turned on carry no owner and appear only in that management listing.

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	—
403 Forbidden	application/problem+json → ProblemDetails	—

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

Operation ID: TraconGetSession

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. If a registered IRunAuthorizationHandler denies the caller, the response is 404 — identical to a session that does not exist, so a denial never confirms the session’s existence. With session ownership turned on, another user’s session answers the same 404.

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	—
404 Not Found	application/problem+json → ProblemDetails	—

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

Operation ID: TraconDeleteSession

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. If a registered IRunAuthorizationHandler denies the caller, the response is also 404, identical to a session that does not exist; with session ownership turned on, another user’s session answers that same 404 and is left untouched.

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	—	—
404 Not Found	application/problem+json → ProblemDetails	—

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

Operation ID: TraconBranchSession

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. If a registered IRunAuthorizationHandler denies the caller, the response is 404, identical to a session that does not exist; with session ownership turned on, another user’s session answers that same 404. The new session inherits the SOURCE session’s owner, not the caller’s — a branch is a copy, not a handover.

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	—