Clomni

Scopes and endpoints: campaigns, flows, automations

Last updated: 11 November 2026 · 11 min read

Scopes for campaigns, flows and automation rules. All three follow one rule: write prepares a draft, and the step that reaches customers (sending, turning on) needs a separate send or publish scope.

Steps

  1. 1

    How to read this article

    • Paths follow https://api.clomni.ai/v1: GET /v1/agents means https://api.clomni.ai/v1/agents. Paths have no workspace ID, because a token belongs to one workspace.
    • Every request carries the Authorization: Bearer clomni_pat_xxx header. How to get a token: Tokens and authentication in the Developer API.
    • Risk: low (no personal data), medium (reads customer data or changes internal data), high (sends to customers, deletes, bulk exports, changes live settings).
    • Every scope goes through review, in public apps too. More: Review: checking scopes and rejection reasons.
    • "Also grants": write and manage grant the read of the same resource. send, delete, publish, assign and run grant nothing.
    • When an endpoint lists several scopes, any one of them is enough. Without the scope the API answers 403 insufficient_scope with required_scopes in the body.
    • Every POST takes an Idempotency-Key header, so a repeated request is not run twice.
  2. 2

    Read campaigns (campaigns:read)

    Reads campaigns, their versions, results and the status of each recipient.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/campaign_results: List campaign results
    • GET /v1/campaign_results/{campaign_result_id}: Get a campaign's result
    • GET /v1/campaign_results/{campaign_result_id}/contacts: List a campaign's recipients and their status
    • GET /v1/campaigns: List campaigns
    • GET /v1/campaigns/{campaign_id}: Get a campaign
    • GET /v1/campaigns/{campaign_id}/versions: List a campaign's versions

    Example:

    curl "https://api.clomni.ai/v1/campaigns" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/campaign_results" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Edit campaign drafts (campaigns:write)

    Creates and edits campaign drafts, discards unpublished changes, restores an older version, deletes a campaign. Note: unless POST /v1/campaigns has enabled: false, the campaign is created active and campaigns:send is required too. In PATCH, enabled: true or scheduled_at also needs campaigns:send.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: campaigns:read.

    Endpoints:

    • POST /v1/campaigns: Create a campaign
    • PATCH /v1/campaigns/{campaign_id}: Update a campaign
    • DELETE /v1/campaigns/{campaign_id}: Delete a campaign
    • POST /v1/campaigns/{campaign_id}/revert: Discard unpublished changes
    • POST /v1/campaigns/{campaign_id}/versions/{version}/restore: Restore a campaign version

    Example:

    curl -X POST "https://api.clomni.ai/v1/campaigns" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "November sale", "inbox_id": 5, "enabled": false, "scheduled_at": 1794200000, "audience": [{"type": "Label", "id": 14}], "template_params": {"name": "november_sale", "language": "az", "category": "MARKETING", "processed_params": {"body": {"1": "15%"}}}}'
  4. 4

    Send campaigns (campaigns:send)

    Sends or schedules a campaign. Bulk messages go to customers, so it is high risk: in the review describe the volume and how consent is collected.

    • Risk: high.
    • Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
    • Also grants: nothing else.

    Endpoints:

    • POST /v1/campaigns/{campaign_id}/publish: Publish a campaign

    Example:

    curl -X POST "https://api.clomni.ai/v1/campaigns/9/publish" \
  -H "Authorization: Bearer clomni_pat_xxx"
  5. 5

    Read flows (flows:read)

    Reads flows, folders, versions, statistics, the step funnel and the contacts who went through a flow, and checks a flow for problems.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/flow_folders: List flow folders
    • GET /v1/flow_report: Get the flows report
    • GET /v1/flow_stats: Get statistics for all flows
    • GET /v1/flows: List flows
    • GET /v1/flows/{flow_id}: Get a flow
    • GET /v1/flows/{flow_id}/analytics: Get a flow's statistics
    • GET /v1/flows/{flow_id}/analytics/contacts: List contacts who went through a flow
    • GET /v1/flows/{flow_id}/analytics/funnel: Get a flow's step funnel
    • GET /v1/flows/{flow_id}/check: Check a flow for problems
    • GET /v1/flows/{flow_id}/versions: List a flow's versions
    • GET /v1/flows/{flow_id}/versions/{version_id}: Get a flow version

    Example:

    curl "https://api.clomni.ai/v1/flows" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/flows/31/check" \
  -H "Authorization: Bearer clomni_pat_xxx"
  6. 6

    Edit flow drafts (flows:write)

    Creates and edits flow drafts, copies flows, moves them to folders, manages folders. Sending status in the body counts as publishing and also needs flows:publish.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: flows:read.

    Endpoints:

    • POST /v1/flow_folders: Create a flow folder
    • PATCH /v1/flow_folders/{flow_folder_id}: Update a flow folder
    • DELETE /v1/flow_folders/{flow_folder_id}: Delete a flow folder
    • POST /v1/flows: Create a flow
    • PATCH /v1/flows/{flow_id}: Update a flow
    • POST /v1/flows/{flow_id}/copy: Copy a flow
    • PATCH /v1/flows/{flow_id}/move: Move a flow to a folder

    For the request body see the API reference on developer.clomni.ai.

  7. 7

    Publish flows (flows:publish)

    Turns a flow on or off, restores an older version, deletes a flow. An active flow writes to customers by itself, so it is high risk. There is no endpoint to start a flow in a given conversation: a trigger, an agent, the AI agent or the mobile app (Clomni.startFlow) starts it.

    • Risk: high.
    • Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
    • Also grants: nothing else.

    Endpoints:

    • DELETE /v1/flows/{flow_id}: Delete a flow
    • POST /v1/flows/{flow_id}/publish: Turn a flow on or off
    • POST /v1/flows/{flow_id}/versions/{version_id}/restore: Restore a flow version

    For the request body see the API reference on developer.clomni.ai.

  8. 8

    Read automations (automations:read)

    Reads automation rules: event, conditions, actions and whether the rule is active.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/automation_rules: List automation rules
    • GET /v1/automation_rules/{automation_rule_id}: Get an automation rule

    Example:

    curl "https://api.clomni.ai/v1/automation_rules" \
  -H "Authorization: Bearer clomni_pat_xxx"
  9. 9

    Edit automation drafts (automations:write)

    Creates and edits rules without activating them. Unless POST has active: false, the rule is created active and automations:publish is needed too. active: true in PATCH also needs automations:publish.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: automations:read.

    Endpoints:

    • POST /v1/automation_rules: Create an automation rule
    • PATCH /v1/automation_rules/{automation_rule_id}: Update an automation rule

    Example:

    curl -X POST "https://api.clomni.ai/v1/automation_rules" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP conversations to the sales team", "event_name": "conversation_created", "active": false, "conditions": [{"attribute_key": "customer_tier", "filter_operator": "equal_to", "values": ["gold"], "query_operator": null}], "actions": [{"action_name": "assign_team", "action_params": [3]}]}'
  10. 10

    Publish automations (automations:publish)

    Turns rules on and off (active in PATCH), copies a rule, deletes a rule. A copy of an active rule is active too, which is why copying needs this scope.

    • Risk: high.
    • Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
    • Also grants: nothing else.

    Endpoints:

    • DELETE /v1/automation_rules/{automation_rule_id}: Delete an automation rule
    • POST /v1/automation_rules/{automation_rule_id}/clone: Copy an automation rule

    Example:

    curl -X PATCH "https://api.clomni.ai/v1/automation_rules/6" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'
  11. 11

    Related articles

Document

Developer platform: guide v1.0 · 41 pages Open Download