Steps

Steps are the individual pages or sections that make up a journey. Each step represents a distinct stage in your workflow that users progress through. On this page, we'll dive into the different step endpoints you can use to manage steps programmatically.

The step model

The step model contains all the information about a single stage within a journey, including its type, ordering, and complexity metrics.

Properties

Name
id
Type
string
Description
Unique identifier for the step.
Name
journeyId
Type
string
Description
The journey this step belongs to.
Name
stepKey
Type
string
Description
Stable identifier used by the embed script (e.g., "eligibility", "upload-docs"). Must be unique within the journey.
Name
name
Type
string
Description
Human-readable name for the step.
Name
stepType
Type
string
Description
The type of step: eligibility, upload, review, submit, information, input, selection, payment, signature, or other.
Name
fieldType
Type
string
Description
Primary field type on this step (e.g., text_box, file_upload, drop_down).
Name
index
Type
integer
Description
Position in the journey sequence (0-based).
Name
readingLevel
Type
integer
Description
Optional grade level required to understand the content.
Name
fieldCount
Type
integer
Description
Optional number of input fields on this step.
Name
requiredArtifacts
Type
integer
Description
Optional number of documents or files required at this step.
Name
createdAt
Type
timestamp
Description
Timestamp of when the step was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the step was last updated.

POST/api/journeys/:journeySlug/steps

Create a step

This endpoint allows you to add a new step to an existing journey.

Path parameters

Name
journeySlug
Type
string
Description
The journey slug.

Required attributes

Name
stepKey
Type
string
Description
Stable identifier for the step (lowercase, alphanumeric, hyphens/underscores).
Name
index
Type
integer
Description
Position in the journey (0-based, must be unique).

Optional attributes

Name
name
Type
string
Description
Human-readable name for dashboards.
Name
stepType
Type
string
Description
Step type: eligibility, upload, review, submit, information, input, selection, payment, signature, or other (default).
Name
fieldType
Type
string
Description
Primary field type (e.g., text_box, file_upload).
Name
readingLevel
Type
integer
Description
Grade level required (positive integer).
Name
fieldCount
Type
integer
Description
Number of input fields (positive integer).
Name
requiredArtifacts
Type
integer
Description
Number of required documents (positive integer).

Request

POST

/api/journeys/small-business-grant/steps

curl -X POST https://odysseylabs.ai/api/journeys/small-business-grant/steps \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "stepKey": "financial-info",
    "name": "Financial Information",
    "stepType": "input",
    "index": 2,
    "fieldCount": 8,
    "readingLevel": 10
  }'

Response

{
  "id": "step_jkl012",
  "journeyId": "journey_abc123xyz",
  "stepKey": "financial-info",
  "name": "Financial Information",
  "stepType": "input",
  "index": 2,
  "fieldCount": 8,
  "readingLevel": 10,
  "fieldType": null,
  "requiredArtifacts": null,
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

PUT/api/journeys/:journeySlug/steps/:stepId

Update a step

This endpoint is planned but not yet implemented. Check back soon for updates.

This endpoint will allow you to update an existing step's properties.

Path parameters

Name
journeySlug
Type
string
Description
The journey slug.
Name
stepId
Type
string
Description
The step ID.

Optional attributes

All step properties except stepKey and index can be updated.

Request

PUT

/api/journeys/small-business-grant/steps/step_jkl012

curl -X PUT https://odysseylabs.ai/api/journeys/small-business-grant/steps/step_jkl012 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Financial Details",
    "fieldCount": 10
  }'

Response (planned)

{
  "id": "step_jkl012",
  "journeyId": "journey_abc123xyz",
  "stepKey": "financial-info",
  "name": "Financial Details",
  "stepType": "input",
  "index": 2,
  "fieldCount": 10,
  "readingLevel": 10,
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T14:30:00.000Z"
}

POST/api/journeys/:journeySlug/steps/reorder

Reorder steps

This endpoint is planned but not yet implemented. Check back soon for updates.

This endpoint will allow you to reorder steps within a journey by providing the desired index for each step.

Path parameters

Name
journeySlug
Type
string
Description
The journey slug.

Required attributes

Name
steps
Type
array
Description
Array of objects with stepId and index properties.

Request

POST

/api/journeys/small-business-grant/steps/reorder

curl -X POST https://odysseylabs.ai/api/journeys/small-business-grant/steps/reorder \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "stepId": "step_def456", "index": 0 },
      { "stepId": "step_jkl012", "index": 1 },
      { "stepId": "step_ghi789", "index": 2 }
    ]
  }'

Response (planned)

{
  "updated": 3,
  "steps": [
    {
      "id": "step_def456",
      "stepKey": "eligibility",
      "index": 0
    },
    {
      "id": "step_jkl012",
      "stepKey": "financial-info",
      "index": 1
    },
    {
      "id": "step_ghi789",
      "stepKey": "business-info",
      "index": 2
    }
  ]
}

Step types reference

When creating or updating steps, use these step types to categorize their purpose:

Name
eligibility
Description
Qualification or screening questions that determine if the user can proceed.
Name
upload
Description
Document or file upload pages where users provide supporting materials.
Name
review
Description
Summary or confirmation pages where users review their information before submitting.
Name
submit
Description
Final submission pages where users complete the workflow.
Name
information
Description
Informational or instructional pages that provide guidance.
Name
input
Description
Data entry forms where users provide information.
Name
selection
Description
Choice or option selection pages (radio buttons, dropdowns, checkboxes).
Name
payment
Description
Payment processing pages.
Name
signature
Description
Electronic signature capture pages.
Name
other
Description
Miscellaneous or uncategorized step types.

Field types reference

For steps with form inputs, you can optionally specify the primary field type:

text_box, text_area - Text input fields
radio_button, check_box, boolean_check_box - Selection fields
drop_down, multi_select - Dropdown menus
file_upload, multi_upload - File uploads
datepicker - Date selection
address - Address input
signature_field - Signature capture
payment_field - Payment information
table, spreadsheet - Structured data entry
static_html, static_text, heading - Display-only content
action_button, submit_button - Interactive buttons
And more...

Common errors

Step key already exists (409)

{
  "error": "Step with stepKey \"financial-info\" already exists"
}

Journey not found (404)

{
  "error": "Journey with slug \"nonexistent-journey\" not found"
}

Invalid step data (400)

{
  "error": "Invalid step data: index must be a non-negative integer"
}

Insufficient permissions (403)

{
  "error": "API key does not have required scope: journeys:write"
}