SapaganDocs sapagan.com

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

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/journey-templates" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Request body

FieldTypeNotes
journeyId requiredstringmax 100
name requiredstringmin 1, max 120
descriptionstringmax 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"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 201

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/journey-templates/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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)

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
namestringmin 1, max 120
descriptionstringmax 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>"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X DELETE "$SAPAGAN_URL/v1/journey-templates/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "id": "user-42",
  "removed": true
}

GET /v1/journeys#

List the workspace's journeys, newest first

Accepted keys Server key

Parameters

NameInTypeNotes
includeArchivedquery"true" | "false"
afterquerystring (uuid)
limitqueryinteger
curl -X GET "$SAPAGAN_URL/v1/journeys" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key Store key Store token

Request body

FieldTypeNotes
name requiredstringmin 1, max 200
draftobject
curl -X POST "$SAPAGAN_URL/v1/journeys" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_placed"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 409 Conflict. Errors use the error body.

Example response 201

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
namestringmin 1, max 200
draftobject
expectedDraftVersionintegermin 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
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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)

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X POST "$SAPAGAN_URL/v1/journeys/user-42/archive" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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)

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
reasonstringmax 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"
  }'

Responses

200 OK, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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).

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
expectedDraftVersionintegermin 1
notestringmax 500
resumeboolean
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
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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)

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X POST "$SAPAGAN_URL/v1/journeys/user-42/resume" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
statequery"active" | "waiting" | "completed" | "exited" | "failed"
profileIdquerystring (uuid)
includeTestsquery"true" | "false"
afterquerystring (uuid)
limitqueryinteger
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42/runs" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
runIdpathstring required
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42/runs/<runId>" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
versionqueryinteger
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42/stats" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
externalId requiredstringmin 1, max 500
fastWaitsboolean
curl -X POST "$SAPAGAN_URL/v1/journeys/user-42/test" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-42"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 201

{
  "runId": "<runId>"
}

GET /v1/journeys/{id}/versions/{version}#

A published version's definition

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
versionpathinteger required
curl -X GET "$SAPAGAN_URL/v1/journeys/user-42/versions/<version>" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idsquerystring required
curl -X GET "$SAPAGAN_URL/v1/journeys/overview?ids=%3Cids%3E" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 400 Invalid request, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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).

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/journeys/test-people" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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).

Accepted keys Server key

Request body

FieldTypeNotes
definitionany
journeyIdstring (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"
  }'

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/journeys/webhook-secrets" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "secrets": [
    {
      "name": "order_placed",
      "level": "workspace",
      "setAt": "<setAt>"
    }
  ]
}