Purple Journeys API OpenAPI

GET /templates

List journey templates

Templates are reusable definitions of a lifecycle event (onboarding, offboarding, leave, transfer) as phases and steps. Start here to see what can be started. _filter "status eq 'published'" for the ones journeys can start from; _filter "journey_type eq 'onboarding'". Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "List journey templates",
  "description": "Templates are reusable definitions of a lifecycle event (onboarding, offboarding, leave, transfer) as phases and steps. Start here to see what can be started. _filter \"status eq 'published'\" for the ones journeys can start from; _filter \"journey_type eq 'onboarding'\". Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "default": 50
      },
      "description": "Legacy page size (default 50). Prefer $top. Ignored when $top/$skip are used."
    },
    {
      "in": "query",
      "name": "cursor",
      "schema": {
        "type": "string"
      },
      "description": "Legacy keyset cursor — pass the previous response's nextCursor. Prefer $skip/$top."
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/JourneyTemplate"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query (e.g. malformed $filter)"
    }
  }
}

POST /templates

Create a journey template from a whole spec

Takes the entire template in one call: name, journey_type, anchor, trigger, phases (each with an unlock rule) and steps (key, phase, title, kind, assignee_role, due offset, depends_on, required). The server normalizes it (derives keys from names, defaults due dates to the phase opening, orders steps by phase) and VALIDATES it, returning the stored template plus a warnings array rather than rejecting it: unknown roles or kinds, depends_on to a step that does not exist, cycles (the edge that points back to an earlier step is dropped), a phase gated on its own completion through after_phase (it opens at once instead), a step due before its phase opens, a step without a phase. Only a missing name, a step without a title or duplicate keys are errors (400). The template is a draft; preview-templates to check the timeline, add-steps to adjust, publish-templates to make it startable.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Create a journey template from a whole spec",
  "description": "Takes the entire template in one call: name, journey_type, anchor, trigger, phases (each with an unlock rule) and steps (key, phase, title, kind, assignee_role, due offset, depends_on, required). The server normalizes it (derives keys from names, defaults due dates to the phase opening, orders steps by phase) and VALIDATES it, returning the stored template plus a warnings array rather than rejecting it: unknown roles or kinds, depends_on to a step that does not exist, cycles (the edge that points back to an earlier step is dropped), a phase gated on its own completion through after_phase (it opens at once instead), a step due before its phase opens, a step without a phase. Only a missing name, a step without a title or duplicate keys are errors (400). The template is a draft; preview-templates to check the timeline, add-steps to adjust, publish-templates to make it startable.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TemplateSpec"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The normalized template, with warnings",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/JourneyTemplate"
          }
        }
      }
    },
    "400": {
      "description": "Missing name, a step without a title, duplicate phase or step keys, or a non-array phases/steps"
    }
  }
}

GET /templates/{id}

Get a journey template

The full template: phases (with unlock rules), steps (role, kind, due offset, dependencies), roles, counts, version, status and any validation warnings.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Get a journey template",
  "description": "The full template: phases (with unlock rules), steps (role, kind, due offset, dependencies), roles, counts, version, status and any validation warnings.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/JourneyTemplate"
          }
        }
      }
    },
    "404": {
      "description": "Not found"
    }
  }
}

PATCH /templates/{id}

Update a journey template

Change name, description, journey_type, anchor, trigger, or replace phases/steps wholesale (the result is normalized and validated the same way as create). To add or change a few steps use add-steps instead. status may be set to retired; publishing goes through publish-templates, and a published or retired template cannot go back to draft (clone it instead). A retired template cannot change at all (409); clone it and edit the copy. A published template that changes structurally is marked has_unpublished_changes until it is published again. Journeys already running keep the copy of the phases and steps they took when they started.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Update a journey template",
  "description": "Change name, description, journey_type, anchor, trigger, or replace phases/steps wholesale (the result is normalized and validated the same way as create). To add or change a few steps use add-steps instead. status may be set to retired; publishing goes through publish-templates, and a published or retired template cannot go back to draft (clone it instead). A retired template cannot change at all (409); clone it and edit the copy. A published template that changes structurally is marked has_unpublished_changes until it is published again. Journeys already running keep the copy of the phases and steps they took when they started.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "description": "Fields to update (partial)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/JourneyTemplate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/JourneyTemplate"
          }
        }
      }
    },
    "404": {
      "description": "Not found"
    }
  }
}

DELETE /templates/{id}

Delete a journey template

Removes the template. Journeys already started from it keep running on their own copy of the phases and steps (template_snapshot), so nothing about them changes; new journeys can no longer be started from it. To stop starts while keeping the template, set status to retired instead.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Delete a journey template",
  "description": "Removes the template. Journeys already started from it keep running on their own copy of the phases and steps (template_snapshot), so nothing about them changes; new journeys can no longer be started from it. To stop starts while keeping the template, set status to retired instead.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "Not found"
    }
  }
}

POST /templates/{id}/steps

Add or change steps on a template

Upserts steps by key: a step whose key exists is patched with the fields given (e.g. { key, due } to move a due date, { key, required: false } to make it optional); any other key is added (title required; it goes in the phase named, or the first phase). Phases can ride along in phases, matched by key the same way, and steps nested under a phase (phases[].steps) are added to that phase. The whole template is re-normalized and re-validated; the response is the template with warnings plus the keys created and updated. A depends_on in this request that would close a cycle is the edge dropped (with a warning); steps the request did not name are never rewritten. On a published template this marks has_unpublished_changes; publish-templates with apply_to_active to push new steps into running journeys.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__add_steps__templates",
  "summary": "Add or change steps on a template",
  "description": "Upserts steps by key: a step whose key exists is patched with the fields given (e.g. { key, due } to move a due date, { key, required: false } to make it optional); any other key is added (title required; it goes in the phase named, or the first phase). Phases can ride along in phases, matched by key the same way, and steps nested under a phase (phases[].steps) are added to that phase. The whole template is re-normalized and re-validated; the response is the template with warnings plus the keys created and updated. A depends_on in this request that would close a cycle is the edge dropped (with a warning); steps the request did not name are never rewritten. On a published template this marks has_unpublished_changes; publish-templates with apply_to_active to push new steps into running journeys.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JT-0001"
      },
      "description": "Template id"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StepsUpsertRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The template after the change",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StepsUpsertResult"
          }
        }
      }
    },
    "400": {
      "description": "steps missing or not an array, or a new step without a title"
    },
    "404": {
      "description": "Template not found"
    },
    "409": {
      "description": "The template is retired"
    }
  }
}

