Integrations

An integration is the core unit of automation in HeadlessOps. It is a named, versioned package consisting of:

• integration.yaml — the manifest that defines the trigger, steps, and routing
• TypeScript step files — one .ts file per step (step_id.ts)
• Optional files — knowledge_base.md, fix_log.md, helpers, config

Lifecycle

create → push files → deploy → trigger → run → logs

1. Create an integration (name + optional description)
2. Push files — upload integration.yaml and step .ts files
3. Deploy — snapshot files as a versioned deployment
4. Trigger — webhook event, cron schedule, or manual API call
5. Run — the platform executes steps sequentially (or by routing rules)
6. Logs — every step emits structured logs visible in the run history

Trigger Types

Activation

Integrations can be active or inactive. Inactive integrations do not process webhook events or scheduled runs.

# Activate
curl -X POST https://app.headlessops.ai/api/integrations/my-integration/activate \
  -H "Authorization: Bearer iter_YOUR_KEY"

# Deactivate
curl -X POST https://app.headlessops.ai/api/integrations/my-integration/deactivate \
  -H "Authorization: Bearer iter_YOUR_KEY"

Archiving and Deletion

Integrations must be archived before they can be permanently deleted — this prevents accidental data loss. In the web UI, use the "Show archived" filter on the integrations list to view archived items, and the bulk-action bar to archive, unarchive, or delete multiple integrations at once (select rows via the checkboxes in the table).

# Archive (required before deletion)
curl -X POST https://app.headlessops.ai/api/integrations/my-integration/archive \
  -H "Authorization: Bearer iter_YOUR_KEY"

# Delete (only allowed once archived)
curl -X DELETE https://app.headlessops.ai/api/integrations/my-integration \
  -H "Authorization: Bearer iter_YOUR_KEY"

See the Integrations API reference for the full archive/unarchive/bulk-archive/bulk-delete endpoints.

Time Saved Metrics

HeadlessOps automatically tracks how much manual effort your integrations replace. The secondsSaved field on each integration estimates the time saved per run. The platform calculates total time saved as:

Time Saved (30d) = runs in last 30 days × secondsSaved

You can set secondsSaved when creating or updating an integration via the API, MCP, or web UI. The integrations list displays time saved and supports sorting by it alongside run counts.

# Set seconds saved on an integration
curl -X PUT https://app.headlessops.ai/api/integrations/my-integration \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "secondsSaved": 300 }'  # 5 minutes saved per run

Run Activity Chart

The integrations list includes a Run Activity chart — a filterable line chart showing run volume over time. An aggregated run count appears in the top-right corner of the chart. Use the date range picker to filter the chart to specific time windows.

Labels

Labels help organize integrations and enforce access control. You can filter integrations by label in the web UI and API:

# Set labels on an integration
curl -X PUT https://app.headlessops.ai/api/integrations/my-integration/labels \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "labels": ["crm", "billing", "production"] }'

# Filter by label
curl "https://app.headlessops.ai/api/integrations?label=production" \
  -H "Authorization: Bearer iter_YOUR_KEY"

The integrations list also supports sorting by time saved, run count, and other metrics. In the web UI, use the sort dropdown and column headers to reorder. Via the API, pass sortBy:

# Sort by time saved descending
curl "https://app.headlessops.ai/api/integrations?sortBy=timeSaved&sortOrder=desc" \
  -H "Authorization: Bearer iter_YOUR_KEY"

Cloning

curl -X POST https://app.headlessops.ai/api/integrations/my-integration/clone \
  -H "Authorization: Bearer iter_YOUR_KEY"

Returns a new integration object with a -copy suffix on the name.