Create, edit, and publish automations

This walkthrough creates a draft that sends a guide link when a contact comments with a keyword. All IDs, timestamps, copy, and URLs below are illustrative. Replace the account ID with one returned by List accounts. Use an API key with the required scopes.

1. Create a draft

Send this body to POST /api/v1/automations with Authorization: Bearer <API_KEY> and Content-Type: application/json. Creation requires automations:write. The name allows 1 to 120 Unicode scalars, without surrounding whitespace or control characters.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "name": "Guide request",
  "status": "draft",
  "configuration": {
    "contact_filter": "anyone",
    "trigger": {
      "type": "comment",
      "publication": {
        "mode": "all"
      },
      "keywords": {
        "mode": "specific",
        "match_mode": "whole_word",
        "values": [
          "guide"
        ]
      }
    },
    "opening": {
      "public_reply": {
        "enabled": false
      },
      "direct_message": {
        "delay_seconds": 0,
        "message": {
          "text": "Here is the guide you asked for.",
          "buttons": [
            {
              "type": "url",
              "title": "Open the guide",
              "url": "https://example.com/guide"
            }
          ]
        }
      }
    },
    "follow_up": null,
    "extras": {
      "cooldown": {
        "mode": "none"
      }
    }
  }
}

Response: HTTP 201

{
  "automation": {
    "id": "00000000-0000-4000-8000-000000000002",
    "account_id": "00000000-0000-4000-8000-000000000001",
    "name": "Guide request",
    "status": "draft",
    "has_unpublished_changes": false,
    "draft_updated_at": null,
    "created_at": "2026-09-01T12:00:00.000000Z",
    "updated_at": "2026-09-01T12:00:00.000000Z",
    "trigger_type": "comment",
    "configuration": {
      "contact_filter": "anyone",
      "trigger": {
        "type": "comment",
        "publication": {
          "mode": "all"
        },
        "keywords": {
          "mode": "specific",
          "match_mode": "whole_word",
          "values": [
            "guide"
          ]
        }
      },
      "opening": {
        "public_reply": {
          "enabled": false
        },
        "direct_message": {
          "delay_seconds": 0,
          "message": {
            "text": "Here is the guide you asked for.",
            "buttons": [
              {
                "type": "url",
                "title": "Open the guide",
                "url": "https://example.com/guide"
              }
            ]
          }
        }
      },
      "follow_up": null,
      "extras": {
        "cooldown": {
          "mode": "none"
        }
      }
    },
    "authoring_compatibility": "public_v1"
  }
}

The envelope is automation, not data. A successful write stores the automation; it does not prove that a message was sent. Save id and the exact updated_at string. Do not round or reformat timestamps.

2. Read before editing

Call GET /api/v1/automations/{automationId}?account_id=... with automations:read. HTTP 200 returns the same complete envelope shown above. Always start an edit from a fresh read.

3. Rename or replace configuration

For a rename, send this body to PATCH /api/v1/automations/{automationId}. Replace the example timestamp with the value from your fresh read.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "expected_updated_at": "2026-09-01T12:00:00.000000Z",
  "name": "Updated guide request"
}

To change behavior, also send the entire modified configuration object. It replaces the stored configuration; nested objects and arrays are not merged. You can send the name, the configuration, or both, but not status. HTTP 200 returns the full automation envelope, including the new updated_at. On a live automation, inspect has_unpublished_changes. When true, the returned name and configuration describe the draft, while the previously published version continues running. draft_updated_at is informational; concurrency always uses updated_at.

4. Publish or pause

After reviewing the stored draft, send the following body to POST /api/v1/automations/{automationId}/activate. Use the latest version from a new read. Activation requires automations:activate.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "expected_updated_at": "2026-09-01T12:00:00.000000Z"
}

HTTP 200 returns the complete envelope with status: "live" and published configuration. To pause new trigger processing, send the same body shape with a fresh version to POST /api/v1/automations/{automationId}/deactivate; HTTP 200 returns status: "paused". Creating with status: "live" publishes immediately and also requires activation scope.

Recover without duplicate writes

409 with api_automation_version_conflict: read again, reconcile the newer changes, and rebuild the update.
422 with api_automation_invalid_configuration: inspect error.details.issues and fix the reported paths.
api_automation_committed_response_unavailable with committed: true and retryable: false: the write committed. Read back, or list after creation, before deciding what to do.
An uncertain create outcome must not be blindly retried: creation is not idempotent.

Example conflict response

HTTP 409.

{
  "error": {
    "code": "api_automation_version_conflict",
    "message": "The automation changed after the supplied version."
  }
}

Use the error guide for the response envelope, correlation IDs, authentication failures, and retry decisions. Delete archives the automation and returns HTTP 204 with no body; do not try to parse it as JSON.

Overview

Getting started

Guides

Webhooks

Create, edit, and publish automations

1. Create a draft

Response: HTTP 201

2. Read before editing

3. Rename or replace configuration

4. Publish or pause

Recover without duplicate writes

Example conflict response

​1. Create a draft

​Response: HTTP 201

​2. Read before editing

​3. Rename or replace configuration

​4. Publish or pause

​Recover without duplicate writes

​Example conflict response

1. Create a draft

Response: HTTP 201

2. Read before editing

3. Rename or replace configuration

4. Publish or pause

Recover without duplicate writes

Example conflict response