DELETE /templates/{id}/steps/{stepKey}

Remove a step from a template

Deletes one step by key. Other steps that depended on it lose that dependency (reported in warnings). Journeys already running keep their tasks.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__remove_step__templates",
  "summary": "Remove a step from a template",
  "description": "Deletes one step by key. Other steps that depended on it lose that dependency (reported in warnings). Journeys already running keep their tasks.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JT-0001"
      },
      "description": "Template id"
    },
    {
      "in": "path",
      "name": "stepKey",
      "required": true,
      "schema": {
        "type": "string",
        "example": "sign_paperwork"
      },
      "description": "The step's key within the template"
    }
  ],
  "responses": {
    "200": {
      "description": "The template after the change",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/JourneyTemplate"
          }
        }
      }
    },
    "404": {
      "description": "Template or step not found; the message lists the step keys that exist"
    },
    "409": {
      "description": "The template is retired"
    }
  }
}

POST /templates/{id}/preview

Preview a template as a per-role timeline

Returns one row per step, grouped by role (subject first, then manager, buddy, hr, it, facilities, payroll, security, system) and ordered by due offset: role, phase, title, kind, required, due label (start -7d) and, when anchor_date is given, the actual due_date and the day the phase opens. as_role narrows it to one role, which is how a manager or a new hire sees their own list. Use it before publishing and before starting a journey to confirm the dates read right. Also returns the template's warnings.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Preview a template as a per-role timeline",
  "description": "Returns one row per step, grouped by role (subject first, then manager, buddy, hr, it, facilities, payroll, security, system) and ordered by due offset: role, phase, title, kind, required, due label (start -7d) and, when anchor_date is given, the actual due_date and the day the phase opens. as_role narrows it to one role, which is how a manager or a new hire sees their own list. Use it before publishing and before starting a journey to confirm the dates read right. Also returns the template's warnings.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JT-0001"
      },
      "description": "Template id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PreviewRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The timeline",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TemplatePreview"
          }
        }
      }
    },
    "400": {
      "description": "Bad anchor_date or an as_role the template does not use"
    },
    "404": {
      "description": "Template not found"
    }
  }
}

POST /templates/{id}/publish

Publish a template (optionally applying it to active journeys)

Makes the template startable. The first publish keeps version 1; publishing a published template that changed bumps the version and clears has_unpublished_changes. Without apply_to_active, journeys already running are untouched: they keep the copy of the phases and steps they started with. With apply_to_active true, every active journey of this template takes the new phases and steps as its template_snapshot, gets a task for each step it does not have yet and did not exclude at start (ready if that phase is already open, otherwise locked), re-gates and re-dates its open, unstarted tasks from the new phases (a phase whose unlock rule changed, a due offset that moved; work in flight keeps its gate), assigns new role tasks to the people the journey started with, and moves to the new template_version; completed and cancelled journeys are left alone. A template with no steps cannot be published.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Publish a template (optionally applying it to active journeys)",
  "description": "Makes the template startable. The first publish keeps version 1; publishing a published template that changed bumps the version and clears has_unpublished_changes. Without apply_to_active, journeys already running are untouched: they keep the copy of the phases and steps they started with. With apply_to_active true, every active journey of this template takes the new phases and steps as its template_snapshot, gets a task for each step it does not have yet and did not exclude at start (ready if that phase is already open, otherwise locked), re-gates and re-dates its open, unstarted tasks from the new phases (a phase whose unlock rule changed, a due offset that moved; work in flight keeps its gate), assigns new role tasks to the people the journey started with, and moves to the new template_version; completed and cancelled journeys are left alone. A template with no steps cannot be published.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JT-0001"
      },
      "description": "Template id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PublishRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The published template, with how many journeys it was applied to",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublishResult"
          }
        }
      }
    },
    "404": {
      "description": "Template not found"
    },
    "409": {
      "description": "The template is retired or has no steps"
    }
  }
}

GET /steps

List the step library (what other journeys ask people to do)

Every step of every template in the instance as one read model, grouped by title: kind, assignee_role, system, due offset from the anchor, the phase it sits in, which templates use it (template_names, used_in_count) and whether it was promoted from an ad hoc task (origin). This answers "what do other journeys ask people to do": research it before designing a template, then reuse the rows as steps in create-templates or add-steps. system=itsm (or _filter "system eq 'itsm'") for what journeys ask the ITSM system to do; assignee_role=manager for what managers are asked; _search "laptop" across titles, descriptions and template names; _orderby "used_in_count desc" for the most common steps. Built from the templates on each call; nothing is stored. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "List the step library (what other journeys ask people to do)",
  "description": "Every step of every template in the instance as one read model, grouped by title: kind, assignee_role, system, due offset from the anchor, the phase it sits in, which templates use it (template_names, used_in_count) and whether it was promoted from an ad hoc task (origin). This answers \"what do other journeys ask people to do\": research it before designing a template, then reuse the rows as steps in create-templates or add-steps. system=itsm (or _filter \"system eq 'itsm'\") for what journeys ask the ITSM system to do; assignee_role=manager for what managers are asked; _search \"laptop\" across titles, descriptions and template names; _orderby \"used_in_count desc\" for the most common steps. Built from the templates on each call; nothing is stored. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "query",
      "name": "kind",
      "schema": {
        "type": "string",
        "enum": [
          "todo",
          "form",
          "esign",
          "document",
          "content",
          "learning",
          "survey",
          "approval",
          "automated",
          "status_check",
          "meeting",
          "link"
        ]
      },
      "description": "Only this kind of step: todo, form, esign, document, content, learning, survey, approval, automated, status_check, meeting, link"
    },
    {
      "in": "query",
      "name": "assignee_role",
      "schema": {
        "type": "string",
        "enum": [
          "subject",
          "manager",
          "buddy",
          "hr",
          "it",
          "facilities",
          "payroll",
          "security",
          "system"
        ]
      },
      "description": "Only steps for this role: subject, manager, buddy, hr, it, facilities, payroll, security, system"
    },
    {
      "in": "query",
      "name": "system",
      "schema": {
        "type": "string",
        "enum": [
          "identity",
          "access",
          "itsm",
          "hris",
          "lms",
          "chat",
          "calendar",
          "pages",
          "mail",
          "expense",
          "people"
        ]
      },
      "description": "Only steps processed in this system: identity, access, itsm, hris, lms, chat, calendar, pages, mail, expense, people"
    },
    {
      "in": "query",
      "name": "origin",
      "schema": {
        "type": "string",
        "enum": [
          "template",
          "promoted"
        ]
      },
      "description": "template or promoted (the step came from an ad hoc group)"
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/StepLibraryRow"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query, or no current user for a /me route"
    }
  }
}

