Beta

Workflow Run

⚠️

Beta API

This endpoint is in beta and may change before general availability. Feedback is welcome — contact your trumpet account team.

POST/v1/workflows/{id}/run

Starts an asynchronous run of the workflow identified by id. Returns immediately with a run identifier; the result is delivered later to the configured webhook URL for this workflow.

Authentication

This endpoint requires a valid API key. Pass it via the Authorization header:

Authorization: Bearer trpt_a1b2c3_your_key_here

Path Parameters

Body Parameters

Parameter	Type	Required	Description
`id`	string	Required	The workflow ID to run. Each workflow you create in the trumpet app has a unique ID — see Finding your workflow ID below. There is no API endpoint to list workflows.

Finding your workflow ID

Workflow IDs are not available via the API. Create a workflow in the trumpet app and use its ID when calling this endpoint — every workflow you create is assigned a unique ID.

💡

No list endpoint

There is currently no GET /workflows endpoint. You need to know the workflow ID before calling this API.

Request Body

Body Parameters

Parameter	Type	Required	Description
`data`	object	Required	Arbitrary payload passed to the workflow run. Must be a JSON object; shape is not validated beyond that, since it varies per workflow.

Async Behavior

This is an asynchronous endpoint — do not poll for completion. When you trigger a run, the API responds immediately with a 202 Accepted and a runId. When the workflow finishes, trumpet POSTs the result to the webhook URL configured for that workflow.

Example Request

cURL

curl -X POST https://trumpet.app/api/v1/workflows/wf_789/run \
  -H "Authorization: Bearer trpt_a1b2c3_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "podId": "pod_123",
      "stepId": "step_456",
      "notes": "triggered manually from CRM"
    }
  }'

JavaScript

const response = await fetch(
  "https://trumpet.app/api/v1/workflows/wf_789/run",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TRUMPET_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      data: {
        podId: "pod_123",
        stepId: "step_456",
        notes: "triggered manually from CRM",
      },
    }),
  },
);

const { runId, workflowId, status, createdAt } = await response.json();

Python

import os, requests

response = requests.post(
    "https://trumpet.app/api/v1/workflows/wf_789/run",
    headers={
        "Authorization": f"Bearer {os.environ['TRUMPET_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "data": {
            "podId": "pod_123",
            "stepId": "step_456",
            "notes": "triggered manually from CRM",
        },
    },
)

data = response.json()

Accepted Response

Returns 202 Accepted when the run is queued:

202 Accepted

{
  "runId": "run_8f3e1c2a",
  "workflowId": "wf_789",
  "status": "pending",
  "createdAt": "2026-07-14T10:30:00Z"
}

Webhook Payload

When the run completes, trumpet POSTs the following payload to your workflow's configured webhook URL. The runId matches the one returned in the accepted response.

Succeeded

{
  "runId": "run_8f3e1c2a",
  "workflowId": "wf_789",
  "status": "succeeded",
  "data": {
    "podId": "pod_123",
    "stepId": "step_456",
    "notes": "triggered manually from CRM"
  },
  "result": {
    "actionsCompleted": 3
  },
  "completedAt": "2026-07-14T10:30:45Z"
}

Failed

{
  "runId": "run_8f3e1c2a",
  "workflowId": "wf_789",
  "status": "failed",
  "data": {
    "podId": "pod_123",
    "stepId": "step_456"
  },
  "error": {
    "message": "Action step_456 timed out",
    "code": "ACTION_TIMEOUT"
  },
  "completedAt": "2026-07-14T10:30:45Z"
}

Error Responses

Status	Cause
`400`	Invalid request body — e.g. `data` is missing or not a JSON object.
`404`	No workflow exists with the given `id`.
`409`	Workflow is disabled and cannot be run.

Error body

{
  "error": "validation_error",
  "message": "data must be a JSON object"
}

💡

OpenAPI specification

The full OpenAPI 3.0 spec for this endpoint is available at /openapi/workflow-run-openapi.json.