Automations and playbooks

Three pieces compose every repeatable process on a pod:

Keep them apart: an automation should not hold the work itself, and a playbook should not decide when it runs.

PlaybooksCopy Anchor Link

A playbook needs a name and a goalTemplate. It can also declare:

• params: inputs asked for when it runs, referenced in the goal as {name} (for example Analyze competitors for {market}). An undeclared name, or {{name}}, is refused.
• stages: ordered steps, each with a key, a name and a category (backlog, planned, started, paused, completed or canceled), and optionally a gate where a person must say yes.
• criteria: binary statements every run is graded against.
• a subject kind: the kind of record it runs on, such as a company or a lead.

Create oneCopy Anchor Link

• Your agent: ask for it. synap_create_playbook files it as a proposal you approve. An agent can also turn a session that went well into a playbook with synap_promote_session_to_playbook.
• The API: POST /api/hub/playbooks with name, goalTemplate and workspaceId, plus any of description, stages, params, criteria and subjectProfile (for example { "profileSlug": "company" }). See Playbooks in the Hub REST API.
• A template: workspaces from the marketplace bring their own playbooks.

Run oneCopy Anchor Link

synap playbook run "<name or id>" --subject <entityId> --param market=Europe

Your agent runs one with synap_run_playbook, and the API with POST /api/hub/playbooks/{id}/run (subjectId, params, workspaceId). A run creates a session and hands it to the playbook's executor. It can come back:

Let a goal run on its ownCopy Anchor Link

A playbook can declare workers: what starts it by itself. Your agent turns one on for a goal with synap_enable_worker, named by its trigger: schedule:<cron> (for example schedule:0 9 * * 1, every Monday at 09:00 UTC), enters_status:<status> (when a record enters that status), count:<status> (when enough records are in it) or created. Its mode says whether each run asks you first (propose, the default) or just runs (run).

AutomationsCopy Anchor Link

TriggersCopy Anchor Link

Match events in the .completed phase: it fires for every change that lands, whether it ran directly or was approved. The .validated phase fires only for changes that went through a proposal.

Filters compare values exactly, or with $eq, $ne, $in, $gt, $gte, $lt and $lte. A record's properties are flat in the event data: filter on score, not properties.score.

The flowCopy Anchor Link

The flow is a set of nodes joined by edges. It starts at its trigger node. The steps you will use most:

Text in a step can use the trigger and earlier steps: {{trigger.payload.subjectId}} (the record the event is about), {{trigger.payload.data.title}}, {{steps.<nodeId>.output}}. The full reference, with every step type and its fields, is served by your pod:

synap automation schema           # or GET /api/hub/automations/schema

Create and manage oneCopy Anchor Link

• Your agent: synap_create_automation. It is always a proposal; once approved, the automation is live. An agent's automation must also carry a short contract of what it reads, stores and does (metadata.dataContract, below), or it is refused.
• The API: POST /api/hub/automations/create with name, triggerType, triggerConfig, flowDefinition, workspaceId and status (draft by default, or active). See Automations in the Hub REST API.

synap automation list
synap automation describe <id>
synap automation enable <id>      # make it live
synap automation disable <id>     # pause it

To run one now, outside its trigger: synap_trigger_automation for an agent, or POST /api/hub/automations/{automationId}/trigger. A run is not a proposal, but every write its steps make goes through the same governance as any other write.

Example: research every new companyCopy Anchor Link

This puts the three pieces together: when a company is added to your pod, start a research session on it, in which an agent can use the search capability you installed.

synap capability add
synap capability list

curl -X POST https://pod.example.com/api/hub/playbooks \
  -H "Authorization: Bearer $SYNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "<workspace id>",
    "name": "Research a company",
    "goalTemplate": "Research this company on the web and record what it does, who runs it and recent news",
    "subjectProfile": { "profileSlug": "company" }
  }'

curl -X POST https://pod.example.com/api/hub/automations/create \
  -H "Authorization: Bearer $SYNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d @research-new-companies.json

{
  "workspaceId": "<workspace id>",
  "name": "Research new companies",
  "triggerType": "event",
  "triggerConfig": {
    "eventPattern": "entity.create.completed",
    "filters": { "profileSlug": "company" }
  },
  "status": "active",
  "flowDefinition": {
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "position": { "x": 0, "y": 0 },
        "data": {
          "triggerType": "event",
          "label": "A company is added",
          "config": { "eventPattern": "entity.create.completed" }
        }
      },
      {
        "id": "run-1",
        "type": "playbook_run",
        "position": { "x": 0, "y": 200 },
        "data": { "label": "Research it", "playbookName": "Research a company" }
      }
    ],
    "edges": [{ "id": "e1", "source": "trigger-1", "target": "run-1" }]
  },
  "metadata": {
    "dataContract": {
      "version": 1,
      "mode": "react",
      "gets": [
        {
          "id": "new-company",
          "label": "A company is added to the pod",
          "nodeIds": ["trigger-1"],
          "origin": "synap",
          "event": "entity.create.completed"
        }
      ],
      "stores": [],
      "reacts": [
        { "id": "research", "label": "Start a research session on it", "nodeIds": ["run-1"], "kind": "process" }
      ]
    }
  }
}

To call the search verb directly from the flow instead of leaving it to the agent, add a capability step with verbId set to the verb's name and an inputMapping such as { "query": "{{trigger.payload.data.title}}" }.

RelatedCopy Anchor Link

• Capabilities
• Validation policy
• Event catalog
• Webhooks, for the pod to call your URL when something changes