GET /templates/{id}/insights

Suggested changes for a template: what its journeys have been teaching

Reads across every journey of the template (any version): ad hoc tasks grouped by normalized title (count, which journeys, who added them and why, the suggested phase, role and due offset, and promote: the add-steps body that would add the group to the template; promoted_step_key when a step already covers it), the steps people skipped (with notes), the steps that ran late (count, median and worst days late, by role), the steps that were reassigned, and every flag with its note and who raised it. This is what goes wrong in this journey and what to add. To promote a group call add-steps-templates with the group's promote body (the new step records promoted_from), then publish-templates with apply_to_active to reach the journeys under way. Computed on every call; nothing is stored. Skips and lateness leave cancelled journeys out.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Suggested changes for a template: what its journeys have been teaching",
  "description": "Reads across every journey of the template (any version): ad hoc tasks grouped by normalized title (count, which journeys, who added them and why, the suggested phase, role and due offset, and promote: the add-steps body that would add the group to the template; promoted_step_key when a step already covers it), the steps people skipped (with notes), the steps that ran late (count, median and worst days late, by role), the steps that were reassigned, and every flag with its note and who raised it. This is what goes wrong in this journey and what to add. To promote a group call add-steps-templates with the group's promote body (the new step records promoted_from), then publish-templates with apply_to_active to reach the journeys under way. Computed on every call; nothing is stored. Skips and lateness leave cancelled journeys out.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JT-0001"
      },
      "description": "Template id"
    }
  ],
  "responses": {
    "200": {
      "description": "The insights",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TemplateInsights"
          }
        }
      }
    },
    "404": {
      "description": "Template not found"
    }
  }
}

POST /templates/{id}/clone

Clone a template into a new draft

Copies phases and steps into a new draft template (version 1) with the given name or Copy of the original. Use it to make a variant (contractor onboarding from employee onboarding) or to revise a retired template.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Clone a template into a new draft",
  "description": "Copies phases and steps into a new draft template (version 1) with the given name or Copy of the original. Use it to make a variant (contractor onboarding from employee onboarding) or to revise a retired template.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JT-0001"
      },
      "description": "Template id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CloneRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The new draft",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/JourneyTemplate"
          }
        }
      }
    },
    "404": {
      "description": "Template not found"
    }
  }
}

GET /journeys

List journeys

Every journey in the instance (one per person per lifecycle event) with status, health, progress_percent, counts and up_next. _filter "status eq 'active' and health eq 'warning'" for the ones that need attention; _filter "anchor_date ge 2026-11-01" for upcoming start dates; _orderby "anchor_date asc". For the current user's own journeys use list-my-journeys; for their reports' journeys list-team-journeys. Not to be confused with manager-experience's journeys, which only paint a vendor API. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "List journeys",
  "description": "Every journey in the instance (one per person per lifecycle event) with status, health, progress_percent, counts and up_next. _filter \"status eq 'active' and health eq 'warning'\" for the ones that need attention; _filter \"anchor_date ge 2026-11-01\" for upcoming start dates; _orderby \"anchor_date asc\". For the current user's own journeys use list-my-journeys; for their reports' journeys list-team-journeys. Not to be confused with manager-experience's journeys, which only paint a vendor API. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "default": 50
      },
      "description": "Legacy page size (default 50). Prefer $top. Ignored when $top/$skip are used."
    },
    {
      "in": "query",
      "name": "cursor",
      "schema": {
        "type": "string"
      },
      "description": "Legacy keyset cursor — pass the previous response's nextCursor. Prefer $skip/$top."
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    },
    {
      "in": "query",
      "name": "status",
      "schema": {
        "type": "string",
        "enum": [
          "draft",
          "active",
          "completed",
          "cancelled"
        ]
      },
      "description": "Only this status: draft, active, completed, cancelled"
    },
    {
      "in": "query",
      "name": "health",
      "schema": {
        "type": "string",
        "enum": [
          "passing",
          "warning",
          "failing"
        ]
      },
      "description": "Only this health: passing, warning, failing"
    },
    {
      "in": "query",
      "name": "subject_email",
      "schema": {
        "type": "string",
        "format": "email"
      },
      "description": "Journeys for this person"
    },
    {
      "in": "query",
      "name": "manager_email",
      "schema": {
        "type": "string",
        "format": "email"
      },
      "description": "Journeys where this person is the manager"
    },
    {
      "in": "query",
      "name": "template_id",
      "schema": {
        "type": "string"
      },
      "description": "Journeys started from this template"
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Journey"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query (e.g. malformed $filter)"
    }
  }
}

POST /journeys

Start a journey for a person from a published template

Creates the journey and one task per step, dated from anchor_date (each step's due offset) and locked until its phase opens and its prerequisites are done; automated steps whose phase is already open run at once. Roles resolve to people: subject_email is given; manager_email defaults to the subject's manager on the identity roster; buddy_email must be given when the template has buddy steps; hr, it, facilities, payroll and security resolve from the roster by department unless role_assignments overrides them, and the result is recorded on the journey (role_assignments) so later tasks for those roles go to the same people. Fails with 409 if the template is a draft (publish it first) or the person already has an active journey of this template. Returns the journey with its tasks.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Start a journey for a person from a published template",
  "description": "Creates the journey and one task per step, dated from anchor_date (each step's due offset) and locked until its phase opens and its prerequisites are done; automated steps whose phase is already open run at once. Roles resolve to people: subject_email is given; manager_email defaults to the subject's manager on the identity roster; buddy_email must be given when the template has buddy steps; hr, it, facilities, payroll and security resolve from the roster by department unless role_assignments overrides them, and the result is recorded on the journey (role_assignments) so later tasks for those roles go to the same people. Fails with 409 if the template is a draft (publish it first) or the person already has an active journey of this template. Returns the journey with its tasks.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StartJourneyRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The journey and its tasks",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StartJourneyResult"
          }
        }
      }
    },
    "400": {
      "description": "Missing template_id, subject_email or anchor_date; a manager or buddy the template needs that could not be resolved; a bad email"
    },
    "404": {
      "description": "Template not found"
    },
    "409": {
      "description": "The template is not published, or the person already has an active journey of it"
    }
  }
}

