Journeys

Journeys are the core resource in Odyssey. They represent multi-step processes or workflows that you want to track and analyze. On this page, we'll dive into the different journey endpoints you can use to manage journeys programmatically.

The journey model

The journey model contains all the configuration and metadata for a tracked workflow, including its steps, analytics, and health metrics.

Properties

Name
id
Type
string
Description
Unique identifier for the journey.
Name
orgId
Type
string
Description
The organization this journey belongs to.
Name
slug
Type
string
Description
URL-safe identifier for the journey (unique within organization).
Name
displayName
Type
string
Description
Human-readable name for the journey.
Name
sourceSystem
Type
string
Description
Origin of the journey: simpliGov, custom, or unknown.
Name
environment
Type
string
Description
Deployment environment: production or staging.
Name
allowedOrigins
Type
array
Description
Array of allowed origin URLs for CORS. Empty array allows all origins.
Name
steps
Type
array
Description
Array of step objects belonging to this journey.
Name
healthMetrics
Type
object
Description
Journey health indicators including hasSteps, hasRecentEvents, sessionCount, and hasSnapshot.
Name
behaviorMetrics
Type
object
Description
User behavior metrics including completionRate, mobileRate, medianTimeToComplete, and topDropoffStep.
Name
eventCountsLast24h
Type
object
Description
Event counts by type for the last 24 hours.
Name
unmappedStepIds
Type
array
Description
Step IDs that haven't received events in the last 7 days.
Name
createdAt
Type
timestamp
Description
Timestamp of when the journey was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the journey was last updated.

POST/api/journeys/create

Create a journey

This endpoint allows you to create a new journey in your organization.

Required attributes

Name
slug
Type
string
Description
URL-safe identifier (lowercase letters, numbers, and hyphens only). Must be unique within your organization.
Name
displayName
Type
string
Description
Human-readable name for the journey (max 255 characters).

Optional attributes

Name
sourceSystem
Type
string
Description
Origin system: simpliGov, custom, or unknown. Defaults to unknown.
Name
allowedOrigins
Type
array
Description
Array of allowed origin URLs (e.g., ["https://app.example.com"]). Leave empty to allow all origins.
Name
steps
Type
array
Description
Array of step objects to create with the journey. Each step requires stepKey, index, and optionally name, stepType, readingLevel, fieldCount, and requiredArtifacts.

Request

POST

/api/journeys/create

curl -X POST https://odysseylabs.ai/api/journeys/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "small-business-grant",
    "displayName": "Small Business Grant Application",
    "sourceSystem": "custom",
    "allowedOrigins": ["https://grants.example.com"],
    "steps": [
      {
        "stepKey": "eligibility",
        "name": "Eligibility Check",
        "stepType": "eligibility",
        "index": 0,
        "fieldCount": 5
      },
      {
        "stepKey": "business-info",
        "name": "Business Information",
        "stepType": "input",
        "index": 1,
        "fieldCount": 12
      }
    ]
  }'

Response

{
  "id": "journey_abc123xyz",
  "orgId": "org_xyz789",
  "slug": "small-business-grant",
  "displayName": "Small Business Grant Application",
  "sourceSystem": "custom",
  "environment": "production",
  "allowedOrigins": ["https://grants.example.com"],
  "steps": [
    {
      "id": "step_def456",
      "journeyId": "journey_abc123xyz",
      "stepKey": "eligibility",
      "name": "Eligibility Check",
      "stepType": "eligibility",
      "index": 0,
      "fieldCount": 5,
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    },
    {
      "id": "step_ghi789",
      "journeyId": "journey_abc123xyz",
      "stepKey": "business-info",
      "name": "Business Information",
      "stepType": "input",
      "index": 1,
      "fieldCount": 12,
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

GET/api/journeys/:slug

Retrieve a journey

This endpoint allows you to retrieve a journey by providing its slug. The response includes the journey configuration, all steps, and analytics metrics.

Path parameters

Name
slug
Type
string
Description
The journey slug.

Request

GET

/api/journeys/small-business-grant

curl https://odysseylabs.ai/api/journeys/small-business-grant \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "journey_abc123xyz",
  "orgId": "org_xyz789",
  "slug": "small-business-grant",
  "displayName": "Small Business Grant Application",
  "sourceSystem": "custom",
  "environment": "production",
  "allowedOrigins": ["https://grants.example.com"],
  "steps": [
    {
      "id": "step_def456",
      "stepKey": "eligibility",
      "name": "Eligibility Check",
      "stepType": "eligibility",
      "index": 0,
      "fieldCount": 5
    }
  ],
  "healthMetrics": {
    "hasSteps": true,
    "hasRecentEvents": true,
    "sessionCount": 247,
    "hasSnapshot": false
  },
  "behaviorMetrics": {
    "completionRate": 0.68,
    "mobileRate": 0.42,
    "medianTimeToComplete": 1230,
    "topDropoffStep": {
      "stepId": "step_def456",
      "stepKey": "eligibility",
      "stepName": "Eligibility Check",
      "abandonmentRate": 0.28
    }
  },
  "eventCountsLast24h": {
    "session_start": 45,
    "step_view": 178,
    "field_focus": 523,
    "submit_attempt": 38,
    "submit_success": 32
  },
  "unmappedStepIds": [],
  "lastArtifactCreated": null,
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

PUT/api/journeys/:slug

Update a journey

This endpoint allows you to update a journey's configuration. You can change the display name, environment, source system, or allowed origins.

Path parameters

Name
slug
Type
string
Description
The journey slug.

Optional attributes

Name
displayName
Type
string
Description
Updated display name (max 255 characters).
Name
environment
Type
string
Description
Environment: production or staging.
Name
sourceSystem
Type
string
Description
Source system: simpliGov, custom, or unknown.
Name
allowedOrigins
Type
array
Description
Updated array of allowed origin URLs.

Request

PUT

/api/journeys/small-business-grant

curl -X PUT https://odysseylabs.ai/api/journeys/small-business-grant \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "SBA Small Business Grant",
    "allowedOrigins": [
      "https://grants.example.com",
      "https://apply.example.com"
    ]
  }'

Response

{
  "id": "journey_abc123xyz",
  "orgId": "org_xyz789",
  "slug": "small-business-grant",
  "displayName": "SBA Small Business Grant",
  "sourceSystem": "custom",
  "environment": "production",
  "allowedOrigins": [
    "https://grants.example.com",
    "https://apply.example.com"
  ],
  "steps": [
    {
      "id": "step_def456",
      "stepKey": "eligibility",
      "name": "Eligibility Check",
      "stepType": "eligibility",
      "index": 0
    }
  ],
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T14:30:00.000Z"
}

Common errors

Journey not found (404)

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

Slug already exists (409)

{
  "error": "Journey with slug \"small-business-grant\" already exists in this organization"
}

Invalid slug format (400)

{
  "error": "Invalid journey data: slug must contain only lowercase letters, numbers, and hyphens"
}

Insufficient permissions (403)

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