---
title: Shared Steps
description: Create and manage reusable named test snippets via the Smoketest API.
---

# Shared Steps

Shared Steps are project-scoped reusable markdown snippets. In the app, users insert them into tests from the slash menu as chips. In stored markdown, a chip is represented as a stable link token:

```markdown
[Log in](smoketest-shared-step:018effff-abcd-7000-8000-abc123456789)
```

Shared Steps cannot reference other Shared Steps yet. A Shared Step cannot be deleted while any Test references it.

## The Shared Step object

```json
{
  "id": "018effff-abcd-7000-8000-abc123456789",
  "name": "Log in",
  "description": "Open login, enter credentials, submit, and verify the dashboard.",
  "referencedTestCount": 2,
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:30:00.000Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | UUID | Unique identifier |
| `name` | string | Display name, unique within the project |
| `description` | string | Markdown-backed reusable steps |
| `referencedTestCount` | number | Number of Tests that reference this Shared Step |
| `createdAt` | ISO 8601 | Creation timestamp |
| `updatedAt` | ISO 8601 | Last updated timestamp |

---

## List Shared Steps

<ApiPlayground
  method="GET"
  path="/v1/projects/:projectId/shared-steps"
  scope="read"
  pathParams={[{ name: "projectId", type: "UUID", required: true, placeholder: "018e5678-abcd-7000-8000-abc123456789", description: "Project ID" }]}
/>

```bash
curl "https://api.smoketest.sh/v1/projects/018e5678-abcd-7000-8000-abc123456789/shared-steps" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"
```

---

## Create a Shared Step

<ApiPlayground
  method="POST"
  path="/v1/projects/:projectId/shared-steps"
  scope="write"
  pathParams={[{ name: "projectId", type: "UUID", required: true, placeholder: "018e5678-abcd-7000-8000-abc123456789", description: "Project ID" }]}
  bodyParams={[
    { name: "name", type: "string", required: true, placeholder: "Log in", description: "Display name, unique within the project" },
    { name: "description", type: "string", required: true, placeholder: "Open login, enter credentials…", description: "Reusable markdown steps" },
  ]}
/>

```bash
curl -X POST "https://api.smoketest.sh/v1/projects/018e5678-abcd-7000-8000-abc123456789/shared-steps" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Log in",
    "description": "Open login, enter credentials, submit, and verify the dashboard."
  }'
```

---

## Get, update, or delete a Shared Step

<ApiPlayground
  method="GET"
  path="/v1/shared-steps/:id"
  scope="read"
  pathParams={[{ name: "id", type: "UUID", required: true, placeholder: "018effff-abcd-7000-8000-abc123456789", description: "Shared Step ID" }]}
/>

```bash
curl "https://api.smoketest.sh/v1/shared-steps/018effff-abcd-7000-8000-abc123456789" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"
```

Update a Shared Step:

```bash
curl -X PATCH "https://api.smoketest.sh/v1/shared-steps/018effff-abcd-7000-8000-abc123456789" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Open login, enter credentials, submit, and verify the dashboard nav." }'
```

Delete a Shared Step:

```bash
curl -X DELETE "https://api.smoketest.sh/v1/shared-steps/018effff-abcd-7000-8000-abc123456789" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"
```