# Pause a journey

`POST /v1/journeys/{id}/pause`

Requires an API key with the `journeys:write` scope. [About keys and scopes](/docs/api/authentication)

Stops new contacts entering the journey. Contacts already partway through stay where they are and resume if the journey is activated again. Only an active journey can be paused: a draft answers 409 `CONFLICT`. Needs `journeys:write`, so agent keys may pause; activating again needs `journeys:activate`.

## Path parameters

- `id` (string, required, uuid)

## Returns

Returns `200 OK` with a `Journey` in `data`. Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `id` (string, required, uuid)
- `name` (string, required)
- `triggerEvent` (string, required) — The event that starts a run.
- `dateTrigger` (object | null, required) — The contact date that starts runs, for a date journey; otherwise `null`.
  - `field` (string, required) — The contact date field the journey runs from.
  - `recurrence` (string, required, one of `once`, `annual`) — `once` runs on the date a single time; `annual` repeats every year.
  - `offsetDays` (integer, required, min -365, max 365, default `0`) — Days from the date to start: negative before it, positive after. Defaults to 0.
  - `time` (string, required) — Time of day to start, as `HH:MM` in the contact's timezone, else the workspace's.
  - `leapDay` (string, required, one of `feb28`, `mar1`, `skip`, default `"feb28"`) — For an annual 29 February date in a common year: run on 28 Feb, on 1 Mar, or skip.
- `entryConditions` (object, required) — Property values the trigger event must carry to start a run.
- `reentry` (object, required) — Whether a contact may enter again.
  - One of: **Once**
    - `mode` ("once", required)
  - One of: **Repeatable**
    - `mode` ("repeatable", required)
    - `cooldownDays` (integer, required, min 0, max 3650, default `0`) — Days after a run starts before the same contact may enter again.
- `exitConditions` (object[], required) — Events that end a contact's run early.
  - `type` ("event", required)
  - `eventName` (string, required, 1–128 characters) — The event that ends a contact's run when they do it.
  - `properties` (object, required, default `{}`) — Property values the event must carry to count; all must match exactly.