GET /journeys/{id}

Get a journey

One journey with its rollup (progress, counts, health, up_next, all as of today) and the template_snapshot it runs on (phases and steps as they were when it started or was last applied). Reading it opens any task whose phase has opened on the calendar since the journey was last written (automations run, the feed records them). Tasks are listed separately with list-journey-tasks.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Get a journey",
  "description": "One journey with its rollup (progress, counts, health, up_next, all as of today) and the template_snapshot it runs on (phases and steps as they were when it started or was last applied). Reading it opens any task whose phase has opened on the calendar since the journey was last written (automations run, the feed records them). Tasks are listed separately with list-journey-tasks.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Journey"
          }
        }
      }
    },
    "404": {
      "description": "Not found"
    }
  }
}

PATCH /journeys/{id}

Update a journey

Change manager_email, buddy_email, anchor_date or subject_name. A new manager or buddy takes over that role's open tasks. A moved anchor date re-dates the open template tasks from the journey's own rules: phases and dues that hang off the anchor move with it, while an immediate phase (opened on the start day), an ad hoc task (dated on its own) and a due fixed when a task unlocked keep their dates; ready tasks nobody has started whose phase now opens in the future are re-locked. Status changes go through cancel-journeys; progress moves through the task actions.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Update a journey",
  "description": "Change manager_email, buddy_email, anchor_date or subject_name. A new manager or buddy takes over that role's open tasks. A moved anchor date re-dates the open template tasks from the journey's own rules: phases and dues that hang off the anchor move with it, while an immediate phase (opened on the start day), an ad hoc task (dated on its own) and a due fixed when a task unlocked keep their dates; ready tasks nobody has started whose phase now opens in the future are re-locked. Status changes go through cancel-journeys; progress moves through the task actions.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "description": "Fields to update (partial)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Journey"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Journey"
          }
        }
      }
    },
    "404": {
      "description": "Not found"
    }
  }
}

DELETE /journeys/{id}

Delete a journey

Removes the journey with its tasks and activity. To end a journey while keeping its history, use cancel-journeys instead.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Delete a journey",
  "description": "Removes the journey with its tasks and activity. To end a journey while keeping its history, use cancel-journeys instead.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JNY-0001"
      },
      "description": "Journey id"
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "deleted_tasks": {
                "type": "integer"
              },
              "deleted_activity": {
                "type": "integer"
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "Journey not found"
    }
  }
}

POST /journeys/{id}/cancel

Cancel a journey

Ends an active journey: every open task is skipped with the reason as its note, status becomes cancelled, and the activity feed records it. Done tasks keep their history. Use it when a start date falls through or a leave is withdrawn.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Cancel a journey",
  "description": "Ends an active journey: every open task is skipped with the reason as its note, status becomes cancelled, and the activity feed records it. Done tasks keep their history. Use it when a start date falls through or a leave is withdrawn.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JNY-0001"
      },
      "description": "Journey id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CancelJourneyRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The cancelled journey",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Journey"
          }
        }
      }
    },
    "404": {
      "description": "Journey not found"
    },
    "409": {
      "description": "The journey is already completed or cancelled"
    }
  }
}

GET /journeys/{id}/tasks

List the tasks of one journey

Every task of the journey with status, assignee, due date, lock reason and dependencies: the detail view, as of today (a phase that opened on the calendar since the last write is opened first, and its automations run). _filter "assignee_role eq 'manager'" for one column; _filter "status in ('ready','in_progress')" for what can be worked now; origin=ad_hoc for the tasks added by hand; _orderby "due_date asc". Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__list__journey_tasks",
  "summary": "List the tasks of one journey",
  "description": "Every task of the journey with status, assignee, due date, lock reason and dependencies: the detail view, as of today (a phase that opened on the calendar since the last write is opened first, and its automations run). _filter \"assignee_role eq 'manager'\" for one column; _filter \"status in ('ready','in_progress')\" for what can be worked now; origin=ad_hoc for the tasks added by hand; _orderby \"due_date asc\". Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JNY-0001"
      },
      "description": "Journey id"
    },
    {
      "in": "query",
      "name": "status",
      "schema": {
        "type": "string",
        "enum": [
          "locked",
          "ready",
          "in_progress",
          "processing",
          "done",
          "skipped",
          "error"
        ]
      },
      "description": "Only this status: locked, ready, in_progress, processing, done, skipped, error"
    },
    {
      "in": "query",
      "name": "assignee_role",
      "schema": {
        "type": "string",
        "enum": [
          "subject",
          "manager",
          "buddy",
          "hr",
          "it",
          "facilities",
          "payroll",
          "security",
          "system"
        ]
      },
      "description": "Only this role: subject, manager, buddy, hr, it, facilities, payroll, security, system"
    },
    {
      "in": "query",
      "name": "assignee_email",
      "schema": {
        "type": "string",
        "format": "email"
      },
      "description": "Only this person's tasks"
    },
    {
      "in": "query",
      "name": "origin",
      "schema": {
        "type": "string",
        "enum": [
          "template",
          "ad_hoc"
        ]
      },
      "description": "template steps or ad hoc tasks: template or ad_hoc"
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/JourneyTask"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query, or no current user for a /me route"
    },
    "404": {
      "description": "Journey not found"
    }
  }
}

POST /journeys/{id}/tasks

Add an ad hoc task to a running journey

