API documentation

zapier integration & inbound API

The chaos trace API lets you push automation data from any tool, receive governance alerts via webhooks, and integrate with Zapier. All endpoints return JSON. The Zapier integration uses OAuth 2.0 — if you're connecting through Zapier, authentication is handled automatically.

authentication

API key

For direct API access, include your API key in the X-API-Key header. API keys are scoped to a single tenant and can be created in your chaos trace settings.

curl -H "X-API-Key: ct_your_key_here" \
  https://api.chaostrace.com/inbound/automations

OAuth 2.0 (Zapier)

The Zapier integration authenticates via OAuth 2.0 authorization code flow. Zapier handles the token exchange automatically — no manual setup required.

Authorization: Bearer <access_token>

base URL

https://api.chaostrace.com

All endpoint paths below are relative to this base URL.

errors

The API uses standard HTTP status codes. Error responses include a detail field with a human-readable message.

code	meaning
400	bad request — missing or invalid parameters
401	unauthorized — invalid or missing credentials
413	payload too large — maximum request size is 10 MB
500	server error — something broke on our end

connection test

GET/zapier/me

Test your connection and get the account label. Zapier calls this automatically to verify credentials.

response

{
  "name": "chaos trace",
  "client_id": "your_client_id"
}

governance alerts

GET/zapier/alerts

Fetch recent governance alerts. Used as the Zapier trigger polling endpoint and for sample data in the Zap editor.

response

[
  {
    "id": 42,
    "type": "high_risk_field",
    "severity": "warning",
    "title": "3 automations writing to Contact.Email across 2 systems",
    "description": "3 automations write to this field across 2 system(s).",
    "system": "salesforce",
    "object": "Contact",
    "fields": ["Email"],
    "metadata": { "risk_score": 12 },
    "created_at": "2026-04-09T18:30:00Z"
  }
]

alert types

high_risk_field — a field has a high conflict risk score

cross_system_write — multiple systems writing the same field

yoyo_risk — a field is read and written in the same flow chain

unowned_automation — an active automation with no clear owner

webhooks (REST hooks)

chaos trace pushes governance alerts to your webhook URL in real time. Zapier manages these subscriptions automatically when you turn a Zap on or off. You can also manage them directly via the API.

POST/zapier/hooks

Subscribe a webhook URL to receive governance alerts.

parameter	type	required	description
hookUrl	string	yes	The URL to receive webhook payloads
event	string	no	Event type to subscribe to. Default: governance_alert

request body

{
  "hookUrl": "https://hooks.zapier.com/hooks/catch/123/abc",
  "event": "governance_alert"
}

response

{
  "id": 7
}

DELETE/zapier/hooks/{hook_id}

Unsubscribe a webhook. Zapier calls this when a Zap is turned off.

response

{
  "status": "unsubscribed"
}

webhook payload

When a governance alert fires, chaos trace sends a POST to your webhook URL with the alert object as the body. The payload matches the alert schema from /zapier/alerts above.

If your endpoint returns 410 Gone, chaos trace automatically deactivates the subscription.

push automations

POST/inbound/automations

Push one or more automations from any external system. Use this to send automation configs from tools chaos trace doesn't natively connect to.

parameter	type	required	description
name	string	yes	Automation name (or flow_name)
source_system	string	no	Source platform, e.g. "zapier", "clay", "manual". Default: manual
status	string	no	Active, inactive, draft, etc.
trigger_type	string	no	What fires the automation
description	string	no	Human-readable description
url	string	no	Link back to the automation in the source system
steps	array	no	Inline step definitions (also accepts actions or field_mappings keys)
mode	string	no	Upload mode: create, update (default), replace, or append

single automation

{
  "name": "New Lead → Slack Notification",
  "source_system": "zapier",
  "status": "active",
  "trigger_type": "new_record",
  "description": "Posts to #sales when a lead is created in HubSpot",
  "steps": [
    { "action": "filter", "field": "Lead.Status", "value": "New" },
    { "action": "send_message", "channel": "#sales" }
  ]
}

batch upload

{
  "source_system": "clay",
  "mode": "update",
  "automations": [
    { "name": "Enrich new contacts", "status": "active", ... },
    { "name": "Score inbound leads", "status": "active", ... }
  ]
}

response

{
  "received": 2,
  "saved": 2,
  "batch_id": 15,
  "source_id": 3,
  "mode": "update",
  "links": [],
  "results": [
    {
      "system_id": "clay-automation-enrich-new-contacts",
      "flow_name": "Enrich new contacts",
      "steps_count": 4,
      "changed": true,
      "change_type": "new"
    }
  ]
}

upload modes

update — upsert automations, keep existing ones not in this batch (default)

create — only add new automations, skip any that already exist

replace — delete all existing automations from this source, then insert

append — add new automations, skip existing ones without error

Uploads with 20+ automations are processed in the background. You'll receive an email when processing is complete.

integration events

POST/zapier/events

Send an integration event from a Zap. Events are stored for the authenticated account.

parameter	type	required	description
source_system	string	yes	System the event originated from
event_type	string	yes	Type of event, e.g. "field_change", "deployment"
title	string	yes	Short title for the event
description	string	no	Longer description
metadata	object	no	Arbitrary key-value data

request body

{
  "source_system": "salesforce",
  "event_type": "deployment",
  "title": "Flow deployed: Lead Assignment v3",
  "description": "Updated assignment rules for EMEA region",
  "metadata": { "deployed_by": "jane@acme.com" }
}

response

{
  "id": 91,
  "source_system": "salesforce",
  "event_type": "deployment",
  "title": "Flow deployed: Lead Assignment v3",
  "received_at": "2026-04-09T18:30:00Z"
}

CSV upload

POST/inbound/upload-csv

Upload a CSV file of automations. Column names are flexible — chaos trace maps common variations automatically.

accepted columns

name — automation name (also accepts: flow_name, automation_name, title, workflow_name)

source_system — platform (also accepts: system, source, platform, tool)

status — active/inactive (also accepts: state, enabled, is_active)

trigger_type — trigger (also accepts: event, event_type)

steps — flow steps as text (also accepts: actions, what it does)

fields — fields touched (also accepts: fields_touched, field list)

description — notes (also accepts: desc, summary)

url — link to automation (also accepts: automation_url, link)

request

curl -X POST \
  -H "X-API-Key: ct_your_key_here" \
  -F "file=@automations.csv" \
  -F "source_system=manual" \
  https://api.chaostrace.com/inbound/upload-csv

limits

Maximum request body size is 10 MB. Large batch uploads (20+ items) are processed asynchronously. There are no per-minute rate limits.

← back to home