Automations via API

The automation resources described in Automations — playbooks, AI agents, templates, and their supporting cast — are managed through a uniform API surface. This guide covers the resource model, then walks the flagship journey: author a playbook, publish it, and put an AI agent on it.

Base URL: https://medchatapp.com/automationapi · Scopes: read.automations / manage.automations (tasks use their own pair — see Tasks via API).

One shape, eight resources

These collections all expose the same endpoints:

aiAgents · playbooks · taskTemplates · dataTypes · knowledgeSets · customAiActions · analyzerConfigurations · tasks

The edit/version conventions apply everywhere: mutations bump the edit, x-aggregate-edit tells you the new one, and finalizing a version seals it.

Playbook anatomy

A playbook is a tree: Playbook → Procedures → Sections → Steps. Procedures and sections carry integer IDs unique within their parent; each declares where execution enters (initialStepId). Steps are polymorphic on a type discriminator — the current step types:

SayStep · CollectStep · AiTaskStep · PresentFileStep · TransferStep · ExecuteProcedureStep · EndInteractionStep

Steps connect through typed paths (DefaultPath, ConditionalPath, FailurePath). Playbooks also declare attributes (the data the playbook reads and writes) and grants (what an executing agent is allowed to do — readable via API, authored in the app UI).

Author and publish a playbook

1. Create it (procedures can be supplied inline or patched in later):

curl -X POST "https://medchatapp.com/automationapi/orgs/$ORG_ID/playbooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Appointment Follow-Up", "description": "Post-visit outreach procedure" }'

204 + Location + x-aggregate-edit: 1.

2. Build it out with JSON Patch — nested collections (procedures, sections, steps, attributes) are edited through the playbook's PATCH:

curl -X PATCH "https://medchatapp.com/automationapi/orgs/$ORG_ID/playbooks/$PLAYBOOK_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[ { "op": "add", "path": "/procedures/-", "value": { "name": "Outreach", "displayOrder": 1 } } ]'

Each patch returns the new edit in x-aggregate-edit.

3. Publish by sealing the active version. Pass the edit you believe is current — a 409 means someone else changed the playbook; re-read and retry:

curl -X POST "https://medchatapp.com/automationapi/orgs/$ORG_ID/playbooks/$PLAYBOOK_ID/finalizeVersion" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "lastEdit": 14 }'

4. Assign it to an AI agent. The reference can float on "latest" or pin a specific edit:

curl -X PATCH "https://medchatapp.com/automationapi/orgs/$ORG_ID/aiAgents/$AI_AGENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[ { "op": "replace", "path": "/assignedPlaybook", "value": { "playbookId": "'$PLAYBOOK_ID'", "playbookEdit": "latest" } } ]'

5. Confirm with the denormalized view: GET /orgs/{orgId}/aiAgents/assignedPlaybooksView.

📘

Playbooks are configured via API, executed by the platform. There is no "run playbook" endpoint — execution starts when an interaction reaches an AI agent assigned to the playbook.

Move configuration between environments

The YAML export/import round-trip works on all eight resource types:

curl "https://medchatapp.com/automationapi/orgs/$ORG_ID/playbooks/$PLAYBOOK_ID/export" \
  -H "Authorization: Bearer $TOKEN" -o playbook.yaml

curl -X POST "https://medchatapp.com/automationapi/orgs/$TARGET_ORG_ID/playbooks/import" \
  -H "Authorization: Bearer $TARGET_TOKEN" \
  -F "[email protected]"

Add ?edit= or ?asOf= to the export to ship a known-good historical state rather than the current one.

Impact analysis: the resource graph

Before changing a shared resource, see what depends on it:

curl "https://medchatapp.com/automationapi/orgs/$ORG_ID/resourceGraph?anchorType=Playbook&anchorId=$PLAYBOOK_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns nodes and edges for everything connected to the anchor — the AI agents assigned to it, the knowledge sets and custom actions they use, the phone numbers and widgets that route to them. Valid anchorType values include Playbook, AiAgent, TaskTemplate, KnowledgeSet, CustomAiAction, AnalyzerConfig, PhoneNumber, Widget — an invalid value returns 400 listing the valid set.