Adds a task the template did not foresee to this one journey: title, who does it (assignee_email, or assignee_role to use whoever holds that role on the journey), due_date, and reason (why it was needed). The task joins the phase that is open now, is ready at once, and records origin ad_hoc, added_by (the current user) and the reason; the journey's ad_hoc_count goes up. kind defaults to todo (form and link tasks are accepted with form or link); system defaults from the kind and title. Ad hoc tasks are what get-insights-templates groups by title so the owner can promote the recurring ones into the template with add-steps-templates. Not for the template itself: use add-steps-templates for that.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__add_task__journeys",
  "summary": "Add an ad hoc task to a running journey",
  "description": "Adds a task the template did not foresee to this one journey: title, who does it (assignee_email, or assignee_role to use whoever holds that role on the journey), due_date, and reason (why it was needed). The task joins the phase that is open now, is ready at once, and records origin ad_hoc, added_by (the current user) and the reason; the journey's ad_hoc_count goes up. kind defaults to todo (form and link tasks are accepted with form or link); system defaults from the kind and title. Ad hoc tasks are what get-insights-templates groups by title so the owner can promote the recurring ones into the template with add-steps-templates. Not for the template itself: use add-steps-templates for that.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JNY-0001"
      },
      "description": "Journey id"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AdHocTaskRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The new task (ready) and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Missing title, due_date or assignee; a role nobody holds on this journey; a bad kind or system"
    },
    "404": {
      "description": "Journey not found"
    },
    "409": {
      "description": "The journey is completed or cancelled"
    }
  }
}

GET /journeys/{id}/activity

List the activity feed of one journey

Who did what and when on this journey, oldest first by default: started, tasks completed or skipped, automations that ran, a template version applied, cancellation. _orderby "at desc" for newest first. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__list__journey_activity",
  "summary": "List the activity feed of one journey",
  "description": "Who did what and when on this journey, oldest first by default: started, tasks completed or skipped, automations that ran, a template version applied, cancellation. _orderby \"at desc\" for newest first. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JNY-0001"
      },
      "description": "Journey id"
    },
    {
      "in": "query",
      "name": "kind",
      "schema": {
        "type": "string",
        "enum": [
          "journey_started",
          "journey_updated",
          "journey_completed",
          "journey_cancelled",
          "task_unlocked",
          "task_started",
          "task_completed",
          "task_submitted",
          "task_skipped",
          "task_reopened",
          "task_reassigned",
          "task_added",
          "task_flagged",
          "task_unflagged",
          "automation_completed",
          "status_check_started",
          "template_applied"
        ]
      },
      "description": "Only this kind of entry: journey_started, journey_updated, journey_completed, journey_cancelled, task_unlocked, task_started, task_completed, task_submitted, task_skipped, task_reopened, task_reassigned, task_added, task_flagged, task_unflagged, automation_completed, status_check_started, template_applied"
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/JourneyActivity"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query, or no current user for a /me route"
    },
    "404": {
      "description": "Journey not found"
    }
  }
}

GET /tasks

List journey tasks across journeys

Every task in every journey. Useful for a queue view (assignee_email=... or _filter "assignee_role eq 'it' and status eq 'ready'"), for finding what is late (_filter "is_overdue eq true"), what was flagged (_filter "flagged eq true"), what was added by hand (origin=ad_hoc) and what was submitted (_filter "submission ne null"). Rows are projected to today: a task locked only on a date whose day has come reads ready. For the current user's own tasks use list-my-tasks; for one journey list-journey-tasks. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "List journey tasks across journeys",
  "description": "Every task in every journey. Useful for a queue view (assignee_email=... or _filter \"assignee_role eq 'it' and status eq 'ready'\"), for finding what is late (_filter \"is_overdue eq true\"), what was flagged (_filter \"flagged eq true\"), what was added by hand (origin=ad_hoc) and what was submitted (_filter \"submission ne null\"). Rows are projected to today: a task locked only on a date whose day has come reads ready. For the current user's own tasks use list-my-tasks; for one journey list-journey-tasks. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "default": 50
      },
      "description": "Legacy page size (default 50). Prefer $top. Ignored when $top/$skip are used."
    },
    {
      "in": "query",
      "name": "cursor",
      "schema": {
        "type": "string"
      },
      "description": "Legacy keyset cursor — pass the previous response's nextCursor. Prefer $skip/$top."
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    },
    {
      "in": "query",
      "name": "status",
      "schema": {
        "type": "string",
        "enum": [
          "locked",
          "ready",
          "in_progress",
          "processing",
          "done",
          "skipped",
          "error"
        ]
      },
      "description": "Only this status: locked, ready, in_progress, processing, done, skipped, error"
    },
    {
      "in": "query",
      "name": "journey_id",
      "schema": {
        "type": "string"
      },
      "description": "Only tasks of this journey"
    },
    {
      "in": "query",
      "name": "assignee_email",
      "schema": {
        "type": "string",
        "format": "email"
      },
      "description": "Only tasks assigned to this person"
    },
    {
      "in": "query",
      "name": "assignee_role",
      "schema": {
        "type": "string",
        "enum": [
          "subject",
          "manager",
          "buddy",
          "hr",
          "it",
          "facilities",
          "payroll",
          "security",
          "system"
        ]
      },
      "description": "Only tasks for this role: subject, manager, buddy, hr, it, facilities, payroll, security, system"
    },
    {
      "in": "query",
      "name": "kind",
      "schema": {
        "type": "string",
        "enum": [
          "todo",
          "form",
          "esign",
          "document",
          "content",
          "learning",
          "survey",
          "approval",
          "automated",
          "status_check",
          "meeting",
          "link"
        ]
      },
      "description": "Only this kind of step: todo, form, esign, document, content, learning, survey, approval, automated, status_check, meeting, link"
    },
    {
      "in": "query",
      "name": "system",
      "schema": {
        "type": "string",
        "enum": [
          "identity",
          "access",
          "itsm",
          "hris",
          "lms",
          "chat",
          "calendar",
          "pages",
          "mail",
          "expense",
          "people"
        ]
      },
      "description": "Only tasks processed in this system: identity, access, itsm, hris, lms, chat, calendar, pages, mail, expense, people"
    },
    {
      "in": "query",
      "name": "origin",
      "schema": {
        "type": "string",
        "enum": [
          "template",
          "ad_hoc"
        ]
      },
      "description": "template steps or ad hoc tasks: template or ad_hoc"
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/JourneyTask"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query (e.g. malformed $filter)"
    }
  }
}

GET /tasks/{id}

Get a journey task

One task with its status, due date, dependencies, lock reason and completion details.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Get a journey task",
  "description": "One task with its status, due date, dependencies, lock reason and completion details.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/JourneyTask"
          }
        }
      }
    },
    "404": {
      "description": "Not found"
    }
  }
}

PATCH /tasks/{id}

Update a journey task

