Journeys API

Multi-step journeys: create them from templates, enrol people, run them, and review runs.

10 endpoints

Endpoints

POST

/api/v1/journeys/templates

Starter journeys (welcome series, abandoned cart, appointment reminder, win-back) as full documents to adapt. Each lists the site events it needs.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/templates \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

POST

/api/v1/journeys/list

Journeys of a site with their status (draft/live/paused/stopped), trigger, step count and run counts.

Parameters

projectId

stringrequired

Site id

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/list \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example"
}'

POST

/api/v1/journeys/get

One journey with its full document and stats (runs by status, emails sent, opened, clicked).

Parameters

id stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/get \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example"
}'

POST

/api/v1/journeys/create

Create a journey for a site. It starts as a draft unless status=live.

Parameters

`projectId`	stringrequired	Site id
`name`	stringrequired
`description`	string
`document`	any	A full journey document (see journeys_templates for the shape)
`template`	string	Starter key from journeys_templates (welcome-series, abandoned-cart, appointment-reminder, win-back)
`status`	string	draft (default) or live

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/create \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example",
  "name": "example",
  "description": "example"
}'

POST

/api/v1/journeys/update

Rename, describe, or replace the document (version bumps; people already inside follow the new steps from where they are).

Parameters

`id`	stringrequired
`name`	string
`description`	string
`document`	any	Replaces the whole document; the version bumps and in-flight runs follow the new steps from where they are

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/update \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "name": "example",
  "description": "example"
}'

POST

/api/v1/journeys/setStatus

live = enrols and sends; paused = no new entries, people already inside finish; stopped = halts everyone now; draft = editing

Parameters

`id`	stringrequired
`status`	stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/setStatus \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example",
  "status": "example"
}'

POST

/api/v1/journeys/delete

Delete a journey (stops every run first).

Parameters

id stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/delete \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example"
}'

POST

/api/v1/journeys/runs

People in a journey: status, current step, next send time, exit reason, lastError. When an email step failed, lastError is the mail server's own words only for someone who holds the "Add and remove mailboxes" permission; anyone else reads plain words saying so — pass those on, don't guess the cause.

Parameters

`journeyId`	stringrequired
`status`	string
`limit`	integer

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/runs \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "journeyId": "example",
  "status": "example",
  "limit": {}
}'

POST

/api/v1/journeys/run

One run with its step log and the emails it sent. A failed email step's error (lastError and that step's detail.error) is the mail server's own words only for someone who holds the "Add and remove mailboxes" permission; anyone else reads plain words saying so. Other steps' errors are shown as logged.

Parameters

id stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/run \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example"
}'

POST

/api/v1/journeys/enrol

Put one person into a live journey by hand (also how a function or agent starts a `manual` journey).

Parameters

`journeyId`	stringrequired
`subjectId`	string	Site member id
`email`	string
`properties`	object

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/journeys/enrol \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "journeyId": "example",
  "subjectId": "example",
  "email": "example"
}'