Admin — provisioning workflows

12 endpoints in this group. All paths are prefixed with /api/v1.

Endpoints in this group#

• GET /api/v1/admin/provisioning/definitions — Admin List Definitions
• POST /api/v1/admin/provisioning/definitions — Admin Create Definition
• POST /api/v1/admin/provisioning/definitions/validate — Admin Validate Definition
• GET /api/v1/admin/provisioning/definitions/{definition_id} — Admin Get Definition
• PATCH /api/v1/admin/provisioning/definitions/{definition_id} — Admin Update Definition
• POST /api/v1/admin/provisioning/definitions/{definition_id}/clone-as-new-version — Admin Clone As New Version
• GET /api/v1/admin/provisioning/definitions/{definition_id}/usage — Admin Definition Usage
• GET /api/v1/admin/provisioning/handlers — Admin List Handlers
• GET /api/v1/admin/provisioning/workflows — Admin List Workflows
• POST /api/v1/admin/provisioning/workflows/{workflow_id}/force-complete — Admin Force Complete
• POST /api/v1/admin/provisioning/workflows/{workflow_id}/retry-step/{step_name} — Admin Retry Step
• POST /api/v1/admin/provisioning/workflows/{workflow_id}/rollback — Admin Rollback Workflow

GET /api/v1/admin/provisioning/definitions — Admin List Definitions {#get-api-v1-admin-provisioning-definitions}#

List workflow definitions. Newest version per (service, type) first.

Parameters:

• service_slug (query, string, optional)
• workflow_type (query, string, optional)
• include_inactive (query, boolean, optional)
• authorization (header, string, optional)

Responses:

• 200 — Successful Response. Returns: ApiResponse_list_DefinitionSummary__ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

POST /api/v1/admin/provisioning/definitions — Admin Create Definition {#post-api-v1-admin-provisioning-definitions}#

Validate-then-insert a new workflow definition.

Auto-bumps version when (service_slug, workflow_type) already exists. Rejects with 400 on validation failure; the error envelope includes the structured rule-code list so the UI can highlight failing lines.

Parameters:

• authorization (header, string, optional)

Body: DefinitionCreateRequest — {service_slug, workflow_type, steps_definition, description + 1 more}

Responses:

• 201 — Successful Response. Returns: ApiResponse_DefinitionDetail_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

POST /api/v1/admin/provisioning/definitions/validate — Admin Validate Definition {#post-api-v1-admin-provisioning-definitions-validate}#

Run the validator without persisting. Always returns 200 — the result's ok field tells you whether the definition would pass.

Powers the editor's "Validate" button: red-gutter markers on the JSON body come from errors[*].path.

Parameters:

• authorization (header, string, optional)

Body: DefinitionValidateRequest — {steps_definition}

Responses:

• 200 — Successful Response. Returns: ApiResponse_ValidationResultOut_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

GET /api/v1/admin/provisioning/definitions/{definition_id} — Admin Get Definition {#get-api-v1-admin-provisioning-definitions-definition-id}#

Parameters:

• definition_id (path, string, required)
• authorization (header, string, optional)

Responses:

• 200 — Successful Response. Returns: ApiResponse_DefinitionDetail_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

PATCH /api/v1/admin/provisioning/definitions/{definition_id} — Admin Update Definition {#patch-api-v1-admin-provisioning-definitions-definition-id}#

Update metadata only: description, is_active. The steps_definition field is intentionally not editable here — clone it as a new version instead so any in-flight workflows finish on the definition they started on.

Parameters:

• definition_id (path, string, required)
• authorization (header, string, optional)

Body: DefinitionUpdateRequest — {description, is_active, ui_layout}

Responses:

• 200 — Successful Response. Returns: ApiResponse_DefinitionDetail_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

POST /api/v1/admin/provisioning/definitions/{definition_id}/clone-as-new-version — Admin Clone As New Version {#post-api-v1-admin-provisioning-definitions-definition-id-clone-as-new-version}#

Create a new version of an existing definition with edited steps.

The new row inherits service_slug + workflow_type from the source, gets version = max_existing_version + 1, defaults is_active=True, and runs through the validator. The source row's is_active is left alone — deactivate it explicitly to retire.

Parameters:

• definition_id (path, string, required)
• authorization (header, string, optional)

Body: DefinitionCloneRequest — {steps_definition, description, ui_layout}

Responses:

• 201 — Successful Response. Returns: ApiResponse_DefinitionDetail_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

GET /api/v1/admin/provisioning/definitions/{definition_id}/usage — Admin Definition Usage {#get-api-v1-admin-provisioning-definitions-definition-id-usage}#

How many workflows have attached to this definition, broken down by status? Used by the UI to render a "safe to deactivate?" hint.

Parameters:

• definition_id (path, string, required)
• authorization (header, string, optional)

Responses:

• 200 — Successful Response. Returns: ApiResponse_DefinitionUsage_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

GET /api/v1/admin/provisioning/handlers — Admin List Handlers {#get-api-v1-admin-provisioning-handlers}#

List every registered step handler with its declared metadata.

Powers designer autocomplete + node-palette UIs. Includes built-in handlers from services/provisioning/handlers/common.py and anything third-party packages have registered via the scaicontrol.provisioning.handlers entry-point group.

Parameters:

• authorization (header, string, optional)

Responses:

• 200 — Successful Response. Returns: ApiResponse_list_HandlerInfo__ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

GET /api/v1/admin/provisioning/workflows — Admin List Workflows {#get-api-v1-admin-provisioning-workflows}#

List all provisioning workflows across all tenants.

Parameters:

• authorization (header, string, optional)

Responses:

• 200 — Successful Response. Returns: ApiResponse_list_WorkflowResponse__ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

POST /api/v1/admin/provisioning/workflows/{workflow_id}/force-complete — Admin Force Complete {#post-api-v1-admin-provisioning-workflows-workflow-id-force-complete}#

Force-complete a workflow, marking all non-terminal steps as skipped.

This is an admin escape hatch for stuck workflows. All pending, running, waiting_callback, and waiting_poll steps are marked as skipped, and the workflow is marked as completed.

Parameters:

• workflow_id (path, string, required)
• authorization (header, string, optional)

Responses:

• 200 — Successful Response. Returns: ApiResponse_WorkflowDetailResponse_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

POST /api/v1/admin/provisioning/workflows/{workflow_id}/retry-step/{step_name} — Admin Retry Step {#post-api-v1-admin-provisioning-workflows-workflow-id-retry-step-step-name}#

Retry a failed step in a workflow.

Resets the step to pending status with incremented retry count and re-runs execution.

Parameters:

• workflow_id (path, string, required)
• step_name (path, string, required)
• authorization (header, string, optional)

Responses:

• 200 — Successful Response. Returns: ApiResponse_WorkflowDetailResponse_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}

POST /api/v1/admin/provisioning/workflows/{workflow_id}/rollback — Admin Rollback Workflow {#post-api-v1-admin-provisioning-workflows-workflow-id-rollback}#

Roll back a workflow by executing compensating actions in reverse order.

Parameters:

• workflow_id (path, string, required)
• authorization (header, string, optional)

Responses:

• 200 — Successful Response. Returns: ApiResponse_WorkflowDetailResponse_ — {data, meta}
• 422 — Validation Error. Returns: HTTPValidationError — {detail}