> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Flow Status
> This API changes a flow's lifecycle state. It validates the requested transition against the flow's
current state before applying it; an invalid transition returns `409`. Your API key must have the
`campaigns:create_manage` permission (see the [Authentication](/api/flows/flows-overview#authentication) section).
Lifecycle actions (`pause`, `resume`, `stop`, `retire`) accept an optional `version_no` and act on that
version (default: the active version). `archive` / `unarchive` apply to the whole flow and reject a `version_no`.
| Action | Allowed from | Result |
| ----------- | ----------------------------------------------------------- | --------------------- |
| `pause` | `ACTIVE`, `SCHEDULED` | `PAUSED` |
| `resume` | `PAUSED` | `ACTIVE` |
| `stop` | `ACTIVE`, `SCHEDULED`, `PAUSED`, `RETIRED` | `STOPPED` |
| `retire` | `ACTIVE`, `PAUSED` | `RETIRED` |
| `archive` | `PAUSED`, `STOPPED`, `COMPLETED` (and not already archived) | sets `archived=true` |
| `unarchive` | any archived flow | sets `archived=false` |
#### Rate Limits
The rate limits are at the workspace level. A maximum of 10 requests per second, 100 requests per minute, and 6,000 requests per hour are allowed per workspace.
## OpenAPI
````yaml /api/flows/flows.yaml patch /v5/flows/{flow_id}/status
openapi: 3.0.0
info:
title: Flows
version: '5.0'
description: >
Use the Flows endpoints to list your flows, view the details of a single
flow (including its
versions and stages), and change a flow's status. These
endpoints read and control existing flows; they do not create them.
The Flows endpoints are in early access. MoEngage enhances these endpoints based on feedback during this period, but does not make breaking changes.
The API exposes the following endpoints:
- `POST /v5/flows/search` — paginated listing with filters (status, delivery
type, tags,
teams, name, creator, creation-date range).
- `GET /v5/flows/{flow_id}` — single flow detail. Use the optional
`version_no` query
parameter to view a specific version; the default is the last published version, or
the draft if none is published.
- `GET /v5/flows/{flow_id}/versions/{version_id}` — the details of a flow as
it was in a
specific version, identified by its ID.
- `PATCH /v5/flows/{flow_id}/status` — lifecycle transition (`pause`,
`resume`, `stop`,
`retire`) or the flow-level `archive` / `unarchive` toggle.
**Conventions**
- IDs are 24-character identifiers. `flow_id` identifies the flow;
`version_id` identifies one
of its versions.
- Every successful response uses the format `{response_id, type, data}`. The
`response_id`
echoes the `request_id` you send; if you omit it, the server uses the first 12 characters
of a system-generated UUID.
- Dates and times are in ISO 8601 UTC format (`YYYY-MM-DDThh:mm:ssZ`).
- The search endpoint returns results one page at a time. To fetch the next
page, send the
`next_cursor` from the previous response back as the `cursor` value.
**Permissions**
Flows reuse the `campaigns` permission for scope checks. Read endpoints
require the
`campaigns:view` permission; the status endpoint requires
`campaigns:create_manage`.
**Status Model**
Public flow statuses: `DRAFT`, `ACTIVE`, `SCHEDULED`, `PAUSED`, `STOPPED`,
`COMPLETED`,
`RETIRED`, `UNDER_REVIEW`, `REJECTED`. `archived` is a separate boolean flag
(it spans every version of the flow), not a status.
**Rate Limits**: The rate limits are at the workspace level. A maximum of 10
requests per second,
100 requests per minute, and 6,000 requests per hour are allowed per
workspace for the search,
get, and status endpoints.
Breaching any limit rejects the request with a `429` response.
servers:
- url: https://api-{dc}.moengage.com
variables:
dc:
default: '01'
description: >
MoEngage data center identifier. Replace it with the number assigned
to your account, such as 01 (US), 02 (EU), 03 (India), 04 (US), 05
(Singapore), or 06 (Indonesia). For example,
https://api-01.moengage.com. Data center 101 is not supported.
enum:
- '01'
- '02'
- '03'
- '04'
- '05'
- '06'
security:
- basicAuth: []
paths:
/v5/flows/{flow_id}/status:
patch:
tags:
- Flows
summary: Update Flow Status
description: >
This API changes a flow's lifecycle state. It validates the requested
transition against the flow's
current state before applying it; an invalid transition returns `409`.
Your API key must have the
`campaigns:create_manage` permission (see the
[Authentication](/api/flows/flows-overview#authentication) section).
operationId: updateFlowStatus
parameters:
- $ref: '#/components/parameters/FlowId'
- name: Idempotency-Key
in: header
required: true
description: >-
Client-generated UUID v4. Reusing the same key replays the original
response instead of re-applying the transition.
schema:
type: string
format: uuid
- $ref: '#/components/parameters/XMoeTenantId'
- $ref: '#/components/parameters/XMoeRequestIdHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FlowStatusRequest'
examples:
pause:
summary: Pause an active flow
value:
action: pause
updated_by: agent@example.com
archive:
summary: Archive a flow
value:
action: archive
updated_by: agent@example.com
responses:
'200':
description: Flow status updated.
headers:
X-MOE-Request-Id:
$ref: '#/components/headers/XMoeRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FlowStatusResponse'
example:
response_id: abc-200
type: flow
data:
flow_id: 69f1de84f9e401a2d7d9a931
status: PAUSED
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenStatusWrite'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: >-
The requested action is not a valid transition from the flow's
current status.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-409
error:
code: BAD_REQUEST
target: action
message: Cannot resume a flow that is not paused.
details: []
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- basicAuth: []
components:
parameters:
FlowId:
name: flow_id
in: path
required: true
description: >
The 24-character ID of the flow. This must be the flow's own ID, not a
version ID; passing a version ID returns `400`.
schema:
type: string
pattern: ^[a-f0-9]{24}$
example: 6a3b09c938da57c8f5838880
XMoeTenantId:
name: X-MOE-Tenant-ID
in: header
required: false
description: >
Identifies the tenant/workspace making the request. Optional — when
omitted, the workspace is resolved from the Basic Auth credentials in
the `Authorization` header.
schema:
type: string
XMoeRequestIdHeader:
name: X-MOE-Request-Id
in: header
required: false
description: >
Client-supplied trace ID. The server echoes it in the `X-MOE-Request-Id`
response header and in `response_id`. If you omit it, the server
generates one.
schema:
type: string
schemas:
FlowStatusRequest:
type: object
required:
- action
- updated_by
properties:
action:
type: string
description: >-
The lifecycle operation to apply. `publish` is not available in this
phase.
enum:
- pause
- resume
- stop
- retire
- archive
- unarchive
version_no:
type: integer
minimum: 1
description: >
Optional. For lifecycle actions (`pause`, `resume`, `stop`,
`retire`), acts on this version (default: the active version).
Rejected for `archive` / `unarchive`.
updated_by:
type: string
format: email
description: Email of the user performing the action. Recorded in the audit log.
request_id:
type: string
description: >-
Optional if supplied via the `X-MOE-Request-Id` header; echoed in
`response_id`.
FlowStatusResponse:
type: object
required:
- response_id
- type
- data
properties:
response_id:
type: string
type:
type: string
enum:
- flow
data:
type: object
required:
- flow_id
- status
properties:
flow_id:
type: string
description: The flow acted on.
status:
$ref: '#/components/schemas/FlowStatusEnum'
ErrorResponse:
type: object
required:
- error
- response_id
properties:
response_id:
type: string
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- VALIDATION_FAILED
- BAD_REQUEST
- NOT_FOUND
- UNAUTHORIZED
- FORBIDDEN
- RATE_LIMITED
- INTERNAL_ERROR
message:
type: string
target:
type: string
description: The component or field the error relates to.
details:
type: array
description: One entry per failing check.
items:
type: object
properties:
target:
type: string
message:
type: string
FlowStatusEnum:
type: string
description: >
Public lifecycle status of a flow (or of a specific version),
independent of the `archived` flag.
enum:
- DRAFT
- ACTIVE
- SCHEDULED
- PAUSED
- STOPPED
- COMPLETED
- RETIRED
- UNDER_REVIEW
- REJECTED
headers:
XMoeRequestId:
description: Echoed request ID. If you do not provide one, the server generates it.
schema:
type: string
responses:
BadRequest:
description: >
The request failed validation — for example, a bad filter value, a
malformed cursor, a non-integer `version_no`, an invalid date range, or
a `flow_id` that is actually a version ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-101
error:
code: VALIDATION_FAILED
target: request
message: One or more request parameters failed validation.
details:
- target: request
message: Check the request parameters and try again.
Unauthorized:
description: Authentication failed (missing or invalid credentials).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-101
error:
code: UNAUTHORIZED
message: Invalid or missing credentials.
details: []
ForbiddenStatusWrite:
description: You do not have the required permission for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-450
error:
code: FORBIDDEN
target: permission
message: You do not have the required permission for this operation.
details:
- target: permission
message: 'Required permission: campaigns:create_manage'
NotFound:
description: The flow (or the requested version) does not exist in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-100
error:
code: NOT_FOUND
target: flow
message: Flow not found.
details:
- target: flow_id
message: Flow not found.
RateLimited:
description: >-
Per-app rate limit exceeded. Retry after the interval indicated in the
`Retry-After` header.
headers:
Retry-After:
schema:
type: integer
description: Seconds until the rate-limit window resets.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-101
error:
code: RATE_LIMITED
message: Rate limit exceeded for app key.
details: []
InternalServerError:
description: Unhandled server-side failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-101
error:
code: INTERNAL_ERROR
message: Internal server error.
details: []
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >
Authentication is done via Basic Auth. This requires a base64-encoded
string of your credentials in the format 'username:password'.
- **Username**: Use your MoEngage workspace ID (also known as the App
ID). You can find it in the MoEngage dashboard at **Settings** >
**Account** > **APIs** > **Workspace ID (earlier app id)**.
- **Password**: On your MoEngage workspace, navigate to **Settings** →
**Account** → **API keys** and click **Create new key**. The tab lists
every API surface (Data, Segmentation, Push, Email, Campaigns,
Templates, and more) and exposes per-resource actions. Flows reuse the
Campaigns permissions — ensure the **View** checkbox (for the read
endpoints) and the **Create & Manage** checkbox (for Update Flow Status)
are selected.
For more information on authentication and getting your credentials,
refer to [Getting your
credentials](/api/introduction#getting-your-credentials).
Send the value in the `Authorization` header as `Basic` followed by
Base64-encoding of `appkey:apisecret` (workspace ID and API key).
````