Change title, description, due_date, note, required, payload, system or reason. Status moves with complete-tasks, start-tasks, skip-tasks and reopen-tasks; the person moves with reassign-tasks (which records reassigned_from and logs the change, so insights see it); the journey's counts and health are recomputed when a due date moves.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Update a journey task",
  "description": "Change title, description, due_date, note, required, payload, system or reason. Status moves with complete-tasks, start-tasks, skip-tasks and reopen-tasks; the person moves with reassign-tasks (which records reassigned_from and logs the change, so insights see it); the journey's counts and health are recomputed when a due date moves.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "description": "Fields to update (partial)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/JourneyTask"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/JourneyTask"
          }
        }
      }
    },
    "404": {
      "description": "Not found"
    }
  }
}

POST /tasks/{id}/complete

Complete a task

Marks a ready, in-progress or processing task done (completed_by is the current user) and unlocks what depended on it: dependents whose prerequisites are now all done and whose phase is open become ready, automated steps among them run to done, status checks move to processing. Returns the task, the tasks it unlocked and the journey's new progress. A locked task cannot be completed; the 409 says what it is waiting for. Use skip-tasks for a step that should not happen.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__complete__tasks",
  "summary": "Complete a task",
  "description": "Marks a ready, in-progress or processing task done (completed_by is the current user) and unlocks what depended on it: dependents whose prerequisites are now all done and whose phase is open become ready, automated steps among them run to done, status checks move to processing. Returns the task, the tasks it unlocked and the journey's new progress. A locked task cannot be completed; the 409 says what it is waiting for. Use skip-tasks for a step that should not happen.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JTK-0001-03"
      },
      "description": "Task id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TaskNoteRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The task after the action, the tasks it unlocked, and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "404": {
      "description": "Task not found"
    },
    "409": {
      "description": "The task is not in a state that allows this action; the message says what it is waiting for or what to call instead"
    }
  }
}

POST /tasks/{id}/start

Start a task (mark it in progress)

Moves a ready task to in_progress so others can see it is being worked. Locked and finished tasks cannot be started.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__start__tasks",
  "summary": "Start a task (mark it in progress)",
  "description": "Moves a ready task to in_progress so others can see it is being worked. Locked and finished tasks cannot be started.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JTK-0001-03"
      },
      "description": "Task id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TaskNoteRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The task after the action, the tasks it unlocked, and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "404": {
      "description": "Task not found"
    },
    "409": {
      "description": "The task is not in a state that allows this action; the message says what it is waiting for or what to call instead"
    }
  }
}

POST /tasks/{id}/skip

Skip a task

Marks a task skipped: it counts toward progress and satisfies anything that depended on it, so dependents unlock as if it were done. Skipping a required step returns a warning. Works on locked tasks too.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__skip__tasks",
  "summary": "Skip a task",
  "description": "Marks a task skipped: it counts toward progress and satisfies anything that depended on it, so dependents unlock as if it were done. Skipping a required step returns a warning. Works on locked tasks too.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JTK-0001-03"
      },
      "description": "Task id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TaskNoteRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The task after the action, the tasks it unlocked, and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "404": {
      "description": "Task not found"
    },
    "409": {
      "description": "The task is not in a state that allows this action; the message says what it is waiting for or what to call instead"
    }
  }
}

POST /tasks/{id}/reopen

Reopen a done or skipped task

Puts a finished task back to ready (or locked, if its phase or prerequisites say so), clears its completion, and re-locks any task that was waiting on it and has not been started: tasks that depend on it, and tasks in a phase that opens only when this task's phase is complete. A completed journey goes back to active.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__reopen__tasks",
  "summary": "Reopen a done or skipped task",
  "description": "Puts a finished task back to ready (or locked, if its phase or prerequisites say so), clears its completion, and re-locks any task that was waiting on it and has not been started: tasks that depend on it, and tasks in a phase that opens only when this task's phase is complete. A completed journey goes back to active.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JTK-0001-03"
      },
      "description": "Task id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TaskNoteRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The task after the action, the tasks it unlocked, and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "404": {
      "description": "Task not found"
    },
    "409": {
      "description": "The task is not in a state that allows this action; the message says what it is waiting for or what to call instead"
    }
  }
}

POST /tasks/{id}/reassign

Reassign a task to another person

Changes assignee_email on an open task, records the previous person as reassigned_from and logs it on the activity feed. To change who holds a whole role on the journey (a new manager), update the journey's manager_email instead.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__reassign__tasks",
  "summary": "Reassign a task to another person",
  "description": "Changes assignee_email on an open task, records the previous person as reassigned_from and logs it on the activity feed. To change who holds a whole role on the journey (a new manager), update the journey's manager_email instead.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JTK-0001-03"
      },
      "description": "Task id"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ReassignTaskRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The task after the action, the tasks it unlocked, and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "404": {
      "description": "Task not found"
    },
    "409": {
      "description": "The task is not in a state that allows this action; the message says what it is waiting for or what to call instead"
    }
  }
}

POST /tasks/{id}/flag

Flag a task as bumpy

Marks a task (in any state, done included) as something that did not go smoothly, with a note saying what: flagged, flag_note, flagged_by and flagged_at are set, the journey's flag_count goes up, and the flag shows in get-insights-templates for the template's owner. Any participant can flag; flagging again replaces the note. unflag-tasks clears it.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Flag a task as bumpy",
  "description": "Marks a task (in any state, done included) as something that did not go smoothly, with a note saying what: flagged, flag_note, flagged_by and flagged_at are set, the journey's flag_count goes up, and the flag shows in get-insights-templates for the template's owner. Any participant can flag; flagging again replaces the note. unflag-tasks clears it.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JTK-0001-03"
      },
      "description": "Task id"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FlagTaskRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The task after the action, the tasks it unlocked, and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "404": {
      "description": "Task not found"
    },
    "409": {
      "description": "The task is not in a state that allows this action; the message says what it is waiting for or what to call instead"
    }
  }
}

POST /tasks/{id}/unflag

Clear a task's flag

Clears flagged, flag_note, flagged_by and flagged_at on a flagged task. 409 when the task is not flagged.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Clear a task's flag",
  "description": "Clears flagged, flag_note, flagged_by and flagged_at on a flagged task. 409 when the task is not flagged.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JTK-0001-03"
      },
      "description": "Task id"
    }
  ],
  "responses": {
    "200": {
      "description": "The task after the action, the tasks it unlocked, and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "404": {
      "description": "Task not found"
    },
    "409": {
      "description": "The task is not in a state that allows this action; the message says what it is waiting for or what to call instead"
    }
  }
}

