Documentation

Create run

POST /api/v1/tasks/runs - Create a new task run.

Create run

POST /api/v1/tasks/runs

Queues a new task run and starts asynchronous execution.

Required headers

Header	Description
`x-api-key`	Your Flow API key
`Idempotency-Key`	A stable, unique value for this logical run. Reuse it only when retrying the identical request body. Maximum 256 characters.

Request body

json

{
  "input": {
    "prompt": "Summarize the uploaded files",
    "model": "gpt-5.6-luna",
    "tools": {
      "builtin": ["readFile", "readPDF", "writeFile", "listFiles", "deleteFile", "visualizationAgent"],
      "mcp": { "servers": ["exa"], "policy": "read_only" }
    },
    "config": { "max_steps": 160, "thinking": true },
    "metadata": { "project": "demo" }
  },
  "session_id": "uuid",
  "webhook_url": "https://example.com/hook",
  "files": [{ "name": "data.csv", "content_base64": "base64..." }]
}

Response (202)

json

{
  "run_id": "run_abc123...",
  "session_id": "uuid",
  "status": "running",
  "created_at": "2026-02-27T00:00:00.000Z"
}

Endpoints List runs