Automations

An automation is a trigger and a tree of steps. Send the same tree the designer saves.

Method	Path	What it does
GET	/api/v1/x/automations	Definitions in this firm, and whether each has a published version
GET	/api/v1/x/automations/{id}	One definition
POST	/api/v1/x/automations	Save a draft
PUT	/api/v1/x/automations/{id}	Replace the draft
POST	/api/v1/x/automations/{id}/publish	Publish a draft that the server grades as ordinary

Writes need workflow.definition.manage. name is required. The list accepts an optional status. A saved draft does not run. Updating a company does not fire it until it is published.

The body is a trigger and nodes. The trigger kind is entity, scheduled, manual, or webhook. An entity trigger needs a catalog entityType and an entityEvent. Every action key must be in the catalog. The config keys for each node type are nodeTypes on that same catalog.

Publish checks the tree again. A tree the server grades as high-impact, such as mail inside a loop or an HTTP call per item, stays a draft. The response is HTTP 409 and the body is { result: { id, code: "publish_blocked" }, catalogVersion }. That id is the draft. Publish that one in the designer, where a person can see the warning. Publishing a version that is already published is 409 not_a_draft.

This draft notifies the owner when Northwind Health’s thesis_fit is at least 7. It does not run until publish.

{
  "name": "Thesis fit follow-up",
  "trigger": { "kind": "entity", "entityType": "Company", "entityEvent": "OnUpdate" },
  "nodes": [
    {
      "id": "n-check",
      "type": "condition",
      "label": "Strong fit?",
      "config": { "field": "thesis_fit", "operator": ">=", "value": "7" },
      "branches": [
        {
          "id": "b-yes",
          "label": "Yes",
          "nodes": [
            {
              "id": "n-task",
              "type": "notification",
              "label": "Tell the deal team",
              "config": {
                "recipient": "entity_owner",
                "channels": "in-app",
                "message": "{{record.name}} scored {{record.thesis_fit}}."
              }
            }
          ]
        },
        { "id": "b-no", "label": "No", "nodes": [] }
      ]
    }
  ]
}

entityEvent is OnCreate, OnUpdate, OnStatusChange, or OnDelete. A condition branch is Yes and No. Config values are strings. Read nodeTypes on the catalog for the keys each type accepts, including durationAmount on a timer and field, operator, and value on a condition. A bad tree is 400 automation_invalid with errors[] of { path, code, message }, and nothing is written.

A node type is one of these. The catalog entry for that type lists its config. An unknown type is stored as an action.

type	What the designer stores
task, human_task, review	A person does the step
approval	An approval gate
notification, email	A notification
system_update	A field update
system_action, ai_prompt, data_get, data_get_many, data_create, data_upsert, data_update, data_update_many, data_relate, data_remove, data_remove_many, for_each, for_each_end	An action
out_of_system	A step outside Capsure
condition	A yes or no branch
split	Parallel branches
timer_wait	A wait for a duration
wait_for, event_wait	A wait for an event
switch_workflow	Hand off to another automation
end, converge	The end of a path

The inbound webhook for a published webhook trigger stays on the product path /api/v1/workflow/hooks/{webhookKey}, with the header X-Capsure-Webhook-Secret. This API does not mint that secret and does not offer a second webhook path.

There is no route that proxies an arbitrary HTTP call. A reusable connection to another system is a connector.