- `steps` (object[], required) — The steps, in order.
  - One of: **Wait step**
    - `type` ("wait", required)
    - `durationSeconds` (integer, required, min 1, max 31536000) — How long to wait, in seconds; at most 365 days.
    - `window` (object, optional) — Hours the wait may end in, in the contact's local time.
      - `startHour` (integer, required, min 0, max 23) — Hour of day (0-23) the window opens, inclusive.
      - `endHour` (integer, required, min 1, max 24) — Hour of day (1-24) the window closes; it must be after `startHour`.
      - `days` (integer[], optional, at least 1 item, at most 7 items) — Days of the week the window is open, 0 = Sunday to 6 = Saturday; every day when left out.
    - `nextStep` (integer | null, optional, min 0, max 9007199254740991) — Index in `steps` of the step to run next. It must come after this step; `null` or omitted ends the journey here.
  - One of: **Wait-until step**
    - `type` ("wait_until", required)
    - `eventName` (string, required, 1–128 characters) — The event to wait for.
    - `where` (object[], optional, at least 1 item, at most 5 items) — Conditions on the event's properties; all must hold.
      - `property` (string, required, 1–64 characters) — The event property key.
      - `operator` (string, required, one of `equals`, `notEquals`, `gt`, `gte`, `lt`, `lte`)
      - `value` (string | number | boolean, required)
    - `timeoutSeconds` (integer, required, min 60, max 7776000) — How long to wait for the event, in seconds: 60 to 90 days.
    - `onMatchStep` (integer, required, min 0, max 9007199254740991) — Index of the step to take when the event happens.
    - `onTimeoutStep` (integer | null, required, min 0, max 9007199254740991) — Index of the step to take on timeout; `null` ends the journey.
  - One of: **Digest step**
    - `type` ("digest", required)
    - `windowSeconds` (integer, required, min 60, max 604800) — How long to gather events, in seconds: 60 to 7 days.
    - `nextStep` (integer | null, optional, min 0, max 9007199254740991) — Index in `steps` of the step to run next. It must come after this step; `null` or omitted ends the journey here.
  - One of: **Email send step**
    - `id` (string, optional, uuid) — Assigned by the server; send it back unchanged so a message keeps its identity when steps move.
    - `type` ("send", required)
    - `channel` ("email", required)
    - `content` (object, required) — The email, as saved.
      - `subject` (string, optional, 1–998 characters) — The subject line. Merge tags are allowed.
      - `previewText` (string, optional, 1–255 characters) — Shown by inboxes after the subject. Merge tags are allowed; keep it near 100 characters.
      - `html` (string, optional, 1–512000 characters) — The HTML body. Rendered from the design when one is set.
      - `text` (string, optional, 1–512000 characters) — The plain-text alternative.
      - `from` (string, optional, 1–320 characters) — The sender address, on a verified sending domain.
      - `replyTo` (string, optional, email) — Where replies go.
      - `templateSnapshot` (TemplateSnapshot, optional)
        - `schemaVersion` (integer, required, min > 0, max 1000) — The block format version; use the current one, 1.
        - `blocks` (EmailBlock[], required, at least 1 item, at most 200 items) — At most 200 blocks across the entire tree and five levels including the root. Footer blocks must remain at root. Known child fields are validated recursively.
        - `theme` (EmailTheme, required) — Theme values this email overrides.
        - `plainTextOverride` (string | null, optional, up to 100000 characters) — Plain text sent instead of the version generated from the blocks.
    - `nextStep` (integer | null, optional, min 0, max 9007199254740991) — Index in `steps` of the step to run next. It must come after this step; `null` or omitted ends the journey here.
    - `onUnreachableStep` (integer, optional, min 0, max 9007199254740991) — Index of the step to go to when the contact cannot receive this channel; unset skips the send.
    - `topicId` (string, optional, uuid) — Sends only to contacts the topic reaches; unset sends to everyone with consent.
  - One of: **Push send step**
    - `id` (string, optional, uuid) — Assigned by the server; send it back unchanged so a message keeps its identity when steps move.
    - `type` ("send", required)
    - `channel` ("push", required)
    - `content` (object, required) — The notification. Any part may be missing on a draft.
      - `pushProjectId` (string, optional, uuid) — The push app to send through.
      - `push` (object, optional) — The notification content.
        - `title` (string, optional, 1–100 characters) — The notification title (up to 100 characters).
        - `body` (string, optional, 1–500 characters) — The notification text (up to 500 characters).
        - `actionUrl` (string, optional, uri, up to 2048 characters) — The HTTPS page opened when the notification is tapped.
        - `imageUrl` (string, optional, uri, up to 2048 characters) — A large picture: web and Android show it; iOS needs the app's service extension.
        - `iconUrl` (string, optional, uri, up to 2048 characters) — Web only; iOS and Android show the app's own notification icon.
        - `data` (object, optional) — Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.
        - `buttons` (object[], optional, at least 1 item, at most 2 items) — Up to 2 action buttons.
        - `collapseKey` (string, optional) — A newer notification with the same key replaces the older one on the device.
        - `sound` (string, optional, 1–64 characters) — The name of a sound the app ships; the device's default if unset.
        - `badge` (integer, optional, min 0, max 99999) — The number shown on the iOS app icon.
        - `ttlSeconds` (integer, optional, min 0, max 2419200) — Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).
        - `urgency` (string, optional, one of `high`, `normal`) — `high` wakes the device now; `normal` lets it wait for a good moment to save battery. Unset, a transactional push is `high` and any other `normal`.
        - `overrides` (object, optional) — Fields that differ on one platform, each replacing the shared one there (a whole `data` map, not merged key by key). On iOS and Android `actionUrl` may be an app link such as `myapp://orders`; the shared one and the web one must be HTTPS.
    - `nextStep` (integer | null, optional, min 0, max 9007199254740991) — Index in `steps` of the step to run next. It must come after this step; `null` or omitted ends the journey here.
    - `onUnreachableStep` (integer, optional, min 0, max 9007199254740991) — Index of the step to go to when the contact cannot receive this channel; unset skips the send.
    - `topicId` (string, optional, uuid) — Sends only to contacts the topic reaches; unset sends to everyone with consent.
  - One of: **Branch step**
    - `type` ("branch", required)
    - `condition` (object, required) — Event property values to compare with the trigger event; all must match exactly.
    - `onMatchStep` (integer, required, min 0, max 9007199254740991) — Index of the step to take when the condition matches.
    - `onNoMatchStep` (integer, required, min 0, max 9007199254740991) — Index of the step to take when it does not.
  - One of: **Filter step**
    - `type` ("filter", required)
    - `mode` (string, required, one of `once`, `continuous`) — `once` checks the rules here only; `continuous` re-checks them before every later step.
    - `rules` (object, required) — The contact must match these rules.
      - One of: **Match all**
        - `all` (object[], required, at least 1 item, at most 20 items) — Every rule or nested group must match.
      - One of: **Match any**
        - `any` (object[], required, at least 1 item, at most 20 items) — At least one rule or nested group must match.
    - `onMatchStep` (integer, required, min 0, max 9007199254740991) — Index of the step to take when the contact matches.
    - `onNoMatchStep` (integer | null, required, min 0, max 9007199254740991) — Index of the step to take when they do not; `null` ends the journey.
  - One of: **Split step**
    - `type` ("split", required)
    - `paths` (object[], required, at least 1 item, at most 5 items) — Paths checked in order; the first whose rules match is taken.
      - `rules` (object, required) — The contact takes this path when they match.
        - One of: **Match all**
        - One of: **Match any**
      - `nextStep` (integer, required, min 0, max 9007199254740991) — Index of the step this path leads to.
    - `otherwiseStep` (integer | null, required, min 0, max 9007199254740991) — Index of the step to take when no path matches; `null` ends the journey.
  - One of: **Action step**
    - `type` ("action", required)
    - `action` (object, required) — What this step does to the contact.
      - One of: **Set attribute**
        - `kind` ("set_attribute", required)
        - `key` (string, required) — The contact attribute's key.
        - `value` (string | number | boolean | null, required) — The value to set; `null` clears it.
      - One of: **Add to or remove from list attribute**
        - `kind` (string, required, one of `add_to_attribute`, `remove_from_attribute`)
        - `key` (string, required) — The contact attribute's key.
        - `value` (string | number | boolean, required) — The one item to add to, or remove from, the list; other items are kept.
      - One of: **Add to group**
        - `kind` ("add_to_group", required)
        - `groupId` (string, required, uuid) — The group to add the contact to.
      - One of: **Remove from group**
        - `kind` ("remove_from_group", required)
        - `groupId` (string, required, uuid) — The group to remove the contact from.
      - One of: **Send webhook**
        - `kind` ("webhook", required)
        - `webhookId` (string, required, uuid) — The webhook endpoint to notify.
        - `data` (object, required, default `{}`) — Extra data sent in the `journey.action` payload.
    - `nextStep` (integer | null, optional, min 0, max 9007199254740991) — Index in `steps` of the step to run next. It must come after this step; `null` or omitted ends the journey here.
