Stepsies API

Create, read, update, and manage step-by-step guides via the API.

The Stepsies API allows you to programmatically create and manage step-by-step guides. This is the core resource of the Stepsies platform.

The Stepsy Object

{
  "id": 123,
  "slug": "email-welcome-sequence",
  "title": "Email Welcome Sequence Blueprint",
  "description": "Create a 5-email welcome sequence that converts.",
  "category": "marketing",
  "status": "published",
  "published_at": "2024-12-04T10:30:00Z",
  "featured": false,
  "featured_at": null,
  "views_count": 150,
  "completions_count": 42,
  "average_rating": 4.5,
  "url": "https://stepsies.com/@sarahchen/email-welcome-sequence",
  "user": {
    "username": "sarahchen",
    "display_name": "Sarah Chen"
  },
  "steps": [
    {
      "id": 1,
      "position": 1,
      "title": "Define Your Sequence Goal",
      "content": "<p>Before writing a single email...</p>"
    }
  ],
  "steps_count": 5,
  "created_at": "2024-12-04T10:00:00Z",
  "updated_at": "2024-12-04T10:30:00Z"
}

Attributes

Field Type Description
id integer Unique identifier
slug string URL-friendly identifier (unique per user)
title string Title of the guide
description string Brief description
category string Content category (see Categories)
status string published or draft
published_at datetime When the guide was published (ISO 8601)
featured boolean Whether the guide is featured/pinned
featured_at datetime When the guide was featured
views_count integer Total number of views
completions_count integer Number of completed views
average_rating float Average user rating (1-5)
url string Public URL of the guide
user object Author information
steps array Array of step objects
steps_count integer Number of steps
created_at datetime Creation timestamp
updated_at datetime Last update timestamp

List Stepsies

GET /api/v1/stepsies

read scope

Returns a list of stepsies for the authenticated user.

Query Parameters

Parameter Type Description
user_id string Filter by username
category string Filter by category
status string published or draft
featured boolean Filter featured only (true)
limit integer Max results (default: 50, max: 100)

Example Request

curl "https://api.stepsies.com/v1/stepsies?status=published&category=marketing" \
  -H "Authorization: Bearer sk_your_api_key"

Example Response

{
  "stepsies": [
    {
      "id": 123,
      "slug": "email-welcome-sequence",
      "title": "Email Welcome Sequence Blueprint",
      "description": "Create a 5-email welcome sequence...",
      "category": "marketing",
      "status": "published",
      "steps_count": 5,
      "views_count": 150,
      "completions_count": 42,
      "created_at": "2024-12-04T10:00:00Z"
    }
  ]
}

Get a Stepsy

GET /api/v1/stepsies/:id

read scope

Retrieves a single stepsy by ID, including all steps.

Path Parameters

Parameter Type Description
id integer The stepsy ID

Example Request

curl https://api.stepsies.com/v1/stepsies/123 \
  -H "Authorization: Bearer sk_your_api_key"

Example Response

{
  "stepsy": {
    "id": 123,
    "slug": "email-welcome-sequence",
    "title": "Email Welcome Sequence Blueprint",
    "description": "Create a 5-email welcome sequence that converts.",
    "category": "marketing",
    "status": "published",
    "steps": [
      {
        "id": 1,
        "position": 1,
        "title": "Define Your Sequence Goal",
        "content": "<p>Before writing a single email...</p>"
      },
      {
        "id": 2,
        "position": 2,
        "title": "Map the 5-Email Arc",
        "content": "<p>Your welcome sequence should...</p>"
      }
    ],
    "steps_count": 5,
    "views_count": 150,
    "completions_count": 42
  }
}

Create a Stepsy

POST /api/v1/stepsies

write scope

Creates a new stepsy. Optionally include steps in the same request.

Request Body

Field Type Required Description
user_id string For admin keys Username to create for
title string Yes Title (max 200 chars)
description string No Description (max 500 chars)
category string No Category slug (default: marketing)
steps array No Array of step objects

