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 from a document or a starter template. A journey document has a trigger (event with filters and entry mode, manual, record_created/updated, date_field), exit conditions re-checked before every step, and steps: wait, send_email (template slug or subject+html with {{placeholders}}), check (property / event_since_entry / engagement of a prior send, with yes/no step ids), update_record, call_webhook, run_function (a site function by name, or an account function with target {kind:"account", functionId}), exit. Starts as a draft unless status=live. Check events_catalog first so the trigger names an event the site really records. Asked by an agent or an automation to go live, it is saved as a draft (the answer says so): a person switches it on. A role without the Publish permission on automations also gets a live journey saved as a draft (the answer says so); an agent or an automation is refused changing a journey that people are in.

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 inside finish; stopped = halts everyone now; draft = editing. Going live is a person's: an agent or an automation is refused it.

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). Act only on what the person named or picked.

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 (member id or email) 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"
}'