Workflow Webhook API

Trigger workflows programmatically via HTTP requests.

Overview

The Workflow API allows you to trigger workflows from external systems, automation tools, or custom integrations. Each workflow has a unique webhook URL that accepts POST requests to start a new run.

Endpoint

POST /api/v1/team/{slug}/workflow/{workflowId}

Use GET on the same endpoint to retrieve the workflow schema and available input fields.

Authentication

Include your team API key in the request headers:

x-api-key: your-team-api-key

Find your team API key in Team Settings → API. You can also use a personal API key (prefixed with mk_) if you are a member of the team.

Request Body

The request body format depends on the workflow's first step:

If first step is a Form

Send JSON with field names matching the form input names:

{
  "email": "user@example.com",
  "name": "John Doe",
  "priority": "high"
}

If first step is NOT a Form

Send any JSON payload. It will be injected as context for the first step:

{
  "event": "new_order",
  "customer_id": "12345",
  "items": ["product_a", "product_b"]
}

Optional Fields

{
  // Your payload fields...

  // Run a specific workflow variant
  "variantId": "variant-uuid",

  // Run as a specific team member
  "actorUserId": "user-uuid"
}

Response

Success (200)

{
  "runId": "abc123xyz",
  "workflowId": "workflow-uuid",
  "status": "queued"
}

Error Codes

Status	Description
400	Invalid JSON or workflow is archived
401	Missing or invalid API key
403	API key user is not a team member
404	Team or workflow not found

Check Run Status

After triggering a workflow, check its status using the run ID:

GET /api/v1/team/{slug}/workflow/{workflowId}/run/{runId}

Returns full run details including status, outputs, step results, and analytics.

Example

Trigger a workflow with cURL

curl -X POST \
  https://magpai.app/api/v1/team/your-team/workflow/workflow-id \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"field1": "value1", "field2": "value2"}'

Check run status

curl https://magpai.app/api/v1/team/your-team/workflow/workflow-id/run/run-id \
  -H "x-api-key: your-api-key"

Get Workflow Schema

Retrieve the workflow's input schema before triggering:

GET /api/v1/team/{slug}/workflow/{workflowId}

// Response
{
  "id": "workflow-uuid",
  "name": "My Workflow",
  "description": "Workflow description",
  "inputSchema": {
    "type": "form",
    "fields": [
      {
        "name": "email",
        "type": "text",
        "required": true,
        "description": "Customer email"
      }
    ]
  },
  "variants": [
    { "id": "variant-1", "name": "Production" }
  ]
}