API reference
Journeys
Automated flows started by events or segments, and the templates they start from.
Automated flows started by events or segments, and the templates they start from.
GET /v1/journey-templates#
The organisation's journey templates, by name
curl -X GET "$SAPAGAN_URL/v1/journey-templates" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journey-templates`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"templates": [
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}
]
}POST /v1/journey-templates#
Save a journey's draft as an organisation template (operator)
The draft as it is now, under a name unique in the organisation (409 name_taken). Every workspace of the organisation sees it in New journey. Audited.
Request body
| Field | Type | Notes |
|---|---|---|
journeyId required | string | max 100 |
name required | string | min 1, max 120 |
description | string | max 500 |
curl -X POST "$SAPAGAN_URL/v1/journey-templates" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"journeyId": "<journeyId>",
"name": "order_placed"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journey-templates`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"journeyId": "<journeyId>",
"name": "order_placed"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}GET /v1/journey-templates/{id}#
One organisation template with its definition
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/journey-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journey-templates/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"definition": {}
}PATCH /v1/journey-templates/{id}#
Rename an organisation template or change its description (operator)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 120 |
description | string | max 500 |
curl -X PATCH "$SAPAGAN_URL/v1/journey-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"description": "<description>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journey-templates/user-42`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"description": "<description>"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}DELETE /v1/journey-templates/{id}#
Remove an organisation template (operator)
Journeys already made from it are not affected. Audited, with the definition it had.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X DELETE "$SAPAGAN_URL/v1/journey-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journey-templates/user-42`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"removed": true
}GET /v1/journeys#
List the workspace's journeys, newest first
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
includeArchived | query | "true" | "false" | |
after | query | string (uuid) | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/journeys" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"journeys": [
{
"id": "user-42",
"name": "order_placed",
"status": "draft",
"statusReason": "<statusReason>",
"draft": null,
"draftVersion": 1,
"draftAuthors": [
"<draftAuthors>"
],
"currentVersion": 1,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}
],
"next": "<next>"
}POST /v1/journeys#
Create a journey (operator)
A draft journey. draft is the definition being edited (see the journey definition format); it may be incomplete. A store credential is 403, and 400 webhook_workspace_only when the draft has a webhook step: webhooks are workspace context only.
Request body
| Field | Type | Notes |
|---|---|---|
name required | string | min 1, max 200 |
draft | object |
curl -X POST "$SAPAGAN_URL/v1/journeys" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"status": "draft",
"statusReason": "<statusReason>",
"draft": null,
"draftVersion": 1,
"draftAuthors": [
"<draftAuthors>"
],
"currentVersion": 1,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}GET /v1/journeys/{id}#
A journey with its draft and its published versions
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"status": "draft",
"statusReason": "<statusReason>",
"draft": null,
"draftVersion": 1,
"draftAuthors": [
"<draftAuthors>"
],
"currentVersion": 1,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"versions": [
{
"version": 1,
"messageType": "<messageType>",
"publishedBy": "<publishedBy>",
"approvedBy": "<approvedBy>",
"publishedAt": "<publishedAt>",
"note": "Looks good"
}
]
}PATCH /v1/journeys/{id}#
Change a journey's name or draft (operator)
expectedDraftVersion (the draftVersion last read) refuses a lost update with 409 draft_changed. Published versions never change; publish the draft to make a new one.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 200 |
draft | object | |
expectedDraftVersion | integer | min 1 |
curl -X PATCH "$SAPAGAN_URL/v1/journeys/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"draft": {},
"expectedDraftVersion": 1
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"draft": {},
"expectedDraftVersion": 1
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"status": "draft",
"statusReason": "<statusReason>",
"draft": null,
"draftVersion": 1,
"draftAuthors": [
"<draftAuthors>"
],
"currentVersion": 1,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}POST /v1/journeys/{id}/archive#
Archive (final): every run still under way ends (operator)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X POST "$SAPAGAN_URL/v1/journeys/user-42/archive" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/archive`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"status": "draft",
"statusReason": "<statusReason>",
"draft": null,
"draftVersion": 1,
"draftAuthors": [
"<draftAuthors>"
],
"currentVersion": 1,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"ended": 1
}POST /v1/journeys/{id}/pause#
Pause: nobody enters, no step runs, nothing is sent (operator)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
reason | string | max 200 |
curl -X POST "$SAPAGAN_URL/v1/journeys/user-42/pause" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/pause`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"status": "draft",
"statusReason": "<statusReason>",
"draft": null,
"draftVersion": 1,
"draftAuthors": [
"<draftAuthors>"
],
"currentVersion": 1,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}POST /v1/journeys/{id}/publish#
Publish the draft as the next version (operator)
400 invalid_definition lists the problems in details.issues. A transactional journey (any hour, unsubscribed people too) is published only by a workspace owner who did not edit the draft (403 owner_required; never a key). 409 no_changes when the draft is the published version, draft_changed when expectedDraftVersion is stale. With second-person approval, 403 second_person_required for anyone who edited the draft (and for keys). A paused journey stays paused unless resume is true (then it resumes as /resume does).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
expectedDraftVersion | integer | min 1 |
note | string | max 500 |
resume | boolean |
curl -X POST "$SAPAGAN_URL/v1/journeys/user-42/publish" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"expectedDraftVersion": 1,
"note": "Looks good",
"resume": true
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/publish`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"expectedDraftVersion": 1,
"note": "Looks good",
"resume": true
}),
});
const data = await res.json();Responses
{
"journey": {
"id": "user-42",
"name": "order_placed",
"status": "draft",
"statusReason": "<statusReason>",
"draft": null,
"draftVersion": 1,
"draftAuthors": [
"<draftAuthors>"
],
"currentVersion": 1,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
},
"version": 1
}POST /v1/journeys/{id}/resume#
Resume a paused journey (operator)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X POST "$SAPAGAN_URL/v1/journeys/user-42/resume" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/resume`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"status": "draft",
"statusReason": "<statusReason>",
"draft": null,
"draftVersion": 1,
"draftAuthors": [
"<draftAuthors>"
],
"currentVersion": 1,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}GET /v1/journeys/{id}/runs#
A journey's runs, newest first
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
state | query | "active" | "waiting" | "completed" | "exited" | "failed" | |
profileId | query | string (uuid) | |
includeTests | query | "true" | "false" | |
after | query | string (uuid) | |
limit | query | integer | |
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42/runs" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/runs`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"runs": [
{
"id": "user-42",
"journeyId": "<journeyId>",
"version": 1,
"isTest": true,
"profileId": "user-42",
"externalId": "user-42",
"state": "<state>",
"currentNode": "<currentNode>",
"seq": 1,
"waitingForEvent": "<waitingForEvent>",
"wakeAt": "<wakeAt>",
"enteredAt": "<enteredAt>",
"endedAt": "<endedAt>",
"endReason": "<endReason>"
}
],
"next": "<next>"
}GET /v1/journeys/{id}/runs/{runId}#
One run with its steps
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required | |
runId | path | string required |
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42/runs/<runId>" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/runs/<runId>`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"journeyId": "<journeyId>",
"version": 1,
"isTest": true,
"profileId": "user-42",
"externalId": "user-42",
"state": "<state>",
"currentNode": "<currentNode>",
"seq": 1,
"waitingForEvent": "<waitingForEvent>",
"wakeAt": "<wakeAt>",
"enteredAt": "<enteredAt>",
"endedAt": "<endedAt>",
"endReason": "<endReason>",
"steps": [
{
"seq": 1,
"nodeId": "<nodeId>",
"action": "<action>",
"result": null,
"at": "<at>"
}
]
}GET /v1/journeys/{id}/stats#
Per-step statistics (test runs left out)
Runs, steps, sends and the goal for every version, or for version. nodes (the canvas's figures per step) always describe one version, nodesVersion: the one asked, else the current one.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
version | query | integer | |
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42/stats" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/stats`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"version": 1,
"runs": {
"total": 1,
"byState": {},
"byEndReason": {}
},
"steps": {},
"sends": [
{
"version": 1,
"nodeId": "<nodeId>",
"total": 1,
"byStatus": {},
"suppressedByReason": {},
"sent": 1,
"opened": 1,
"openRate": 1,
"channel": "<channel>",
"clicked": 1,
"clickRate": 1,
"dismissed": 1,
"webhook": {
"attempted": 1,
"succeeded": 1,
"failed": 1,
"retrying": 1
}
}
],
"goal": {
"conversions": 1,
"revenue": 1
},
"nodes": {},
"nodesVersion": 1
}POST /v1/journeys/{id}/test#
Run the draft for one allowlisted person (operator)
The person (external id) must be on the workspace's recipient allowlist (400 not_allowlisted). The test run follows the draft as it is now, waits included unless fastWaits (every wait and wait-until timeout then lasts one minute); its sends are deliveries of source test and stay out of the statistics.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
externalId required | string | min 1, max 500 |
fastWaits | boolean |
curl -X POST "$SAPAGAN_URL/v1/journeys/user-42/test" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "user-42"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/test`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"externalId": "user-42"
}),
});
const data = await res.json();Responses
{
"runId": "<runId>"
}GET /v1/journeys/{id}/versions/{version}#
A published version's definition
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required | |
version | path | integer required |
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42/versions/<version>" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/user-42/versions/<version>`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"version": 1,
"messageType": "<messageType>",
"publishedBy": "<publishedBy>",
"approvedBy": "<approvedBy>",
"publishedAt": "<publishedAt>",
"note": "Looks good",
"definition": null
}GET /v1/journeys/overview#
Figures for the journeys list: people in flight, entered and converted
One line per journey named in ids (comma separated, at most 200), test runs left out. A journey of another workspace, or none, counts zero.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
ids | query | string required |
curl -X GET "$SAPAGAN_URL/v1/journeys/overview?ids=%3Cids%3E" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/overview?ids=%3Cids%3E`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"journeys": [
{
"journeyId": "<journeyId>",
"inFlight": 1,
"entered": 1,
"converted": 1
}
]
}GET /v1/journeys/test-people#
Who a test run may enrol: the workspace's test people
The workspace's test people (Settings, Setup; in a development workspace its recipient allowlist), at most 100, each with whether a live person has the id and their name. A test run enrols only these people. Operator role; each read is audited (profile_view_audit, action list).
curl -X GET "$SAPAGAN_URL/v1/journeys/test-people" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/test-people`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"people": [
{
"externalId": "user-42",
"exists": true,
"name": "order_placed"
}
]
}POST /v1/journeys/validate#
Validate a definition (nothing is stored)
Every problem at once, each with its JSON path and, for a step, its id. The same validation publishing applies (link allowlist and segments of this workspace included).
Request body
| Field | Type | Notes |
|---|---|---|
definition | any | |
journeyId | string (uuid) |
curl -X POST "$SAPAGAN_URL/v1/journeys/validate" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"definition": null,
"journeyId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/validate`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"definition": null,
"journeyId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
}),
});
const data = await res.json();Responses
{
"ok": true,
"issues": [
{
"path": "<path>",
"nodeId": "<nodeId>",
"code": "<code>",
"message": "<message>"
}
]
}GET /v1/journeys/webhook-secrets#
The vault secrets a webhook step can sign with (names only)
The names (webhook_*) of the workspace's own vault secrets and the organisation-wide ones, with when each was set. A secret's value is never returned, here or anywhere: the journey names the secret and the worker reads it to sign. An owner adds one with pnpm kentongan secrets:set on the host.
curl -X GET "$SAPAGAN_URL/v1/journeys/webhook-secrets" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/journeys/webhook-secrets`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"secrets": [
{
"name": "order_placed",
"level": "workspace",
"setAt": "<setAt>"
}
]
}