The push-run endpoint and runs_create MCP tool let you upload code and trigger an immediate run on any integration — webhook, schedule, or manual — in a single API call.

push-run: On-Demand Runs for Any Trigger Type

The push-run endpoint and the runs_create MCP tool work with all trigger types — webhook, schedule, and manual. You can upload code and trigger an immediate run on any integration in a single API call, regardless of how that integration is normally triggered.

Overview

Capability	`push-run` endpoint	`runs_create` MCP tool
Trigger type support	All (`webhook`, `schedule`, `manual`)	All (`webhook`, `schedule`, `manual`)
Upload new code	Yes (atomic)	No — runs existing deployed code
Best for	Development, iterative testing	CI/CD, ad-hoc production runs

This flexibility unlocks key workflows: testing schedule integrations immediately without waiting for the next cron window, running smoke tests in CI/CD pipelines, and triggering event-driven integrations with controlled payloads.

push-run Endpoint

The push-run endpoint atomically uploads a set of files and immediately triggers a run — all in a single HTTP request.

Request

POST https://app.headlessops.ai/api/integrations/{name}/push-run
Authorization: Bearer iter_YOUR_KEY
Content-Type: application/json

{
  "files": {
    "integration.yaml": "...",
    "step_one.ts": "..."
  },
  "payload": {
    "key": "value"
  }
}

Field	Required	Description
`files`	Yes	Map of filename → file content strings
`payload`	No	JSON payload passed as `trigger.body` to the run

Response

{
  "runId": "run_abc123",
  "status": "PENDING"
}

Use the runId to poll the Runs API for status and output.

Examples by Trigger Type

Webhook Integration

curl -X POST https://app.headlessops.ai/api/integrations/my-webhook-integration/push-run \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "integration.yaml": "name: my-webhook-integration\ndescription: Process incoming events\ntrigger:\n  type: webhook\n  method: POST\nsteps:\n  - id: process\n    name: Process\n    description: Processes the event\n    file: process.ts",
      "process.ts": "export async function run(input: Record<string, any>, ctx: StepContext) {\n    ctx.log(\"processing\", input);\n    return { ok: true };\n}"
    },
    "payload": { "event": "record.created", "id": "rec_123" }
  }'

Schedule Integration

curl -X POST https://app.headlessops.ai/api/integrations/my-daily-report/push-run \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "integration.yaml": "name: my-daily-report\ndescription: Daily report\ntrigger:\n  type: schedule\n  cron: 0 9 * * 1-5\nsteps:\n  - id: generate\n    name: Generate\n    description: Generates the report\n    file: generate.ts",
      "generate.ts": "export async function run(input: Record<string, any>, ctx: StepContext) {\n    ctx.log(\"generating report\");\n    return { rows: 0 };\n}"
    },
    "payload": { "dry_run": true }
  }'

Manual Integration

curl -X POST https://app.headlessops.ai/api/integrations/my-manual-task/push-run \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "integration.yaml": "name: my-manual-task\ndescription: Ad-hoc task\ntrigger:\n  type: manual\nsteps:\n  - id: run_task\n    name: Run Task\n    description: Runs the task\n    file: run_task.ts",
      "run_task.ts": "export async function run(input: Record<string, any>, ctx: StepContext) {\n    return { done: true };\n}"
    },
    "payload": { "target_id": "123" }
  }'

runs_create MCP Tool

The runs_create MCP tool triggers an immediate run against an existing (already deployed) integration — without uploading new code.

{
  "tool": "runs_create",
  "arguments": {
    "integrationName": "my-webhook-integration",
    "payload": {
      "event": "record.created",
      "id": "rec_456"
    }
  }
}

This works regardless of whether the integration uses a webhook, schedule, or manual trigger.

Choosing Between runs_create and push-run

Use Case	Recommended Tool
Trigger a run on an existing integration (no code change)	`runs_create`
Upload new code and run immediately (atomic)	`push-run` endpoint
Trigger a run in CI/CD after a separate deploy step	`runs_create`
Develop and test a new or modified integration script	`push-run` endpoint

Key Use Cases

Immediate Testing of Schedule Integrations

Schedule integrations typically run on a cron window — testing them previously meant waiting for the next scheduled execution. With push-run, you can trigger an immediate test run with a controlled payload at any time:

curl -X POST https://app.headlessops.ai/api/integrations/my-daily-sync/push-run \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": { ... },
    "payload": { "dry_run": true }
  }'

This is especially useful when iterating on schedule integration logic without waiting hours between test cycles.

Smoke Testing in CI/CD Pipelines

After deploying an integration, trigger a smoke-test run automatically from your pipeline — regardless of the integration's trigger type:

# CI pipeline example
- name: Smoke test integration
  run: |
    curl -X POST $HEADLESSOPS_URL/api/integrations/$INTEGRATION_NAME/push-run \
      -H "Authorization: Bearer $HEADLESSOPS_API_KEY" \
      -H "Content-Type: application/json" \
      -d "{\"files\": $FILES_JSON, \"payload\": {\"smoke_test\": true}}"

Triggering Webhook Integrations with Test Payloads

Use push-run to send a controlled event payload to a webhook integration for local development or QA without configuring an external webhook source:

curl -X POST https://app.headlessops.ai/api/integrations/crm-event-handler/push-run \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": { ... },
    "payload": {
      "event": "contact.updated",
      "contact_id": "cid_test123",
      "changes": ["email", "name"]
    }
  }'

Trigger Types — webhook, schedule, and manual trigger reference
Auto-Sync Trigger Settings — automatically apply YAML trigger changes on push
Runs API — poll run status and retrieve output after triggering
MCP Tools Reference — full MCP toolchain documentation

push-run — On-Demand Runs for Any Trigger Type