POST /tasks/{id}/submit

Submit a form task's values (completes it)

For a task that carries a form (get-tasks shows form.fields): validates values against the fields (required present, select among options, dates YYYY-MM-DD, numbers, emails, checkboxes; values for unknown fields are dropped with a warning), stores submission { values, submitted_at, submitted_by } on the task, marks it done and unlocks its dependents exactly like complete-tasks. Emits journeys.task.form_submitted (task, journey, step_key, values) as well as journeys.task.completed. 400 lists what is missing or wrong, with the form's fields; 409 when the task has no form (use complete-tasks), is locked, or is already done.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Submit a form task's values (completes it)",
  "description": "For a task that carries a form (get-tasks shows form.fields): validates values against the fields (required present, select among options, dates YYYY-MM-DD, numbers, emails, checkboxes; values for unknown fields are dropped with a warning), stores submission { values, submitted_at, submitted_by } on the task, marks it done and unlocks its dependents exactly like complete-tasks. Emits journeys.task.form_submitted (task, journey, step_key, values) as well as journeys.task.completed. 400 lists what is missing or wrong, with the form's fields; 409 when the task has no form (use complete-tasks), is locked, or is already done.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JTK-0001-03"
      },
      "description": "Task id"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SubmitTaskRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The task after the action, the tasks it unlocked, and the journey's new rollup",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TaskActionResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input"
    },
    "404": {
      "description": "Task not found"
    },
    "409": {
      "description": "The task is not in a state that allows this action; the message says what it is waiting for or what to call instead"
    }
  }
}

GET /activity

List journey activity across journeys

The audit trail: who did what, when, on which journey and task. journey_id=JNY-0001 for one journey (or list-journey-activity); kind=task_completed for one kind; _filter "kind eq 'task_completed' and at ge 2026-11-01T00:00:00Z"; _orderby "at desc". Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "List journey activity across journeys",
  "description": "The audit trail: who did what, when, on which journey and task. journey_id=JNY-0001 for one journey (or list-journey-activity); kind=task_completed for one kind; _filter \"kind eq 'task_completed' and at ge 2026-11-01T00:00:00Z\"; _orderby \"at desc\". Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "default": 50
      },
      "description": "Legacy page size (default 50). Prefer $top. Ignored when $top/$skip are used."
    },
    {
      "in": "query",
      "name": "cursor",
      "schema": {
        "type": "string"
      },
      "description": "Legacy keyset cursor — pass the previous response's nextCursor. Prefer $skip/$top."
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    },
    {
      "in": "query",
      "name": "journey_id",
      "schema": {
        "type": "string"
      },
      "description": "Only entries of this journey"
    },
    {
      "in": "query",
      "name": "kind",
      "schema": {
        "type": "string",
        "enum": [
          "journey_started",
          "journey_updated",
          "journey_completed",
          "journey_cancelled",
          "task_unlocked",
          "task_started",
          "task_completed",
          "task_submitted",
          "task_skipped",
          "task_reopened",
          "task_reassigned",
          "task_added",
          "task_flagged",
          "task_unflagged",
          "automation_completed",
          "status_check_started",
          "template_applied"
        ]
      },
      "description": "Only this kind of entry: journey_started, journey_updated, journey_completed, journey_cancelled, task_unlocked, task_started, task_completed, task_submitted, task_skipped, task_reopened, task_reassigned, task_added, task_flagged, task_unflagged, automation_completed, status_check_started, template_applied"
    },
    {
      "in": "query",
      "name": "actor",
      "schema": {
        "type": "string"
      },
      "description": "Only entries by this person (email) or system"
    },
    {
      "in": "query",
      "name": "task_id",
      "schema": {
        "type": "string"
      },
      "description": "Only entries about this task"
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/JourneyActivity"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query (e.g. malformed $filter)"
    }
  }
}

GET /activity/{id}

Get an activity entry

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "summary": "Get an activity entry",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/JourneyActivity"
          }
        }
      }
    },
    "404": {
      "description": "Not found"
    }
  }
}

GET /me/tasks

List my tasks

Tasks assigned to the current user (the X-PS-Impersonate-User header, or the instance's default MCP user) across every journey: what they owe. Common calls: _filter "status in ('ready','in_progress')" for what can be done now; _filter "is_overdue eq true" for what is late; _filter "due_date le 2026-11-17" for everything due by a date; _orderby "due_date asc". Locked tasks show locked_reason and depends_on. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__list__my_tasks",
  "summary": "List my tasks",
  "description": "Tasks assigned to the current user (the X-PS-Impersonate-User header, or the instance's default MCP user) across every journey: what they owe. Common calls: _filter \"status in ('ready','in_progress')\" for what can be done now; _filter \"is_overdue eq true\" for what is late; _filter \"due_date le 2026-11-17\" for everything due by a date; _orderby \"due_date asc\". Locked tasks show locked_reason and depends_on. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "query",
      "name": "status",
      "schema": {
        "type": "string",
        "enum": [
          "locked",
          "ready",
          "in_progress",
          "processing",
          "done",
          "skipped",
          "error"
        ]
      },
      "description": "Only this status: locked, ready, in_progress, processing, done, skipped, error"
    },
    {
      "in": "query",
      "name": "journey_id",
      "schema": {
        "type": "string"
      },
      "description": "Only tasks of this journey"
    },
    {
      "in": "query",
      "name": "kind",
      "schema": {
        "type": "string",
        "enum": [
          "todo",
          "form",
          "esign",
          "document",
          "content",
          "learning",
          "survey",
          "approval",
          "automated",
          "status_check",
          "meeting",
          "link"
        ]
      },
      "description": "Only this kind of step: todo, form, esign, document, content, learning, survey, approval, automated, status_check, meeting, link"
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/JourneyTask"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query, or no current user for a /me route"
    }
  }
}

GET /me/journeys

List my journeys

Journeys where the current user is the subject (their own onboarding, leave, transfer), with progress, health and up_next. get-my-journey shows one of them as a checklist. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__list__my_journeys",
  "summary": "List my journeys",
  "description": "Journeys where the current user is the subject (their own onboarding, leave, transfer), with progress, health and up_next. get-my-journey shows one of them as a checklist. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "query",
      "name": "status",
      "schema": {
        "type": "string",
        "enum": [
          "draft",
          "active",
          "completed",
          "cancelled"
        ]
      },
      "description": "Only this status: draft, active, completed, cancelled"
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Journey"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query, or no current user for a /me route"
    }
  }
}

