RunWhen run-sessions API
The run-sessions API from RunWhen — 20 operation(s) for run-sessions.
OpenAPI Specification
openapi: 3.1.0
info:
title: papi alert-query-proxy run-sessions API
description: RunWhen Platform API
version: 2.0.0
tags:
- name: run-sessions
paths:
/api/v1/run-sessions:
post:
tags:
- run-sessions
summary: Create a new run session
description: "Create a new run session.\n\nA RunSession tracks a series of RunRequests for a troubleshooting session.\nIf no name is provided and generate_name is True, a unique name will be generated.\n\nArgs:\n data: The run session creation data.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n The created run session.\n\nRaises:\n HTTPException: 400 if workspace not found or name already exists."
operationId: create_run_session_api_v1_run_sessions_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
get:
tags:
- run-sessions
summary: List run sessions
description: "List run sessions for a workspace.\n\nArgs:\n workspace_id: The workspace ID to filter by.\n active_only: If True, return only active sessions.\n limit: Maximum number of results to return.\n offset: Number of results to skip.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n Paginated list of run sessions.\n\nRaises:\n HTTPException: 400 if workspace not found."
operationId: list_run_sessions_api_v1_run_sessions_get
parameters:
- name: workspace_id
in: query
required: true
schema:
type: integer
description: Workspace ID to filter sessions
title: Workspace Id
description: Workspace ID to filter sessions
- name: active_only
in: query
required: false
schema:
type: boolean
description: Filter to active sessions only
default: false
title: Active Only
description: Filter to active sessions only
- name: limit
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
description: Maximum number of results
default: 100
title: Limit
description: Maximum number of results
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Number of results to skip
default: 0
title: Offset
description: Number of results to skip
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/run-sessions/{session_id}:
get:
tags:
- run-sessions
summary: Get a run session by ID
description: "Get a run session by ID.\n\nArgs:\n session_id: The run session ID.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n The run session details.\n\nRaises:\n HTTPException: 404 if session not found."
operationId: get_run_session_api_v1_run_sessions__session_id__get
parameters:
- name: session_id
in: path
required: true
schema:
type: integer
title: Session Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
patch:
tags:
- run-sessions
summary: Update a run session
description: "Update a run session (partial update).\n\nArgs:\n session_id: The run session ID.\n data: The run session update data.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n The updated run session.\n\nRaises:\n HTTPException: 404 if session not found."
operationId: update_run_session_api_v1_run_sessions__session_id__patch
parameters:
- name: session_id
in: path
required: true
schema:
type: integer
title: Session Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
delete:
tags:
- run-sessions
summary: Delete a run session
description: "Delete a run session.\n\nThis will also delete all associated RunRequests (cascade delete).\n\nArgs:\n session_id: The run session ID.\n session: Database session.\n current_user: The authenticated user.\n\nRaises:\n HTTPException: 404 if session not found."
operationId: delete_run_session_api_v1_run_sessions__session_id__delete
parameters:
- name: session_id
in: path
required: true
schema:
type: integer
title: Session Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/run-sessions/{session_id}/deactivate:
post:
tags:
- run-sessions
summary: Deactivate a run session
description: "Deactivate a run session.\n\nSets the session's active flag to False. Inactive sessions cannot accept\nnew RunRequests but can still be viewed and referenced.\n\nArgs:\n session_id: The run session ID.\n data: Optional deactivation request with reason.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n The deactivated run session.\n\nRaises:\n HTTPException: 404 if session not found.\n HTTPException: 400 if session is already inactive."
operationId: deactivate_run_session_api_v1_run_sessions__session_id__deactivate_post
parameters:
- name: session_id
in: path
required: true
schema:
type: integer
title: Session Id
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/DeactivateRequest'
- type: 'null'
title: Data
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/run-sessions/{session_id}/escalate:
post:
tags:
- run-sessions
summary: Escalate a run session
description: "Mark a run session as escalated.\n\nEscalation flags the session as requiring human attention. This is used\nfor issue triage and prioritization.\n\nArgs:\n session_id: The run session ID.\n data: Optional escalation request with escalated status.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n The escalated run session.\n\nRaises:\n HTTPException: 404 if session not found."
operationId: escalate_run_session_api_v1_run_sessions__session_id__escalate_post
parameters:
- name: session_id
in: path
required: true
schema:
type: integer
title: Session Id
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/EscalateRequest'
- type: 'null'
title: Data
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runsessions:
get:
tags:
- run-sessions
summary: List run sessions for a workspace
description: "List run sessions for a workspace by name.\n\nArgs:\n workspace_name: The workspace short name.\n page: Page number (1-indexed).\n page_size: Number of items per page.\n active: Optional exact-match filter on ``RunSession.active``.\n modified__gte: Inclusive lower bound on ``modified_at``.\n modified__lte: Inclusive upper bound on ``modified_at``.\n created__gte: Inclusive lower bound on ``created_at``.\n created__lte: Inclusive upper bound on ``created_at``.\n runrequest__runbook__name: Filter by a single SLX full name\n (e.g. ``workspace--short-name``).\n runrequest__runbook__name__in: Filter by multiple SLX full names,\n comma-separated (e.g. ``ws--slx-a,ws--slx-b``). Ignored when\n ``runrequest__runbook__name`` is provided (single-name takes\n precedence).\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n Paginated list of run sessions.\n\nRaises:\n HTTPException: 400 if any unsupported query parameter is sent.\n HTTPException: 404 if workspace not found."
operationId: list_workspace_run_sessions_api_v1_workspaces__workspace_name__runsessions_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
description: Page number
default: 1
title: Page
description: Page number
- name: page-size
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
description: Items per page
default: 100
title: Page-Size
description: Items per page
- name: active
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: If set, filter to sessions whose ``active`` column matches this value (``true`` for active, ``false`` for inactive). Omit to return both.
title: Active
description: If set, filter to sessions whose ``active`` column matches this value (``true`` for active, ``false`` for inactive). Omit to return both.
- name: modified__gte
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Filter to sessions with modified_at >= this ISO-8601 datetime. Must include a timezone offset (e.g. ``...+00:00`` or ``...Z``); naive datetimes are rejected to avoid ambiguity against the tz-aware column.
title: Modified Gte
description: Filter to sessions with modified_at >= this ISO-8601 datetime. Must include a timezone offset (e.g. ``...+00:00`` or ``...Z``); naive datetimes are rejected to avoid ambiguity against the tz-aware column.
- name: modified__lte
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Filter to sessions with modified_at <= this ISO-8601 datetime. Must include a timezone offset.
title: Modified Lte
description: Filter to sessions with modified_at <= this ISO-8601 datetime. Must include a timezone offset.
- name: created__gte
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Filter to sessions with created_at >= this ISO-8601 datetime. Must include a timezone offset.
title: Created Gte
description: Filter to sessions with created_at >= this ISO-8601 datetime. Must include a timezone offset.
- name: created__lte
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Filter to sessions with created_at <= this ISO-8601 datetime. Must include a timezone offset.
title: Created Lte
description: Filter to sessions with created_at <= this ISO-8601 datetime. Must include a timezone offset.
- name: runrequest__runbook__name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by SLX/runbook full name (e.g. workspace--short-name). Returns only sessions with at least one RunRequest for this SLX.
title: Runrequest Runbook Name
description: Filter by SLX/runbook full name (e.g. workspace--short-name). Returns only sessions with at least one RunRequest for this SLX.
- name: runrequest__runbook__name__in
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by multiple SLX/runbook full names (comma-separated). Returns sessions with at least one RunRequest matching any name.
title: Runrequest Runbook Name In
description: Filter by multiple SLX/runbook full names (comma-separated). Returns sessions with at least one RunRequest matching any name.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
post:
tags:
- run-sessions
summary: Create a run session with run requests
description: "Create a new run session with run requests atomically.\n\nThis endpoint creates a RunSession and associated RunRequests in a single\natomic transaction. It supports deduplication to merge requests into\nexisting sessions based on the source type.\n\n**Deduplication behavior by source:**\n- `direct`: No deduplication - always creates a new session\n- `search`: No deduplication - always creates a new session\n- `slo_alert`: Deduplication enabled (10m window by default)\n- `sli_alert`: Deduplication enabled (10m window by default)\n- `webhook`: Deduplication enabled (10m window by default)\n\n**Status codes:**\n- 201: New session created\n- 200: Merged into existing session (via deduplication)\n- 422: Validation errors (all errors returned)\n\nArgs:\n workspace_name: The workspace short name.\n data: The run session creation request with run requests.\n response: FastAPI response object for setting status code.\n db_session: Database session.\n current_user: The authenticated user.\n\nReturns:\n RunSessionCreateResponse with the session and created flag.\n\nRaises:\n HTTPException: 404 if workspace not found.\n HTTPException: 422 if run request validation fails."
operationId: create_runsession_with_requests_api_v1_workspaces__workspace_name__runsessions_post
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionCreateWithRequests'
responses:
'200':
description: Merged into existing session
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionResponse'
'201':
description: New session created
'422':
description: Validation errors in run requests
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runsessions/search:
post:
tags:
- run-sessions
summary: Search Workspace Run Sessions
description: Search RunSessions with time-bounded filtering.
operationId: search_workspace_run_sessions_api_v1_workspaces__workspace_name__runsessions_search_post
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionSearchRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionSearchResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runsessions/search/sources:
get:
tags:
- run-sessions
summary: Get Search Sources
description: Get available source filter values for RunSession search.
operationId: get_search_sources_api_v1_workspaces__workspace_name__runsessions_search_sources_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SourcesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runsessions/{runsession_id}/alerts:
get:
tags:
- run-sessions
summary: Get Runsession Alerts
description: Get alerts routed to a specific RunSession.
operationId: get_runsession_alerts_api_v1_workspaces__workspace_name__runsessions__runsession_id__alerts_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
- name: runsession_id
in: path
required: true
schema:
type: integer
title: Runsession Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionAlertsListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runsessions/{runsession_id}:
get:
tags:
- run-sessions
summary: Get a run session by ID within a workspace
description: "Get a run session by ID within a workspace.\n\nArgs:\n workspace_name: The workspace short name.\n runsession_id: The run session ID.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n The run session details.\n\nRaises:\n HTTPException: 404 if workspace or session not found."
operationId: get_workspace_run_session_api_v1_workspaces__workspace_name__runsessions__runsession_id__get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
- name: runsession_id
in: path
required: true
schema:
type: integer
description: RunSession ID
title: Runsession Id
description: RunSession ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
patch:
tags:
- run-sessions
summary: Update a run session within a workspace
description: Update a run session within a workspace (partial update).
operationId: patch_workspace_run_session_api_v1_workspaces__workspace_name__runsessions__runsession_id__patch
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
- name: runsession_id
in: path
required: true
schema:
type: integer
description: RunSession ID
title: Runsession Id
description: RunSession ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunSessionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runsessions/{runsession_id}/summary:
get:
tags:
- run-sessions
summary: Get run session summary from Sobrain
description: Proxy to Sobrain service for LLM-generated run session summary.
operationId: get_workspace_run_session_summary_api_v1_workspaces__workspace_name__runsessions__runsession_id__summary_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
- name: runsession_id
in: path
required: true
schema:
type: integer
description: RunSession ID
title: Runsession Id
description: RunSession ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Workspace Run Session Summary Api V1 Workspaces Workspace Name Runsessions Runsession Id Summary Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runsessions/{runsession_id}/activities:
get:
tags:
- run-sessions
summary: Get run session activity timeline
description: 'Proxy to Activities service for run session timeline.
Returns paginated response matching Django''s DRF PageNumberPagination
format: {count, next, previous, results}.'
operationId: get_workspace_run_session_activities_api_v1_workspaces__workspace_name__runsessions__runsession_id__activities_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
- name: runsession_id
in: path
required: true
schema:
type: integer
description: RunSession ID
title: Runsession Id
description: RunSession ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Workspace Run Session Activities Api V1 Workspaces Workspace Name Runsessions Runsession Id Activities Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runsessions/{runsession_id}/step:
post:
tags:
- run-sessions
summary: Process the next step in the RunSession workflow
description: "Process the next step in the RunSession workflow.\n\nThis endpoint coordinates several background tasks:\n1. Processes queued RunRequests that are ready to run (if any)\n2. Marks relevant issues as visited\n3. Triggers persona tasks if a persona is attached\n\nArgs:\n workspace_name: The workspace short name.\n runsession_id: The RunSession ID.\n db_session: Database session.\n current_user: The authenticated user.\n\nReturns:\n StepResponse with processing status.\n\nRaises:\n HTTPException: 404 if workspace or session not found."
operationId: step_runsession_api_v1_workspaces__workspace_name__runsessions__runsession_id__step_post
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
- name: runsession_id
in: path
required: true
schema:
type: integer
description: RunSession ID
title: Runsession Id
description: RunSession ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StepResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v3/workspaces/{workspace_name}/runsessions:
get:
tags:
- run-sessions
summary: List run sessions for a workspace
description: "List run sessions for a workspace by name.\n\nArgs:\n workspace_name: The workspace short name.\n page: Page number (1-indexed).\n page_size: Number of items per page.\n active: Optional exact-match filter on ``RunSession.active``.\n modified__gte: Inclusive lower bound on ``modified_at``.\n modified__lte: Inclusive upper bound on ``modified_at``.\n created__gte: Inclusive lower bound on ``created_at``.\n created__lte: Inclusive upper bound on ``created_at``.\n runrequest__runbook__name: Filter by a single SLX full name\n (e.g. ``workspace--short-name``).\n runrequest__runbook__name__in: Filter by multiple SLX full names,\n comma-separated (e.g. ``ws--slx-a,ws--slx-b``). Ignored when\n ``runrequest__runbook__name`` is provided (single-name takes\n precedence).\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n Paginated list of run sessions.\n\nRaises:\n HTTPException: 400 if any unsupported query parameter is sent.\n HTTPException: 404 if workspace not found."
operationId: list_workspace_run_sessions_api_v3_workspaces__workspace_name__runsessions_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
description: Workspace short name
title: Workspace Name
description: Workspace short name
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
description: Page number
default: 1
title: Page
description: Page number
- name: page-size
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
description: Items per page
default: 100
title: Page-Size
description: Items per page
- name: active
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: If set, filter to sessions whose ``active`` column matches this value (``true`` for active, ``false`` for inactive). Omit to return both.
title: Active
description: If set, filter to sessions whose ``active`` column matches this value (``true`` for active, ``false`` for inactive). Omit to return both.
- name: modified__gte
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Filter to sessions with modified_at >= this ISO-8601 datetime. Must include a timezone offset (e.g. ``...+00:00`` or ``...Z``); naive datetimes are rejected to avoid ambiguity against the tz-aware column.
title: Modified Gte
description: Filter to sessions with modified_at >= this ISO-8601 datetime. Must include a timezone offset (e.g. ``...+00:00`` or ``...Z``); naive datetimes are rejected to avoid ambiguity against the tz-aware column.
- name: modified__lte
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Filter to sessions with modified_at <= this ISO-8601 datetime. Must include a timezone offset.
title: Modified Lte
description: Filter to sessions with modified_at <= this ISO-8601 datetime. Must include a timezone offset.
- name: created__gte
in: query
required: false
schema:
anyOf
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/runwhen/refs/heads/main/openapi/runwhen-run-sessions-api-openapi.yml