RunWhen workspaces API
The workspaces API from RunWhen — 72 operation(s) for workspaces.
OpenAPI Specification
openapi: 3.1.0
info:
title: papi alert-query-proxy workspaces API
description: RunWhen Platform API
version: 2.0.0
tags:
- name: workspaces
paths:
/api/v1/workspaces:
get:
tags:
- workspaces
summary: List workspaces for the current user
description: "List all workspaces the current user has access to.\n\nReturns workspaces where the user is either the owner or has\nexplicit permissions.\n\nArgs:\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 workspaces."
operationId: list_workspaces_api_v1_workspaces_get
parameters:
- 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/WorkspaceListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
post:
tags:
- workspaces
summary: Create a new workspace
description: "Create a new workspace (synchronous, DB-direct).\n\nThis endpoint:\n1. Auto-suffixes the name if it collides with an existing workspace,\n tombstone, repository, or K8s CRD (e.g. ``myws`` -> ``myws-2``).\n2. Creates the workspace DB record and provisions runner infrastructure.\n3. Returns with status=\"ready\" on success.\n\nCreation is synchronous — no polling required after a 201 response."
operationId: create_workspace_api_v1_workspaces_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceGitCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceCreateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_short_name}:
get:
tags:
- workspaces
summary: Get a workspace by name
description: "Get a workspace by its short name.\n\nArgs:\n workspace_short_name: The workspace short name (e.g., 'pp-04').\n detail: If true, include additional details (SLXs, alerts, spec). Defaults to false.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n The workspace details.\n\nRaises:\n HTTPException: 404 if workspace not found or user has no access."
operationId: get_workspace_api_v1_workspaces__workspace_short_name__get
parameters:
- name: workspace_short_name
in: path
required: true
schema:
type: string
title: Workspace Short Name
- name: detail
in: query
required: false
schema:
type: boolean
description: 'If true, load SLXs and firing alerts. Default false: fast metadata-only response.'
default: false
title: Detail
description: 'If true, load SLXs and firing alerts. Default false: fast metadata-only response.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/provisioning-status/{workspace_name}:
get:
tags:
- workspaces
summary: Get workspace provisioning progress
description: 'Get workspace provisioning progress without requiring a DB workspace record.
Non-detail endpoint — bypasses workspace permission checks.
Only requires authentication. Returns boolean stage flags and sync status.
Used by the UI wizard to poll until all provisioning stages complete.
CRD-less mode: workspace creation is synchronous — all stages are
complete if the workspace exists in the database.'
operationId: provisioning_status_api_v1_workspaces_provisioning_status__workspace_name__get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/_ProvisioningStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}:
patch:
tags:
- workspaces
summary: Update a workspace
description: "Update a workspace (partial update).\n\nAccepts workspace name (slug) as the path parameter. All body fields are\noptional; only non-None values are applied.\n\nSupports updating: alias, description, scrubber_config, enabled_locations,\nconfig_provided, permissions (full replacement), slx_groups, slx_relationships.\n\nRequires admin permission on the workspace.\n\nArgs:\n workspace_name: The workspace short name (slug, e.g. 'my-workspace').\n data: The workspace update data.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n The updated workspace (detail view with spec populated).\n\nRaises:\n HTTPException: 404 if workspace not found.\n HTTPException: 403 if user lacks admin permission."
operationId: update_workspace_api_v1_workspaces__workspace_name__patch
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
delete:
tags:
- workspaces
summary: Delete a workspace
description: 'Delete a workspace with full multi-system cleanup.
Phase 1 (sync): Vault secrets, Slack, K8s CRDs, git repo, DB + tombstone.
Phase 2 (async): Sobow, USearch, GCS files, email notification.
Returns step-by-step status for each cleanup operation.
Requires admin permission on the workspace.'
operationId: delete_workspace_api_v1_workspaces__workspace_name__delete
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceDeletionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/workspace-configuration-index:
get:
tags:
- workspaces
summary: Get workspace configuration index
description: "Get the workspace configuration index from sobow.\n\nThe configuration index contains cached workspace data including:\n- SLX metadata and task information\n- Entity index (Kubernetes resources, cloud resources, etc.)\n- Workspace relationships and hierarchies\n\nThis endpoint proxies to the sobow service which owns the canonical\nworkspace configuration index cached in Redis.\n\nArgs:\n workspace_name: The workspace name (not ID).\n session: Database session.\n current_user: The authenticated user.\n sobow: Sobow client for fetching configuration.\n\nReturns:\n The workspace configuration index as a dictionary.\n\nRaises:\n HTTPException: 404 if workspace not found.\n HTTPException: 503 if sobow service is unavailable."
operationId: get_workspace_configuration_index_api_v1_workspaces__workspace_name__workspace_configuration_index_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Workspace Configuration Index Api V1 Workspaces Workspace Name Workspace Configuration Index Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/metadata:
get:
tags:
- workspaces
summary: Get workspace metadata from sobow
description: "Get workspace metadata from sobow service.\n\nReturns metadata about the workspace including index status,\ntask counts, and other operational information.\n\nArgs:\n workspace_name: The workspace name (not ID).\n session: Database session.\n current_user: The authenticated user.\n sobow: Sobow client for fetching metadata.\n\nReturns:\n The workspace metadata as a dictionary, or None if not available.\n\nRaises:\n HTTPException: 404 if workspace not found.\n HTTPException: 503 if sobow service is unavailable."
operationId: get_workspace_metadata_api_v1_workspaces__workspace_name__metadata_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- type: 'null'
title: Response Get Workspace Metadata Api V1 Workspaces Workspace Name Metadata Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/entities:
get:
tags:
- workspaces
summary: Get workspace entities
description: "Get entities (Kubernetes resources, cloud resources, etc.) for a workspace.\n\nEntities are extracted from the workspace configuration and represent\nthe discoverable resources that can be referenced in tasks.\n\nArgs:\n workspace_name: The workspace name (not ID).\n session: Database session.\n current_user: The authenticated user.\n sobow: Sobow client for fetching entities.\n\nReturns:\n Dictionary containing workspace entities organized by type.\n\nRaises:\n HTTPException: 404 if workspace not found.\n HTTPException: 503 if sobow service is unavailable."
operationId: get_workspace_entities_api_v1_workspaces__workspace_name__entities_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Workspace Entities Api V1 Workspaces Workspace Name Entities Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/index-health:
get:
tags:
- workspaces
summary: Get workspace index health
description: "Get the health status of the workspace task index.\n\nReturns information about the index's current state, including\nlast update time, task counts, and any indexing errors.\n\nArgs:\n workspace_name: The workspace name (not ID).\n session: Database session.\n current_user: The authenticated user.\n sobow: Sobow client for fetching health status.\n\nReturns:\n Dictionary containing index health information.\n\nRaises:\n HTTPException: 404 if workspace not found.\n HTTPException: 503 if sobow service is unavailable."
operationId: get_workspace_index_health_api_v1_workspaces__workspace_name__index_health_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Workspace Index Health Api V1 Workspaces Workspace Name Index Health Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/status:
get:
tags:
- workspaces
summary: Get workspace creation status
description: "Get the status of a workspace creation.\n\nThis endpoint is used to poll for workspace creation completion.\nIt checks:\n1. Whether the workspace exists in the database\n2. Whether the WorkSync has successfully reconciled\n\nArgs:\n workspace_name: The workspace name.\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n WorkspaceStatusResponse with workspace and sync booleans."
operationId: get_workspace_status_api_v1_workspaces__workspace_name__status_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/my-permissions:
get:
tags:
- workspaces
summary: Get current user's permissions on workspace
description: 'Get the current user''s permissions (roles) on a workspace.
Returns a list of role strings the user has on this workspace.
This matches the Django implementation which returns a set of roles.'
operationId: get_my_permissions_api_v1_workspaces__workspace_name__my_permissions_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
type: string
title: Response Get My Permissions Api V1 Workspaces Workspace Name My Permissions Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/sync-status:
get:
tags:
- workspaces
summary: Get workspace sync status from WorkSync CRD
description: "Get the sync status for a workspace from the WorkSync Kubernetes CRD.\n\nReturns information about the workspace's GitOps sync status including\nconditions, last applied revision, and related Kubernetes events.\n\nArgs:\n workspace_name: The workspace name (not ID).\n session: Database session.\n current_user: The authenticated user.\n\nReturns:\n Dictionary containing WorkSync status and events.\n\nRaises:\n HTTPException: 404 if workspace not found or no WorkSync CRD exists."
operationId: get_workspace_sync_status_api_v1_workspaces__workspace_name__sync_status_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Workspace Sync Status Api V1 Workspaces Workspace Name Sync Status Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/secrets-keys:
get:
tags:
- workspaces
summary: List workspace secret keys
description: 'Get list of secret key names for a workspace.
Returns only the key names, not the secret values.
Requires read access to the workspace.'
operationId: get_workspace_secret_keys_api_v1_workspaces__workspace_name__secrets_keys_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SecretsKeysResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/secrets:
post:
tags:
- workspaces
summary: Create or update workspace secrets
description: 'Create or update workspace secrets in Vault.
Requires admin access to the workspace.'
operationId: create_workspace_secrets_api_v1_workspaces__workspace_name__secrets_post
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SecretsCreateRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SecretsCreateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/secrets/{secret_key}:
delete:
tags:
- workspaces
summary: Delete a single workspace secret
description: 'Permanently delete a single workspace secret by key.
Requires admin access to the workspace. Mirrors Django''s
``WorkspaceViewSet.delete_workspace_secret``.'
operationId: delete_workspace_secret_api_v1_workspaces__workspace_name__secrets__secret_key__delete
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
- name: secret_key
in: path
required: true
schema:
type: string
title: Secret Key
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SecretDeleteResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/secrets/{secret_key}/usage:
get:
tags:
- workspaces
summary: List where a workspace secret is used
description: 'Return the SLIs and Runbooks that reference this workspace secret.
Used by the UI to warn before deleting a secret that is still in use.
Requires read access to the workspace. Mirrors Django''s
``WorkspaceViewSet.get_secret_usage``.'
operationId: get_workspace_secret_usage_api_v1_workspaces__workspace_name__secrets__secret_key__usage_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
- name: secret_key
in: path
required: true
schema:
type: string
title: Secret Key
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SecretUsageResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/reset-service-account:
post:
tags:
- workspaces
summary: Reset or create workspace service account
description: 'Reset or create the service account for a workspace.
If a service account exists for this workspace, updates its password.
If no service account exists, creates a new one.
Also writes the credentials to Vault for use by SLI/Runbook containers.
Requires admin access to the workspace.'
operationId: reset_workspace_service_account_api_v1_workspaces__workspace_name__reset_service_account_post
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResetServiceAccountRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ResetServiceAccountResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/sa-token:
get:
tags:
- workspaces
summary: Get workspace service account token
description: 'Get the workspace service account token.
Trades an existing valid token for a workspace service account token.
This is used by runners and SLI containers to authenticate with PAPI.
Valid tokenTypes:
- LOCATION_WORKSPACE_SA_TOKEN: Token from location namespace'
operationId: get_workspace_sa_token_api_v1_workspaces__workspace_name__sa_token_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
- name: token
in: query
required: true
schema:
type: string
description: Token to trade for SA token
title: Token
description: Token to trade for SA token
- name: tokenType
in: query
required: true
schema:
type: string
description: Type of token being traded
title: Tokentype
description: Type of token being traded
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SATokenResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/get-gitlab-sas:
get:
tags:
- workspaces
summary: Get GitLab service accounts for workspace
description: 'Get GitLab service accounts for the workspace repository.
Returns service accounts filtered by the user''s access level:
- Admin/readwrite users get both read and write service accounts
- Read-only users get only read service accounts
Returns empty list for non-GitLab (e.g. Gitea) environments.'
operationId: get_gitlab_service_accounts_api_v1_workspaces__workspace_name__get_gitlab_sas_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Gitlab Service Accounts Api V1 Workspaces Workspace Name Get Gitlab Sas Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/task-search:
post:
tags:
- workspaces
summary: Search workspace tasks
description: 'Search for tasks in a workspace.
Supports scoping to specific SLXs and persona-based query interpretation.'
operationId: search_workspace_tasks_api_v1_workspaces__workspace_name__task_search_post
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskSearchRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Search Workspace Tasks Api V1 Workspaces Workspace Name Task Search Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/autocomplete:
post:
tags:
- workspaces
summary: Autocomplete for task search
description: Get autocomplete suggestions for task search.
operationId: autocomplete_workspace_search_api_v1_workspaces__workspace_name__autocomplete_post
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AutocompleteRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Autocomplete Workspace Search Api V1 Workspaces Workspace Name Autocomplete Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/runners:
get:
tags:
- workspaces
summary: Get runners
description: Returns runners registered for this workspace.
operationId: get_runners_api_v1_workspaces__workspace_name__runners_get
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AuthorizedRunner'
title: Response Get Runners Api V1 Workspaces Workspace Name Runners Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/generate-workspace-builder-config:
get:
tags:
- workspaces
summary: '[DEPRECATED] Generate workspace builder config'
description: 'Deprecated: use GET /{workspace_name}/upload-config instead. Returns 410 Gone.'
operationId: generate_workspace_builder_config_api_v1_workspaces__workspace_name__generate_workspace_builder_config_get
deprecated: true
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
title: Workspace Name
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
/api/v1/workspaces/{workspace_name}/search-scope:
get:
tags:
- workspaces
summary: Get search scope options
description: 'Return search scope options for the workspace.
Returns SLX groups, subgroups, and individual SLXs with firing alert status.
Used by the workspace chat page to build the scope selector.'
operationId: get_search_scope_api_v1_workspaces__workspace_name__search_scope_get
parameters:
- name: wor
# --- truncated at 32 KB (148 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/runwhen/refs/heads/main/openapi/runwhen-workspaces-api-openapi.yml