- `messageLimits` (MessageLimitUse, required)
  - `apply` (boolean, required)
  - `retryHours` (integer, optional, min 0, max 48)
- `utm` (object | null, required) — Link tags for the journey's email; `null` follows the workspace.
  - `enabled` (boolean, required)
  - `source` (string, optional, 1–100 characters)
  - `medium` (string, optional, 1–100 characters)
  - `campaign` (string, optional, 1–100 characters)
  - `content` (string, optional, 1–100 characters)
  - `term` (string, optional, 1–100 characters)
- `maxEntries` (integer | null, required, min > 0, max 9007199254740991) — The most runs the journey starts over its life; `null` has no cap.
- `enrolledCount` (integer, required, min 0, max 9007199254740991) — Runs ever started.
- `status` (string, required, one of `draft`, `active`, `paused`, `ended`) — `ended`: nobody enters and runs in progress were exited; it cannot restart.
- `revision` (integer, required, min > 0, max 2147483647) — Raised by every edit. Send it back as `expectedRevision` on the update so a change made since you read it is refused instead of overwritten.
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)

## Example

```bash
curl -X POST https://api.kirora.io/v1/journeys/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/pause \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "name": "Weekend specials",
    "triggerEvent": "triggerEvent_example",
    "dateTrigger": {
      "field": "field_example",
      "recurrence": "once",
      "offsetDays": 0,
      "time": "time_example",
      "leapDay": "feb28"
    },
    "entryConditions": {},
    "reentry": {
      "mode": "once"
    },
    "exitConditions": [
      {
        "type": "event",
        "eventName": "Order Completed",
        "properties": {}
      }
    ],
    "steps": [
      {
        "type": "wait",
        "durationSeconds": 1
      }
    ],
    "messageLimits": {
      "apply": true
    },
    "utm": {
      "enabled": true
    },
    "maxEntries": 1,
    "enrolledCount": 0,
    "status": "draft",
    "revision": 1,
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z"
  }
}
```