Step Object

Field Type Required Description
position integer Yes Order of the step (1-indexed)
title string No Step title (optional)
content string Yes HTML content of the step

Example Request

curl -X POST https://api.stepsies.com/v1/stepsies \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "stepsy": {
      "title": "Email Welcome Sequence Blueprint",
      "description": "Create a 5-email welcome sequence that converts.",
      "category": "marketing",
      "steps": [
        {
          "position": 1,
          "title": "Define Your Sequence Goal",
          "content": "<p>Before writing a single email, clarify your goal...</p>"
        },
        {
          "position": 2,
          "title": "Map the 5-Email Arc",
          "content": "<p>Your welcome sequence should tell a story...</p>"
        }
      ]
    }
  }'

Example Response

HTTP/1.1 201 Created

{
  "stepsy": {
    "id": 124,
    "slug": "email-welcome-sequence-blueprint",
    "title": "Email Welcome Sequence Blueprint",
    "status": "draft",
    "steps_count": 2
  }
}

New stepsies are drafts

Newly created stepsies have status: "draft". Use the publish endpoint to make them public.

Update a Stepsy

PATCH /api/v1/stepsies/:id

write scope

Updates an existing stepsy. Only include fields you want to change.

Request Body

Field Type Description
title string New title
description string New description
category string New category

Example Request

curl -X PATCH https://api.stepsies.com/v1/stepsies/123 \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "stepsy": {
      "title": "Updated Welcome Sequence",
      "category": "product"
    }
  }'

Delete a Stepsy

DELETE /api/v1/stepsies/:id

write scope

Deletes a stepsy. This is a soft delete; the stepsy can be recovered within 30 days.

Example Request

curl -X DELETE https://api.stepsies.com/v1/stepsies/123 \
  -H "Authorization: Bearer sk_your_api_key"

Response

HTTP/1.1 204 No Content

Publish a Stepsy

POST /api/v1/stepsies/:id/publish

write scope

Publishes a draft stepsy, making it publicly accessible.

Example Request

curl -X POST https://api.stepsies.com/v1/stepsies/123/publish \
  -H "Authorization: Bearer sk_your_api_key"

Example Response

{
  "stepsy": {
    "id": 123,
    "status": "published",
    "published_at": "2024-12-04T10:30:00Z",
    "url": "https://stepsies.com/@sarahchen/email-welcome-sequence"
  }
}

Unpublish a Stepsy

POST /api/v1/stepsies/:id/unpublish

write scope

Reverts a published stepsy to draft status.

Example Request

curl -X POST https://api.stepsies.com/v1/stepsies/123/unpublish \
  -H "Authorization: Bearer sk_your_api_key"

Example Response

{
  "stepsy": {
    "id": 123,
    "status": "draft",
    "published_at": null
  }
}

Feature a Stepsy

POST /api/v1/stepsies/:id/feature

admin scope

Pins a stepsy to the top of the user’s profile.

Example Request

curl -X POST https://api.stepsies.com/v1/stepsies/123/feature \
  -H "Authorization: Bearer sk_your_api_key"

Unfeature a Stepsy

POST /api/v1/stepsies/:id/unfeature

admin scope

Removes a stepsy from featured/pinned position.

Categories

Valid category values for stepsies:

Category Description
marketing Lead magnets, campaigns, funnels
product Onboarding, feature tours, tutorials
education Courses, lessons, how-tos
business Processes, SOPs, workflows
creative Design, writing, art tutorials
tech Development, tools, integrations
lifestyle Personal, hobbies, DIY

Error Responses

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "Stepsy not found"
  }
}

422 Validation Failed

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed",
    "details": {
      "title": ["can't be blank"],
      "category": ["is not included in the list"]
    }
  }
}

402 Stepsy Limit Exceeded

{
  "error": {
    "code": "stepsy_limit_exceeded",
    "message": "You have reached your stepsy limit. Please upgrade your plan."
  }
}

On this page