Shared steps

Shared steps are reusable step groups that can be embedded in multiple tests. Shared steps are authorized through the tests scope: reading uses tests:read; updating and deleting use tests:update together with tests:read. To rearrange the steps of a single test, or to turn a step into a shared one, see Steps.

GET actions take their inputs as query parameters; all other actions, including DELETE, take a JSON body. All actions require x-project-id. The branch is resolved from x-branch-id or the project default branch. Actions that change data require an active subscription and otherwise return 403 { "error": "LICENSE_REQUIRED" }; GET actions do not.

See Authentication and Scopes.

stepId on this page is the canonical step ID, not a revision-step ID.

List shared steps

GET /v1/actions/shared-steps.list

Scope: tests:read

Returns shared steps on the active branch, with pagination.

Query parameters

Parameter	Type	Default	Notes
`limit`	integer	`50`	Results per page. 1 to 1000.
`page`	integer	`0`	Zero-based page index.
`search`	string	-	Substring search on step name.
`type`	string	`all`	`all`, `ui`, or `api`.

Response

{
  "data": [
    {
      "id": "step-uuid",
      "name": "Log in as admin",
      "action": { "name": "group", "description": "Log in as admin" },
      "shared": true,
      "group": true
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 50,
    "total": 4,
    "totalPages": 1,
    "hasMore": false
  }
}

Screenshot data is stripped from action payloads in all list and detail responses.

Example

curl -s "https://api.smoothdeploy.com/v1/actions/shared-steps.list?limit=50&page=0" \
  -H "x-api-key: $SMOOTHDEPLOY_API_KEY" \
  -H "x-project-id: $PROJECT_ID"

Get a shared step

GET /v1/actions/shared-steps.get

Scope: tests:read

Returns the shared step with its action on the active branch.

Query parameters

Parameter	Type	Required	Notes
`stepId`	UUID	yes	The shared step.

Response

{
  "data": {
    "id": "step-uuid",
    "name": "Log in as admin",
    "action": { "name": "group", "description": "Log in as admin" },
    "shared": true,
    "group": true
  }
}

Status codes

Status	Meaning
`200`	Step found
`404`	Shared step not found on this branch

Get a shared group step's children

GET /v1/actions/shared-steps.get-children

Scope: tests:read

Returns the parent step and its child steps for a shared group.

Query parameters

Parameter	Type	Required	Notes
`stepId`	UUID	yes	The shared group step.

Response

{
  "data": {
    "step": {
      "id": "step-uuid",
      "name": "Log in as admin",
      "group": true,
      "shared": true
    },
    "children": [
      {
        "id": "child-step-uuid",
        "name": "Go to login page",
        "action": { "name": "goto", "url": "/login" },
        "order": 0
      }
    ]
  }
}

Status codes

Status	Meaning
`200`	Group found
`404`	Shared group step not found

Get step usage

GET /v1/actions/shared-steps.get-usage

Scope: tests:read

Returns the tests that use the shared step on the active branch.

Query parameters

Parameter	Type	Required	Notes
`stepId`	UUID	yes	The shared step.

Response

{
  "data": [
    { "id": "test-uuid", "name": "Login flow" },
    { "id": "test-uuid-2", "name": "Checkout flow" }
  ]
}

Update a shared step

PUT /v1/actions/shared-steps.update

Scope: tests:read and tests:update

The server applies copy-on-write: if the action changes and other branches reference this step, a new step record is created rather than mutating the shared one.

Body

Field	Required	Notes
`stepId`	yes	UUID of the shared step.
`name`	no	New display name.
`action`	no	New action payload. Structure depends on the action type and is generated by the step editor.
`metadata`	no	Step metadata (e.g. screenshot references).
`condition`	no	Step condition (skip, always-run, or conditional).
`files`	no	Up to 50 files for a `setInputFiles` action, each `{ "name": string, "type": string (optional), "base64": string }`.

Omit a field to leave it unchanged.

Response

{
  "data": {
    "id": "step-uuid",
    "name": "Log in as admin",
    "action": { "name": "group", "description": "Log in as admin" }
  }
}

Status codes

Status	Meaning
`200`	Updated
`400`	The `action` fails validation
`404`	Shared step not found
`409`	No test uses the step, so it can only be deleted

To change the children of a shared group, use steps.update-children.

Delete a shared step

DELETE /v1/actions/shared-steps.delete

Scope: tests:read and tests:update

Deletes a shared step that no test uses. Returns 400 if the step is still referenced by any test on any branch, naming the branches.

Body

Field	Required	Notes
`stepId`	yes	UUID of the shared step.

Response

{
  "message": "Shared step deleted successfully",
  "data": { "id": "step-uuid", "shared": true, "group": true }
}

Status codes

Status	Meaning
`200`	Deleted
`400`	Step is in use
`404`	Shared step not found

On this page