Steps and shared steps

Shared steps are reusable step groups that can be inserted into multiple tests. The routes in this group operate on shared steps directly (not on per-test steps — use Tests for those).

There is no standalone steps or sharedSteps API key scope. For API keys, these routes are controlled via the tests scope: any operation that requires read access maps to tests:read; create, update, and delete operations map to tests:update. See Authentication and Scopes.

All routes require x-project-id and resolve the branch from x-branch-id (or the project default branch if the header is omitted). PUT and DELETE requests require an active subscription and otherwise return 403 { "message": "LICENSE_REQUIRED" }; GET requests do not.

List shared steps

GET /v1/steps/shared

Requires tests:read. Returns shared steps on the active branch, with pagination.

Query parameters

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.

Get a shared step

GET /v1/steps/:stepId

Requires tests:read. :stepId is the canonical step ID. Returns the shared step with its action on the active branch.

Response

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

Status codes

Get a shared group step's children

GET /v1/steps/:stepId/children

Requires tests:read. :stepId is the canonical step ID of a shared group. Returns the parent step and its child steps.

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

Get step usage

GET /v1/steps/:stepId/usage

Requires tests:read. :stepId is the canonical step ID. Returns the tests that use the shared step on the active branch.

Response

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

Update a shared step

PUT /v1/steps/:stepId/update

Requires tests:update. :stepId is the canonical step ID. Accepts multipart/form-data.

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.

Form fields

stepData JSON fields

All fields are optional. 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" }
  }
}

Update a shared group step's children

PUT /v1/steps/:stepId/children

Requires tests:update. :stepId is the revision-step ID of the group (the revisionStepId value returned in step list responses). Accepts multipart/form-data. Replaces the children of a shared group step with the provided array. Steps with a matching revisionStepId are updated in place; steps without one are created; steps in the existing group that are not in the submitted array are deleted.

Form fields

Response

{
  "data": {
    "step": { "id": "step-uuid", "name": "Log in as admin" },
    "children": [
      { "id": "child-uuid", "name": "Go to login page", "order": 0 }
    ]
  }
}

Delete a shared step

DELETE /v1/steps/:stepId

Requires tests:update. :stepId is the canonical step ID. Returns 400 if the step is still referenced by any test on any branch, listing the affected tests.

Response

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

Status codes