The Run endpoint lets you execute any workflow you own by passing only the input values. The server loads the saved workflow, injects your inputs, and executes the full pipeline. This is how you turn visual workflows into programmable APIs.

Describe Inputs

GET /api/v1/workflows/{id}/run

Returns the input schema for a workflow so you know what to pass.

Request

curl https://www.wireflow.ai/api/v1/workflows/YOUR_WORKFLOW_ID/run \
  -H "Authorization: Bearer sk-your-api-key"

Response 200 OK

{
  "data": {
    "workflowId": "cm1abc123",
    "workflowName": "Video Analyzer",
    "inputs": [
      {
        "nodeId": "node-tiktok",
        "label": "TikTok Import",
        "type": "url",
        "required": true,
        "description": "TikTok video URL"
      },
      {
        "nodeId": "node-theme",
        "label": "Analysis Theme",
        "type": "text",
        "required": false,
        "default": "Break down the visual storytelling techniques"
      }
    ],
    "endpoint": "/api/v1/workflows/cm1abc123/run",
    "method": "POST",
    "example": {
      "inputs": {
        "node-tiktok": "<url>",
        "node-theme": "Break down the visual storytelling techniques"
      }
    }
  }
}

Input Types

Type	Description	Nodes
text	Free-form text input	Text Input, Prompt nodes
image	HTTPS image URL	Image Input, Media Upload
url	Video/media URL	TikTok Import, Instagram Import, YouTube Clipper
number	Numeric value	Number, Seed nodes
boolean	True/false toggle	Toggle nodes
select	Choice from options	List Selector nodes

How Inputs Are Detected

1. If the workflow has published input settings (exposedInputs), only those nodes are exposed
2. Otherwise, all input-category nodes and utility import nodes without incoming connections are automatically exposed

Run a Workflow

POST /api/v1/workflows/{id}/run

Executes the workflow with your input values. Returns 202 with an execution ID for polling.

Request Body

Field	Type	Required	Description
inputs	object	No	Map of nodeId → value. Omit to run with saved defaults.

Request

curl -X POST https://www.wireflow.ai/api/v1/workflows/cm1abc123/run \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "node-tiktok": "https://www.tiktok.com/t/ZP8bar3Dk/"
    }
  }'

Response 202 Accepted

{
  "data": {
    "executionId": "exec_789",
    "status": "running",
    "poll": "/api/v1/workflows/executions/exec_789/poll"
  }
}

The Location header also points to the poll URL.

Poll for results using the Poll endpoint:

curl https://www.wireflow.ai/api/v1/workflows/executions/exec_789/poll \
  -H "Authorization: Bearer sk-your-api-key"

Complete Example

Build a workflow in the editor, then call it from code:

const WIREFLOW_API = 'https://www.wireflow.ai/api/v1';
const API_KEY = process.env.WIREFLOW_API_KEY;

// 1. Discover the inputs
const schema = await fetch(`${WIREFLOW_API}/workflows/${workflowId}/run`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
}).then((r) => r.json());

console.log('Available inputs:', schema.data.inputs);

// 2. Run the workflow
const { data } = await fetch(`${WIREFLOW_API}/workflows/${workflowId}/run`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    inputs: {
      'node-tiktok': 'https://www.tiktok.com/t/ZP8bar3Dk/',
    },
  }),
}).then((r) => r.json());

// 3. Poll until complete
let result;
while (true) {
  const poll = await fetch(`${WIREFLOW_API}${data.poll}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }).then((r) => r.json());

  if (poll.status === 'COMPLETED') {
    result = poll;
    break;
  }
  if (poll.status === 'FAILED') throw new Error(poll.error);

  await new Promise((r) => setTimeout(r, 2000));
}

console.log('Results:', result.nodeResults);

Credits

The API key owner's credits are charged for each AI model node that runs. Text input and utility nodes are free. Use the credit pre-check error to handle insufficient balance gracefully.

Comparison with Execute

	/run	/execute
Input	Just the values you want to override	Full nodes + edges arrays
Workflow source	Loaded from saved state	Sent in request body
Best for	Programmatic use, integrations, automation	Editor (frontend sends live canvas state)
Auth	API key or session	API key, session, or internal