GET /me/journeys/{id}

Get one journey as the current user sees it

The current user's view of a journey (the X-PS-Impersonate-User header, or the instance's default MCP user): next_up (the soonest task they can act on), their tasks soonest due first, each with its status, due date, waiting_for (the unmet prerequisites: titles and who holds them) and unlocks_on for date-locked tasks, plus people (subject, manager, buddy with names) and counts. As of today: a phase that opened on the calendar since the journey was last written is opened first (its automations run). Works for whoever takes part: the subject sees their own checklist, the manager, buddy, HR or IT see what they owe on this person's journey. 404 when the current user has no part in it.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__get__my_journey",
  "summary": "Get one journey as the current user sees it",
  "description": "The current user's view of a journey (the X-PS-Impersonate-User header, or the instance's default MCP user): next_up (the soonest task they can act on), their tasks soonest due first, each with its status, due date, waiting_for (the unmet prerequisites: titles and who holds them) and unlocks_on for date-locked tasks, plus people (subject, manager, buddy with names) and counts. As of today: a phase that opened on the calendar since the journey was last written is opened first (its automations run). Works for whoever takes part: the subject sees their own checklist, the manager, buddy, HR or IT see what they owe on this person's journey. 404 when the current user has no part in it.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "path",
      "name": "id",
      "required": true,
      "schema": {
        "type": "string",
        "example": "JNY-0001"
      },
      "description": "Journey id"
    }
  ],
  "responses": {
    "200": {
      "description": "The journey as a checklist",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MyJourney"
          }
        }
      }
    },
    "400": {
      "description": "No current user"
    },
    "404": {
      "description": "Journey not found, or the current user has no part in it"
    }
  }
}

GET /me/team/journeys

List my team's journeys

Journeys where the current user is the manager: their reports' onboarding, leaves and transfers, with health and what is up next, so a manager can see who is late. _filter "health eq 'warning'" for the ones with overdue tasks. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__list__team_journeys",
  "summary": "List my team's journeys",
  "description": "Journeys where the current user is the manager: their reports' onboarding, leaves and transfers, with health and what is up next, so a manager can see who is late. _filter \"health eq 'warning'\" for the ones with overdue tasks. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    },
    {
      "in": "query",
      "name": "status",
      "schema": {
        "type": "string",
        "enum": [
          "draft",
          "active",
          "completed",
          "cancelled"
        ]
      },
      "description": "Only this status: draft, active, completed, cancelled"
    },
    {
      "in": "query",
      "name": "health",
      "schema": {
        "type": "string",
        "enum": [
          "passing",
          "warning",
          "failing"
        ]
      },
      "description": "Only this health: passing, warning, failing"
    },
    {
      "in": "query",
      "name": "$filter",
      "schema": {
        "type": "string"
      },
      "description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
    },
    {
      "in": "query",
      "name": "$select",
      "schema": {
        "type": "string"
      },
      "description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
    },
    {
      "in": "query",
      "name": "$orderby",
      "schema": {
        "type": "string"
      },
      "description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
    },
    {
      "in": "query",
      "name": "$search",
      "schema": {
        "type": "string"
      },
      "description": "Free-text, case-insensitive substring match across the resource's searchable fields."
    },
    {
      "in": "query",
      "name": "$top",
      "schema": {
        "type": "integer"
      },
      "description": "Maximum number of items to return (page size)."
    },
    {
      "in": "query",
      "name": "$skip",
      "schema": {
        "type": "integer"
      },
      "description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
    },
    {
      "in": "query",
      "name": "$count",
      "schema": {
        "type": "boolean"
      },
      "description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Journey"
                }
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Cursor for the next page, or null on the last page. With $top/$skip this is the next $skip value; otherwise a keyset cursor."
              },
              "total": {
                "type": "integer",
                "description": "Total documents in the collection."
              },
              "@odata.count": {
                "type": "integer",
                "description": "Present only when $count=true: total matches after $filter/$search."
              },
              "@odata.truncated": {
                "type": "boolean",
                "description": "Present and true only when the collection exceeded the in-memory query cap and results may be incomplete."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid OData query, or no current user for a /me route"
    }
  }
}

POST /admin/seed-samples

Load the sample templates and journeys (admin)

Writes this app's sample world into the instance: the four published templates (new hire onboarding, offboarding, parental leave, internal transfer) and eight journeys in mixed states with their tasks and activity, the same data a new instance gets from POST /api/purple-suite/instances/{id}/seed, built from the instance's own roster. For an instance created before this app existed, or emptied since. Does nothing while any of this app's collections (templates, journeys, tasks, activity, start claims) holds a record (seeded false, with the current counts) unless force is true, which clears this app's collections first and writes the sample world again. Other apps' data is never touched. Templates are written last; a write that stops partway answers 500 and says to retry with force true. Instance owners only; not exposed as an MCP tool.

Authentication

[
  {
    "patAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "journeys__seed__samples",
  "x-mcp": false,
  "summary": "Load the sample templates and journeys (admin)",
  "description": "Writes this app's sample world into the instance: the four published templates (new hire onboarding, offboarding, parental leave, internal transfer) and eight journeys in mixed states with their tasks and activity, the same data a new instance gets from POST /api/purple-suite/instances/{id}/seed, built from the instance's own roster. For an instance created before this app existed, or emptied since. Does nothing while any of this app's collections (templates, journeys, tasks, activity, start claims) holds a record (seeded false, with the current counts) unless force is true, which clears this app's collections first and writes the sample world again. Other apps' data is never touched. Templates are written last; a write that stops partway answers 500 and says to retry with force true. Instance owners only; not exposed as an MCP tool.",
  "parameters": [
    {
      "$ref": "#/components/parameters/InstanceId"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SeedSamplesRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Whether the sample world was written, and the counts now in the instance",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SeedSamplesResult"
          }
        }
      }
    },
    "403": {
      "description": "A viewer token: only the instance owner can load sample data"
    },
    "500": {
      "description": "A write stopped partway, so the instance holds part of the sample world; the message says to retry with force true"
    }
  }
}