Agent Sessions
33 operations in the Agent Sessions group.
GET /api/resources/{workspace}/sessions
List Product20 agent sessions for a workspace
Operation ID: listAgentSessions
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
status | query | no | string | |
source_kind | query | no | string | |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent sessions | AgentSessionCollectionResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions
Create a Product20 agent session
Operation ID: createAgentSession
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string |
Request body — application/json · AgentSessionCreateRequest (required)
| Field | Type | Required |
|---|---|---|
title | string | yes |
summary | `string | null` |
source_kind | string | yes |
source_ref | `string | null` |
primary_surface | string | no |
selected_target_repo_ids | array<string> | no |
primary_owning_team_id | `string | null` |
budget_owner_team_id | `string | null` |
visibility_scope | enum(workspace, team, private) | no |
effective_policy_hash | `string | null` |
policy_source_refs | array<string> | no |
data_plane_profile_id | `string | null` |
metadata | object | no |
routing_candidates | array<RoutingCandidateInput> | no |
team_scopes | array<SessionTeamScopeInput> | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Created agent session | AgentSessionResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |
GET /api/resources/{workspace}/sessions/{agentSession}
Get a Product20 agent session aggregate
Operation ID: getAgentSession
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session | AgentSessionResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/access
Grant or update access to a Product20 session
Operation ID: shareAgentSessionAccess
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · AgentSessionAccessShareRequest (required)
| Field | Type | Required |
|---|---|---|
subject_type | enum(user, team, share_group) | yes |
subject_id | integer | yes |
role | enum(viewer, commenter, steerer, approver, owner) | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session access updated | AgentSessionAccessShareResponse |
| 201 | Agent session access granted | AgentSessionAccessShareResponse |
| 403 | Forbidden. | — |
| 404 | Share principal not available. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/access-requests
Request access to a Product20 session
Operation ID: requestAgentSessionAccess
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · AgentSessionAccessRequestCreateRequest (required)
| Field | Type | Required |
|---|---|---|
requested_role | enum(viewer, commenter, steerer, approver) | yes |
reason | `string | null` |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Agent session access requested | AgentSessionAccessRequestResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/access-requests/{accessRequestId}/decision
Approve or deny a Product20 session access request
Operation ID: decideAgentSessionAccessRequest
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string | |
accessRequestId | path | yes | string |
Request body — application/json · AgentSessionAccessRequestDecisionRequest (required)
| Field | Type | Required |
|---|---|---|
decision | enum(approve, deny) | yes |
role | `string | null` |
reason | `string | null` |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session access request decided | AgentSessionAccessRequestDecisionResponse |
| 403 | Forbidden. | — |
| 404 | Access request not found. | — |
| 409 | Access request already decided. | — |
DELETE /api/resources/{workspace}/sessions/{agentSession}/access/{aclEntry}
Revoke access to a Product20 session
Operation ID: revokeAgentSessionAccess
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string | |
aclEntry | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session access revoked | AgentSessionAccessRevokeResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/adapter-receipts
Export Product20 neutral-agent adapter receipt evidence
Operation ID: exportAgentSessionAdapterReceipts
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session adapter receipt evidence | AgentSessionAdapterReceiptsResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/approval-audit
Get a Product20 session approval audit feed
Operation ID: getAgentSessionApprovalAudit
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Session approval audit feed | AgentSessionApprovalAuditResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/attempt-graph
Compose a Product20 session attempt graph with conflict warnings
Operation ID: composeAgentSessionAttemptGraph
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Session attempt graph composed | AgentSessionAttemptGraphResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/collaboration
Return Product20 session collaboration projection
Operation ID: showAgentSessionCollaboration
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session collaboration projection | AgentSessionCollaborationResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/collaboration-events
Append a Product20 session collaboration event
Operation ID: storeAgentSessionCollaborationEvent
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · AgentSessionCollaborationEventStoreRequest (required)
| Field | Type | Required |
|---|---|---|
event_kind | enum(task_created, task_assigned, task_reassigned, task_status_changed, mailbox_message_sent, comment_created) | yes |
task_id | `string | null` |
title | `string | null` |
description | `string | null` |
status | `string | null` |
previous_status | `string | null` |
dependencies | `array | null` |
assignees | `array | null` |
assignee | `AgentSessionCollaborationActor | null` |
recipient | `AgentSessionCollaborationActor | null` |
subject | `string | null` |
target | `AgentSessionCollaborationCommentTarget | null` |
thread_id | `string | null` |
body_ciphertext | `string | null` |
body_digest | `string | null` |
body_plaintext | `string | null` |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Agent session collaboration event recorded | AgentSessionCollaborationEventResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/compute-evidence
Export redacted Product20 managed compute evidence for a session
Operation ID: exportAgentSessionComputeEvidence
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session compute evidence | AgentSessionComputeEvidenceResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/context-corrections
Capture a reviewer context correction as a governed candidate
Operation ID: createAgentSessionContextCorrection
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · AgentSessionContextCorrectionCreateRequest (required)
| Field | Type | Required |
|---|---|---|
context_source_id | `integer | string |
correction_kind | enum(missing_context, stale_context, wrong_context, new_memory, promote_to_policy) | yes |
target_kind | enum(memory_candidate, config_candidate) | yes |
title | string | yes |
summary | `string | null` |
proposed_text | `string | null` |
metadata | object | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Created context correction candidate | AgentSessionContextCorrectionResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/context-working-set
Compose a governed Product20 session context working set receipt
Operation ID: composeAgentSessionContextWorkingSet
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Context working set receipt | AgentSessionContextWorkingSetResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/events
Return Product20 session event deltas for cursor backfill
Operation ID: listAgentSessionEvents
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string | |
after_sequence | query | no | integer | |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session event delta backfill | AgentSessionEventDeltaResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/fan-in-review
Compose a Product20 session fan-in review from attempt facts
Operation ID: composeAgentSessionFanInReview
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Session fan-in review composed | AgentSessionFanInReviewResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/governance
Get effective Product20 session budget and review governance
Operation ID: getAgentSessionGovernance
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Effective session governance | AgentSessionGovernanceResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/guardrail-evidence
Export Product20 guardrail and quality evidence
Operation ID: exportAgentSessionGuardrailEvidence
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session guardrail and quality evidence | AgentSessionGuardrailEvidenceResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/mcp-tools
Export Product20 MCP tool governance receipts
Operation ID: exportAgentSessionMcpTools
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session MCP tool governance receipts | AgentSessionMcpToolsResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/memory-retrieval
Retrieve governed memory for a Product20 session from its fenced working set
Operation ID: retrieveAgentSessionMemory
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · AgentSessionMemoryRetrievalRequest (required)
| Field | Type | Required |
|---|---|---|
query | string | yes |
limit | integer | no |
context_source_ids | array<string> | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Memory retrieval receipt | AgentSessionMemoryRetrievalResponse |
| 403 | Forbidden. | — |
| 422 | Requested source is outside the session working set. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/model-routing-decision
Compose a Product20 session model routing decision receipt
Operation ID: composeAgentSessionModelRoutingDecision
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Session model routing decision composed | AgentSessionModelRoutingResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/readiness
Export Product20 session readiness and cold-acceptance blockers
Operation ID: exportAgentSessionReadiness
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session readiness | AgentSessionReadinessResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/receipt-export
Export a signed Product20 agent session receipt bundle
Operation ID: exportAgentSessionReceipt
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Signed agent session receipt export | AgentSessionReceiptExportResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/room
Return Product20 session room aggregate
Operation ID: showAgentSessionRoom
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session room aggregate | AgentSessionRoomResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/routing-decisions
Record a human routing confirmation or correction for a Product20 agent session
Operation ID: createAgentSessionRoutingDecision
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · RoutingDecisionCreateRequest (required)
| Field | Type | Required |
|---|---|---|
selected_routing_candidate_id | `string | null` |
decision_kind | enum(confirmed, corrected, rejected, needs_more_info) | yes |
confidence | `number | null` |
reason | `string | null` |
metadata | object | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Created routing decision | RoutingDecisionResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/run-attempts
Queue the first governed run attempt for a Product20 agent session
Operation ID: queueAgentSessionRunAttempt
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · AgentSessionRunAttemptRequest
| Field | Type | Required |
|---|---|---|
managed_executor_id | `string | null` |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Queued session run attempt | WorkflowRunResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/spend
Export finalized Product20 session spend attribution
Operation ID: exportAgentSessionSpend
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Agent session spend attribution | AgentSessionSpendResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/support-debug
Get a redacted Product20 session support/debug view
Operation ID: getAgentSessionSupportDebug
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Redacted session support/debug view | AgentSessionSupportDebugResponse |
| 403 | Forbidden. | — |
GET /api/resources/{workspace}/sessions/{agentSession}/trace-export
Export a signed Product20 agent session trace bundle
Operation ID: exportAgentSessionTrace
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Signed agent session trace export | AgentSessionTraceExportResponse |
| 403 | Forbidden. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/verification-attempts
Record a Product20 session verification attempt
Operation ID: createAgentSessionVerificationAttempt
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · SessionVerificationAttemptCreateRequest (required)
| Field | Type | Required |
|---|---|---|
workflow_run_id | `string | null` |
attempt_kind | enum(verification, repair_verification, manual_review) | no |
status | enum(passed, failed, needs_review, error) | yes |
verification_pack | object | no |
summary | `string | null` |
artifact_refs | array<string> | no |
repair_recommendation | object | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Recorded verification attempt | SessionVerificationAttemptRecordedResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/verification-pack
Resolve a Product20 session verification pack from policy receipts
Operation ID: resolveAgentSessionVerificationPack
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · SessionVerificationPackResolveRequest
| Field | Type | Required |
|---|---|---|
workflow_run_id | `string | null` |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Resolved verification pack | SessionVerificationPackResolvedResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |
POST /api/resources/{workspace}/sessions/{agentSession}/verification-repair-handoffs
Create a bounded repair or human-review handoff for a failed verification attempt
Operation ID: createAgentSessionVerificationRepairHandoff
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
workspace | path | yes | string | |
agentSession | path | yes | string |
Request body — application/json · SessionVerificationRepairHandoffCreateRequest (required)
| Field | Type | Required |
|---|---|---|
verification_attempt_id | string | yes |
requested_action | enum(bounded_repair, human_review) | no |
reason | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Verification repair handoff created | SessionVerificationRepairHandoffResponse |
| 403 | Forbidden. | — |
| 422 | Validation error. | — |