Create run

http
POST /runs

Create a run.

Servers

json
[
  {
    "url": "https://api.veryfront.com"
  }
]

Authentication

json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyAuth": []
  },
  {
    "runExecutionAuth": []
  }
]
json
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT or API Key",
    "description": "Use a JWT bearer token or a Veryfront API key in the `Authorization` header."
  },
  "apiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key",
    "description": "Alternative API key header for `vf_<prefix>_<secret>` tokens."
  },
  "runExecutionAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT",
    "description": "Server-issued credential bound to project, run, registered runtime, execution generation, audience, expiry, and explicitly allowed operations; user/API-key editor access is insufficient."
  }
}

Parameters

NameLocationRequiredDescription
Idempotency-KeyheaderNo

Parameter contracts

json
[
  {
    "schema": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "required": false,
    "name": "Idempotency-Key",
    "in": "header"
  }
]

Request body

json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateRunRequest"
      },
      "examples": {
        "minimal": {
          "summary": "Minimal request",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "health-check"
            }
          }
        },
        "agent": {
          "summary": "API-started agent",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "coordinator"
            },
            "input": {
              "message": "Research the topic and summarize it."
            }
          }
        },
        "task": {
          "summary": "Task run",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "summarize"
            },
            "input": {
              "text": "A short document."
            }
          }
        },
        "workflow": {
          "summary": "Workflow run",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "workflow",
              "id": "review"
            },
            "input": {
              "document_id": "document_example"
            }
          }
        },
        "child": {
          "summary": "Child run",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "research"
            },
            "input": {
              "question": "Find relevant sources."
            },
            "parent_run_id": "22222222-2222-4222-8222-222222222222",
            "tool_call_id": "call_invoke_agent"
          }
        },
        "workflow_child": {
          "summary": "Workflow starts an agent",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "coordinator"
            },
            "input": {
              "topic": "Energy storage"
            },
            "parent_run_id": "11111111-1111-4111-8111-111111111111",
            "node_id": "research"
          }
        },
        "evaluation": {
          "summary": "Evaluation run",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "eval"
            },
            "config": {
              "eval_id": "eval_example"
            }
          }
        },
        "relationships": {
          "summary": "Conversation and batch",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "support"
            },
            "input": {
              "message": "Summarize this document."
            },
            "conversation_id": "00000000-0000-4000-8000-000000000002",
            "batch_id": "00000000-0000-4000-8000-000000000003"
          }
        },
        "runtime": {
          "summary": "Registered runtime",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "summarize"
            },
            "input": {
              "text": "A short document."
            },
            "execution": {
              "runtime": {
                "type": "registered",
                "id": "runtime_example"
              }
            }
          }
        },
        "schedule": {
          "summary": "Saved schedule",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "source": {
              "type": "schedule",
              "id": "00000000-0000-4000-8000-000000000002"
            }
          }
        },
        "webhook": {
          "summary": "Webhook run",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "input": {
              "event": "document_uploaded"
            },
            "source": {
              "type": "webhook",
              "id": "webhook_example"
            }
          }
        },
        "agent_configuration": {
          "summary": "Agent with client tools and model configuration",
          "value": {
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "researcher"
            },
            "input": "Research the topic and summarize it.",
            "config": {
              "conversation_mode": "create_new",
              "tools": [
                {
                  "name": "read_document",
                  "description": "Reads a document.",
                  "parameters": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id"
                    ]
                  }
                }
              ],
              "context": [
                {
                  "type": "text",
                  "text": "Use the provided document."
                }
              ],
              "forwarded_props": {
                "model": "provider/model"
              }
            }
          }
        }
      }
    }
  }
}

Responses

202

Run admitted. Project-owned runs need project.runs.write; conversation-owned runs need editor access on the conversation.

json
{
  "description": "Run admitted. Project-owned runs need project.runs.write; conversation-owned runs need editor access on the conversation.",
  "headers": {
    "Location": {
      "schema": {
        "type": "string",
        "format": "uri-reference"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateRunResult"
      },
      "examples": {
        "minimal": {
          "summary": "Minimal request",
          "value": {
            "id": "11111111-1111-4111-8111-111111111111",
            "run_id": "11111111-1111-4111-8111-111111111111",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "health-check"
            },
            "input": null,
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            }
          }
        },
        "agent": {
          "summary": "API-started agent",
          "value": {
            "id": "22222222-2222-4222-8222-222222222222",
            "run_id": "22222222-2222-4222-8222-222222222222",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "coordinator"
            },
            "input": {
              "message": "Research the topic and summarize it."
            },
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            }
          }
        },
        "task": {
          "summary": "Task run",
          "value": {
            "id": "11111111-1111-4111-8111-111111111111",
            "run_id": "11111111-1111-4111-8111-111111111111",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "summarize"
            },
            "input": {
              "text": "A short document."
            },
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            }
          }
        },
        "workflow": {
          "summary": "Workflow run",
          "value": {
            "id": "11111111-1111-4111-8111-111111111111",
            "run_id": "11111111-1111-4111-8111-111111111111",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "workflow",
              "id": "review"
            },
            "input": {
              "document_id": "document_example"
            },
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            }
          }
        },
        "child": {
          "summary": "Child run",
          "value": {
            "id": "33333333-3333-4333-8333-333333333333",
            "run_id": "33333333-3333-4333-8333-333333333333",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "research"
            },
            "input": {
              "question": "Find relevant sources."
            },
            "output": null,
            "parent_run_id": "22222222-2222-4222-8222-222222222222",
            "root_run_id": "22222222-2222-4222-8222-222222222222",
            "created_at": "2026-10-02T10:00:01Z",
            "updated_at": "2026-10-02T10:00:01Z",
            "trigger": {
              "type": "agent",
              "id": "coordinator",
              "tool_call_id": "call_invoke_agent"
            }
          }
        },
        "workflow_child": {
          "summary": "Workflow starts an agent",
          "value": {
            "id": "33333333-3333-4333-8333-333333333333",
            "run_id": "33333333-3333-4333-8333-333333333333",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "coordinator"
            },
            "input": {
              "topic": "Energy storage"
            },
            "output": null,
            "parent_run_id": "11111111-1111-4111-8111-111111111111",
            "root_run_id": "11111111-1111-4111-8111-111111111111",
            "created_at": "2026-10-02T10:00:01Z",
            "updated_at": "2026-10-02T10:00:01Z",
            "trigger": {
              "type": "workflow",
              "id": "daily-brief",
              "node_id": "research"
            }
          }
        },
        "evaluation": {
          "summary": "Evaluation run",
          "value": {
            "id": "11111111-1111-4111-8111-111111111111",
            "run_id": "11111111-1111-4111-8111-111111111111",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "eval"
            },
            "input": null,
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            },
            "config": {
              "eval_id": "eval_example"
            }
          }
        },
        "relationships": {
          "summary": "Conversation and batch",
          "value": {
            "id": "11111111-1111-4111-8111-111111111111",
            "run_id": "11111111-1111-4111-8111-111111111111",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "agent",
              "id": "support"
            },
            "input": {
              "message": "Summarize this document."
            },
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            },
            "conversation_id": "00000000-0000-4000-8000-000000000002",
            "batch_id": "00000000-0000-4000-8000-000000000003"
          }
        },
        "runtime": {
          "summary": "Registered runtime",
          "value": {
            "id": "11111111-1111-4111-8111-111111111111",
            "run_id": "11111111-1111-4111-8111-111111111111",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "summarize"
            },
            "input": {
              "text": "A short document."
            },
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            },
            "execution": {
              "runtime": {
                "type": "registered",
                "id": "runtime_example"
              }
            }
          }
        },
        "schedule": {
          "summary": "Saved schedule",
          "value": {
            "id": "11111111-1111-4111-8111-111111111111",
            "run_id": "11111111-1111-4111-8111-111111111111",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "summarize"
            },
            "input": null,
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            }
          }
        },
        "webhook": {
          "summary": "Webhook run",
          "value": {
            "id": "11111111-1111-4111-8111-111111111111",
            "run_id": "11111111-1111-4111-8111-111111111111",
            "status": "pending",
            "project_id": "00000000-0000-4000-8000-000000000001",
            "target": {
              "type": "task",
              "id": "summarize"
            },
            "input": {
              "event": "document_uploaded"
            },
            "output": null,
            "created_at": "2026-10-02T10:00:00Z",
            "updated_at": "2026-10-02T10:00:02Z",
            "trigger": {
              "type": "api_key",
              "id": "key_example"
            }
          }
        }
      }
    }
  }
}

400

Bad request

json
{
  "description": "Bad request",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 400
              }
            }
          }
        ]
      }
    }
  }
}

401

Unauthorized

json
{
  "description": "Unauthorized",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 401
              }
            }
          }
        ]
      }
    }
  }
}

403

Forbidden

json
{
  "description": "Forbidden",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 403
              }
            }
          }
        ]
      }
    }
  }
}

404

Not found

json
{
  "description": "Not found",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 404
              }
            }
          }
        ]
      }
    }
  }
}

409

Conflict

json
{
  "description": "Conflict",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 409
              }
            }
          }
        ]
      }
    }
  }
}

413

Payload too large

json
{
  "description": "Payload too large",
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 413
              }
            }
          }
        ]
      }
    }
  }
}

429

Rate limit exceeded

json
{
  "description": "Rate limit exceeded",
  "headers": {
    "Retry-After": {
      "schema": {
        "type": "integer",
        "format": "int32",
        "minimum": 1
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TargetRunProblem"
          },
          {
            "properties": {
              "status": {
                "const": 429
              }
            }
          }
        ]
      }
    }
  }
}

Referenced contracts

components/schemas/CreateRunRequest

json
{
  "anyOf": [
    {
      "$ref": "#/components/schemas/DirectRunRequest"
    },
    {
      "$ref": "#/components/schemas/ScheduleRunRequest"
    },
    {
      "$ref": "#/components/schemas/WebhookRunRequest"
    }
  ],
  "description": "Create a direct run with project_id, target:{type,id}, and optional input, or execute a saved schedule or webhook. Input is business data; configuration and execution settings are separate."
}

components/schemas/DirectRunRequest

json
{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the project containing the execution definition or saved source."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Optional display title for the accepted run."
    },
    "labels": {
      "$ref": "#/components/schemas/RunLabels"
    },
    "target": {
      "$ref": "#/components/schemas/RunTarget"
    },
    "input": {
      "description": "Business input passed to the definition unchanged; omitted input resolves to null."
    },
    "config": {
      "type": "object",
      "additionalProperties": {
        "description": "A JSON value."
      },
      "description": "Definition-specific configuration; business keys retain their spelling on every transport. Agent targets with `conversation_id` read `agent_admission` (AgentAdmissionConfig)."
    },
    "execution": {
      "$ref": "#/components/schemas/RunExecutionOptions"
    },
    "parent_run_id": {
      "type": "string",
      "format": "uuid",
      "description": "Canonical UUID of the authenticated runtime parent; ordinary users cannot assert parent authority."
    },
    "tool_call_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Durable tool invocation on an agent parent; requires parent_run_id and excludes node_id."
    },
    "node_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Started workflow node on the parent; requires parent_run_id and excludes tool_call_id."
    },
    "conversation_id": {
      "type": "string",
      "format": "uuid",
      "description": "Conversation associated with an agent admission, when applicable."
    },
    "batch_id": {
      "type": "string",
      "format": "uuid",
      "description": "Batch UUID associated with the accepted run."
    }
  },
  "required": [
    "project_id",
    "target"
  ],
  "additionalProperties": false,
  "dependentRequired": {
    "tool_call_id": [
      "parent_run_id"
    ],
    "node_id": [
      "parent_run_id"
    ]
  },
  "allOf": [
    {
      "not": {
        "required": [
          "tool_call_id",
          "node_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "target": {
            "properties": {
              "type": {
                "const": "agent"
              }
            },
            "required": [
              "type"
            ]
          },
          "config": {
            "required": [
              "agent_admission"
            ]
          }
        },
        "required": [
          "target",
          "config"
        ]
      },
      "then": {
        "required": [
          "conversation_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "target": {
            "properties": {
              "type": {
                "const": "agent"
              }
            },
            "required": [
              "type"
            ]
          }
        },
        "required": [
          "target",
          "conversation_id"
        ]
      },
      "then": {
        "properties": {
          "config": {
            "properties": {
              "agent_admission": {
                "$ref": "#/components/schemas/AgentAdmissionConfig"
              }
            }
          }
        }
      }
    }
  ]
}

components/schemas/RunLabels

json
{
  "type": "object",
  "additionalProperties": {
    "type": "string",
    "maxLength": 256
  },
  "description": "Labels used to organize runs.",
  "maxProperties": 50,
  "propertyNames": {
    "type": "string",
    "minLength": 1,
    "maxLength": 64,
    "pattern": "^[a-zA-Z0-9_.-]+$"
  },
  "x-ref-description": "Labels used to organize runs."
}

components/schemas/RunTarget

json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "agent",
        "task",
        "workflow"
      ],
      "description": "Kind of execution definition."
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "pattern": "^\\S+$",
      "description": "Definition ID without a kind prefix, such as health-check rather than task:health-check."
    }
  },
  "required": [
    "type",
    "id"
  ],
  "additionalProperties": false,
  "description": "Definition executed by this run."
}

components/schemas/RunExecutionOptions

json
{
  "type": "object",
  "properties": {
    "runtime": {
      "allOf": [
        {
          "$ref": "#/components/schemas/RunRuntime"
        },
        {
          "description": "Deployment or registered runtime override; omit to use the definition default.",
          "x-ref-description": "Deployment or registered runtime override; omit to use the definition default."
        }
      ]
    },
    "timeout_seconds": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Whole-run deadline in seconds, including retries; unsupported target overrides are refused."
    },
    "retry_limit": {
      "type": "integer",
      "minimum": 0,
      "description": "Maximum retries after the first attempt, restricted to retryable failures."
    }
  },
  "additionalProperties": false,
  "description": "Execution overrides, separate from business input and configuration.",
  "x-ref-description": "Execution overrides, separate from business input and configuration."
}

components/schemas/RunRuntime

json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "main_branch"
          ],
          "description": "Runtime selection kind."
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false,
      "description": "Selected main-branch deployment."
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "environment"
          ],
          "description": "Runtime selection kind."
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Environment UUID."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false,
      "description": "Selected environment."
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "preview_branch"
          ],
          "description": "Runtime selection kind."
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Preview branch UUID."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false,
      "description": "Selected preview branch."
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "registered"
          ],
          "description": "Runtime selection kind."
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Registered runtime identifier."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false,
      "description": "Selected registered runtime."
    }
  ],
  "description": "Resolved logical runtime selection; main_branch identifies the selected main-branch deployment, not a worker process.",
  "x-ref-description": "Resolved logical runtime selection; main_branch identifies the selected main-branch deployment, not a worker process."
}

components/schemas/AgentAdmissionConfig

json
{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "hosted",
        "project",
        "worker"
      ],
      "description": "Who executes the agent: `worker` hands the run to a registered agent worker that claims it, `project` runs the deployed project agent, `hosted` runs the Veryfront chat agent."
    },
    "agent_identity": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        }
      },
      "required": [
        "name"
      ],
      "additionalProperties": false,
      "description": "Worker display identity only; grants no execution capabilities."
    },
    "composing_user_id": {
      "type": "string",
      "format": "uuid",
      "description": "User who composed the triggering message."
    },
    "input_message_id": {
      "type": "string",
      "format": "uuid",
      "description": "Persisted user message that starts the run; defaults to the latest conversation message."
    },
    "implementation_kind": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "Required for `worker`: the `implementation_kind` the agent worker registered with."
    },
    "worker_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[a-zA-Z0-9_.:-]+$",
      "description": "Pin the run to one registered worker by its `worker_key`; omit to let any matching worker claim it."
    },
    "client_run_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Deprecated. Send an `Idempotency-Key` header instead."
    },
    "source_target_kind": {
      "type": "string",
      "enum": [
        "project",
        "main_branch",
        "environment",
        "preview_branch"
      ],
      "description": "Worker source selection: project, main_branch, environment, or preview_branch."
    },
    "source_target_environment_id": {
      "type": "string",
      "format": "uuid",
      "description": "Environment UUID when `source_target_kind` is `environment`."
    },
    "source_target_branch_id": {
      "type": "string",
      "format": "uuid",
      "description": "Preview branch UUID when `source_target_kind` is `preview_branch`."
    }
  },
  "required": [
    "mode"
  ],
  "additionalProperties": false,
  "description": "Agent admission for an agent target with `conversation_id`. The conversation's latest message must be a persisted user message. Before durable queue admission, the prepared active user message and its run/conversation/input identity wrapper must fit 2 MiB of serialized UTF-8 JSON. Larger prepared requests fail with INVALID_INPUT before quota charging or dispatch and are never truncated. See https://veryfront.com/docs/cloud/connect-agent-runtime.",
  "allOf": [
    {
      "if": {
        "properties": {
          "mode": {
            "const": "worker"
          }
        },
        "required": [
          "mode"
        ]
      },
      "then": {
        "required": [
          "implementation_kind"
        ]
      }
    },
    {
      "not": {
        "required": [
          "source_target_environment_id",
          "source_target_branch_id"
        ]
      }
    },
    {
      "if": {
        "anyOf": [
          {
            "required": [
              "source_target_environment_id"
            ]
          },
          {
            "required": [
              "source_target_branch_id"
            ]
          }
        ]
      },
      "then": {
        "properties": {
          "mode": {
            "const": "worker"
          }
        },
        "required": [
          "mode",
          "source_target_kind"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "source_target_kind": {
            "enum": [
              "project",
              "main_branch"
            ]
          }
        },
        "required": [
          "source_target_kind"
        ]
      },
      "then": {
        "not": {
          "anyOf": [
            {
              "required": [
                "source_target_environment_id"
              ]
            },
            {
              "required": [
                "source_target_branch_id"
              ]
            }
          ]
        }
      }
    },
    {
      "if": {
        "properties": {
          "source_target_kind": {
            "const": "environment"
          }
        },
        "required": [
          "source_target_kind"
        ]
      },
      "then": {
        "required": [
          "source_target_environment_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "source_target_kind": {
            "const": "preview_branch"
          }
        },
        "required": [
          "source_target_kind"
        ]
      },
      "then": {
        "required": [
          "source_target_branch_id"
        ]
      }
    }
  ]
}

components/schemas/ScheduleRunRequest

json
{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the project containing the execution definition or saved source."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Optional display title for the accepted run."
    },
    "labels": {
      "$ref": "#/components/schemas/RunLabels"
    },
    "source": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "schedule"
          ],
          "description": "Execute a saved schedule."
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "UUID of the saved schedule in this project."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false,
      "description": "Saved schedule supplying the target and execution configuration."
    }
  },
  "required": [
    "project_id",
    "source"
  ],
  "additionalProperties": false
}

components/schemas/WebhookRunRequest

json
{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "format": "uuid"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "labels": {
      "$ref": "#/components/schemas/RunLabels"
    },
    "source": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "webhook"
          ],
          "description": "Saved source kind."
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Saved webhook identifier."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false,
      "description": "Saved webhook to execute."
    },
    "input": {
      "description": "A JSON value."
    }
  },
  "required": [
    "project_id",
    "source",
    "input"
  ],
  "additionalProperties": false
}

components/schemas/CreateRunResult

json
{
  "anyOf": [
    {
      "$ref": "#/components/schemas/CreatedRun"
    },
    {
      "$ref": "#/components/schemas/RunCreationReceipt"
    }
  ],
  "description": "The full created run when readable by the caller; otherwise only its admission receipt. Replay uses the same caller visibility."
}

components/schemas/CreatedRun

json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique run UUID."
    },
    "run_id": {
      "type": "string",
      "minLength": 1,
      "description": "Public run ID that run events (metadata.run_id) and runtime tools name. Equals id for runs the server names; older runs keep their run_ ID."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "waiting",
        "completed",
        "failed",
        "cancelled"
      ],
      "description": "Current execution state."
    },
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "Project containing the run."
    },
    "target": {
      "$ref": "#/components/schemas/CreatedRunTarget"
    },
    "input": {
      "description": "Business input supplied when the run was created."
    },
    "output": {
      "description": "Final business output; null until successful finalization."
    },
    "error": {
      "$ref": "#/components/schemas/RunFailure"
    },
    "title": {
      "type": "string",
      "description": "Display title, omitted when unset."
    },
    "labels": {
      "$ref": "#/components/schemas/RunLabels"
    },
    "parent_run_id": {
      "type": "string",
      "format": "uuid",
      "description": "Immediate parent run ID, present on child runs."
    },
    "root_run_id": {
      "type": "string",
      "format": "uuid",
      "description": "Top-level ancestor run ID, present on child runs."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the run was accepted."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the resource last changed, including usage updates."
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the first execution attempt started, omitted before execution."
    },
    "finished_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the run completed, failed or was cancelled."
    },
    "config": {
      "type": "object",
      "additionalProperties": {
        "description": "A JSON value."
      },
      "description": "Definition-specific execution configuration."
    },
    "execution": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Current or final execution assignment identity; absent before assignment or when unavailable."
        },
        "runtime_instance": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Actual executing process identity."
            },
            "name": {
              "type": "string",
              "description": "Process name captured for this execution."
            },
            "mode": {
              "type": "string",
              "enum": [
                "service",
                "worker"
              ]
            }
          },
          "required": [
            "id",
            "mode"
          ],
          "description": "Actual process attribution; additive compatibility bridge while runtime retains logical selection."
        },
        "runtime": {
          "$ref": "#/components/schemas/RunRuntime"
        },
        "timeout_seconds": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "description": "Deadline for the whole run in seconds, measured from its first start and including retries."
        },
        "retry_limit": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum retries after the first attempt; only retryable failures are retried."
        },
        "attempt": {
          "type": "integer",
          "minimum": 1,
          "description": "Current or last execution attempt, starting at 1; absent before execution."
        },
        "exit_code": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Runtime process exit code, or null when no exit code was recorded."
        },
        "duration_ms": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Elapsed time from first start to finish, including waits and retries; null when not finished.",
          "format": "int64"
        },
        "tool_error_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Recorded failed tool invocations during this run."
        },
        "logs": {
          "type": "string",
          "description": "Captured runtime text logs, when available."
        },
        "start_mode": {
          "type": "string",
          "description": "Recorded execution start mode, when available."
        },
        "worker": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Agent worker ID."
            },
            "name": {
              "type": "string",
              "description": "Worker display name, omitted when the worker registered without one."
            },
            "worker_key": {
              "type": "string",
              "description": "Key the worker registered under, unique per project and kind; omitted when the worker is gone."
            },
            "implementation_kind": {
              "type": "string",
              "description": "Agent implementation the worker runs, such as codex; omitted when the worker is gone."
            },
            "claimed_at": {
              "type": "string",
              "format": "date-time",
              "description": "When the worker claimed the run."
            }
          },
          "required": [
            "id",
            "claimed_at"
          ],
          "description": "Agent worker that claimed and executed the run; present only on worker-executed runs."
        }
      },
      "description": "Resolved execution settings and diagnostics."
    },
    "control": {
      "type": "object",
      "properties": {
        "waiting": {
          "$ref": "#/components/schemas/RunWait"
        },
        "pause": {
          "$ref": "#/components/schemas/RunPause"
        },
        "cancellation": {
          "$ref": "#/components/schemas/RunCancellation"
        }
      },
      "description": "Pending control requests and the current wait."
    },
    "task_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Orchestration task ID, distinct from the execution definition."
    },
    "conversation_id": {
      "type": "string",
      "format": "uuid",
      "description": "Conversation containing the run."
    },
    "input_message_id": {
      "type": "string",
      "format": "uuid",
      "description": "Conversation message that supplied the input."
    },
    "output_message_id": {
      "type": "string",
      "format": "uuid",
      "description": "Conversation message containing the result."
    },
    "batch_id": {
      "type": "string",
      "format": "uuid",
      "description": "Batch containing the run."
    },
    "trigger": {
      "$ref": "#/components/schemas/RunTrigger"
    },
    "usage": {
      "$ref": "#/components/schemas/Usage"
    },
    "descendants": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer",
          "minimum": 0,
          "description": "Total descendants at every depth."
        },
        "active": {
          "type": "integer",
          "minimum": 0,
          "description": "Descendants that are pending, running or waiting."
        },
        "has_failures": {
          "type": "boolean",
          "description": "Whether any descendant has failed."
        },
        "usage": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Usage"
            },
            {
              "description": "Aggregate usage of every descendant, excluding this run.",
              "x-ref-description": "Aggregate usage of every descendant, excluding this run."
            }
          ]
        }
      },
      "required": [
        "total",
        "active",
        "has_failures"
      ],
      "description": "Counts and usage across all descendant runs, excluding this run."
    },
    "artifacts": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/RunArtifact"
      },
      "description": "Files produced by the run."
    },
    "schemas": {
      "type": "object",
      "properties": {
        "input": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "schema": {
              "description": "JSON Schema captured for this run; object schemas and boolean schemas are supported.",
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "object",
                  "additionalProperties": {
                    "description": "A JSON value."
                  }
                }
              ]
            },
            "sha256": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$",
              "description": "SHA-256 digest of the pinned schema."
            }
          },
          "required": [
            "schema",
            "sha256"
          ]
        },
        "output": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "schema": {
              "description": "JSON Schema captured for this run; object schemas and boolean schemas are supported.",
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "object",
                  "additionalProperties": {
                    "description": "A JSON value."
                  }
                }
              ]
            },
            "sha256": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$",
              "description": "SHA-256 digest of the pinned schema."
            }
          },
          "required": [
            "schema",
            "sha256"
          ]
        }
      },
      "required": [
        "input",
        "output"
      ],
      "description": "Pinned schemas for business input and output; null means no declared schema."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "description": "A JSON value."
      },
      "description": "Additional resource metadata."
    }
  },
  "required": [
    "id",
    "run_id",
    "status",
    "project_id",
    "target",
    "input",
    "output",
    "created_at",
    "updated_at",
    "trigger"
  ],
  "description": "A newly created run with resolved target and recorded trigger.",
  "allOf": [
    {
      "if": {
        "properties": {
          "status": {
            "enum": [
              "failed"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "then": {
        "required": [
          "error"
        ]
      },
      "else": {
        "not": {
          "required": [
            "error"
          ]
        }
      }
    },
    {
      "if": {
        "properties": {
          "status": {
            "enum": [
              "completed",
              "failed",
              "cancelled"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "then": {
        "required": [
          "finished_at"
        ]
      },
      "else": {
        "not": {
          "required": [
            "finished_at"
          ]
        }
      }
    },
    {
      "if": {
        "properties": {
          "status": {
            "enum": [
              "pending",
              "running",
              "waiting",
              "failed",
              "cancelled"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "then": {
        "properties": {
          "output": {
            "type": "null"
          }
        }
      },
      "else": {}
    },
    {
      "if": {
        "properties": {
          "status": {
            "enum": [
              "waiting"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "then": {
        "required": [
          "control"
        ],
        "properties": {
          "control": {
            "required": [
              "waiting"
            ]
          }
        }
      },
      "else": {
        "properties": {
          "control": {
            "not": {
              "required": [
                "waiting"
              ]
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "control": {
            "required": [
              "pause"
            ]
          }
        },
        "required": [
          "control"
        ]
      },
      "then": {
        "properties": {
          "status": {
            "enum": [
              "pending",
              "running",
              "waiting"
            ]
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "trigger"
        ],
        "properties": {
          "trigger": {
            "properties": {
              "type": {
                "enum": [
                  "agent",
                  "task",
                  "workflow"
                ]
              }
            },
            "required": [
              "type"
            ]
          }
        }
      },
      "then": {
        "required": [
          "parent_run_id",
          "root_run_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "status": {
            "const": "completed"
          }
        },
        "required": [
          "status"
        ]
      },
      "then": {
        "properties": {
          "descendants": {
            "properties": {
              "active": {
                "const": 0
              }
            }
          }
        }
      }
    }
  ],
  "dependentRequired": {
    "parent_run_id": [
      "root_run_id"
    ],
    "root_run_id": [
      "parent_run_id"
    ]
  }
}

components/schemas/CreatedRunTarget

json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "agent",
        "task",
        "workflow"
      ],
      "description": "Kind of execution definition."
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "pattern": "^\\S+$",
      "description": "Definition ID without a kind prefix, such as health-check rather than task:health-check."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "Display name captured at admission when available."
    },
    "agent_kind": {
      "type": "string",
      "enum": [
        "project"
      ],
      "description": "Server-recorded project agent identity; absence retains legacy identity semantics."
    }
  },
  "required": [
    "type",
    "id"
  ],
  "additionalProperties": false,
  "description": "Resolved execution definition.",
  "x-ref-description": "Resolved execution definition."
}

components/schemas/RunFailure

json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Stable failure code."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Human-readable failure message."
    },
    "details": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional failure details."
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": false,
  "description": "Failure details, present only when the run failed.",
  "x-ref-description": "Failure details, present only when the run failed."
}

components/schemas/RunWait

json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "resume_at": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled automatic resume time."
        },
        "reason": {
          "type": "string",
          "enum": [
            "manual_pause"
          ],
          "description": "Condition required to resume the run."
        }
      },
      "required": [
        "reason"
      ],
      "description": "Waiting for manual resumption."
    },
    {
      "type": "object",
      "properties": {
        "resume_at": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled automatic resume time."
        },
        "reason": {
          "type": "string",
          "enum": [
            "tool_result"
          ],
          "description": "Condition required to resume the run."
        },
        "tool_call_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Tool call awaiting a result."
        }
      },
      "required": [
        "reason",
        "tool_call_id"
      ],
      "description": "Waiting for a tool result."
    },
    {
      "type": "object",
      "properties": {
        "resume_at": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled automatic resume time."
        },
        "reason": {
          "type": "string",
          "enum": [
            "integration_connected"
          ],
          "description": "Condition required to resume the run."
        },
        "integration": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Integration awaiting connection."
        }
      },
      "required": [
        "reason",
        "integration"
      ],
      "description": "Waiting for an integration connection."
    },
    {
      "type": "object",
      "properties": {
        "resume_at": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled automatic resume time."
        },
        "reason": {
          "type": "string",
          "enum": [
            "approval"
          ],
          "description": "Condition required to resume the run."
        },
        "wait_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Durable wait identifier."
        },
        "node_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "minItems": 1,
          "description": "Workflow nodes awaiting approval."
        }
      },
      "required": [
        "reason",
        "wait_id",
        "node_ids"
      ],
      "description": "Waiting for workflow approval."
    },
    {
      "type": "object",
      "properties": {
        "resume_at": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled automatic resume time."
        },
        "reason": {
          "type": "string",
          "enum": [
            "event"
          ],
          "description": "Condition required to resume the run."
        },
        "wait_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Durable wait identifier."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Event required to resume."
        }
      },
      "required": [
        "reason",
        "wait_id",
        "name"
      ],
      "description": "Waiting for a named event."
    },
    {
      "type": "object",
      "properties": {
        "resume_at": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled automatic resume time."
        },
        "reason": {
          "type": "string",
          "enum": [
            "input_request"
          ],
          "description": "Condition required to resume the run."
        },
        "input_request_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "minItems": 1,
          "description": "Input requests awaiting responses."
        }
      },
      "required": [
        "reason",
        "input_request_ids"
      ],
      "description": "Waiting for input responses."
    },
    {
      "type": "object",
      "properties": {
        "resume_at": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled automatic resume time."
        },
        "reason": {
          "type": "string",
          "enum": [
            "child_run"
          ],
          "description": "Condition required to resume the run."
        },
        "dependencies": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "run_id": {
                "type": "string",
                "format": "uuid",
                "description": "Canonical UUID of the child run."
              },
              "correlation": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "tool_call"
                        ],
                        "description": "Child invocation kind."
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128,
                        "description": "Tool call identifier."
                      }
                    },
                    "required": [
                      "type",
                      "id"
                    ],
                    "additionalProperties": false,
                    "description": "Child started by a tool call."
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "workflow_node"
                        ],
                        "description": "Child invocation kind."
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128,
                        "description": "Workflow node identifier."
                      }
                    },
                    "required": [
                      "type",
                      "id"
                    ],
                    "additionalProperties": false,
                    "description": "Child started by a workflow node."
                  }
                ]
              }
            },
            "required": [
              "run_id",
              "correlation"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "description": "Child runs that must finish."
        }
      },
      "required": [
        "reason",
        "dependencies"
      ],
      "description": "Waiting for child runs."
    },
    {
      "type": "object",
      "properties": {
        "resume_at": {
          "type": "string",
          "format": "date-time",
          "description": "Scheduled automatic resume time."
        },
        "reason": {
          "type": "string",
          "enum": [
            "timer"
          ],
          "description": "Condition required to resume the run."
        }
      },
      "required": [
        "resume_at",
        "reason"
      ],
      "description": "Waiting until the scheduled resume time."
    }
  ],
  "description": "The current durable wait, with only the fields required to satisfy that wait."
}

components/schemas/RunPause

json
{
  "type": "object",
  "properties": {
    "requested_at": {
      "type": "string",
      "format": "date-time",
      "description": "Time the pause was requested."
    }
  },
  "required": [
    "requested_at"
  ],
  "additionalProperties": false,
  "description": "When a pause was requested; control.waiting confirms when execution is paused."
}

components/schemas/RunCancellation

json
{
  "type": "object",
  "properties": {
    "requested_at": {
      "type": "string",
      "format": "date-time",
      "description": "Time cancellation was requested."
    },
    "stopped_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Time the runtime confirmed its stop; null until confirmed."
    }
  },
  "required": [
    "requested_at",
    "stopped_at"
  ]
}

components/schemas/RunTrigger

json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "user"
          ]
        },
        "id": {
          "type": "string",
          "format": "uuid"
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "api_key"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "name": {
          "type": "string",
          "description": "Display name of the API key, revoked keys included; omitted when unknown."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "service_account"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "system"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "schedule"
          ]
        },
        "id": {
          "type": "string",
          "format": "uuid"
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "webhook"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "agent"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512,
          "pattern": "^\\S+$"
        },
        "tool_call_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "task"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512,
          "pattern": "^\\S+$"
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "workflow"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512,
          "pattern": "^\\S+$"
        },
        "node_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    }
  ],
  "description": "How execution was initiated.",
  "x-ref-description": "How execution was initiated."
}

components/schemas/Usage

json
{
  "type": "object",
  "properties": {
    "funding": {
      "type": "string",
      "enum": [
        "managed",
        "customer",
        "mixed"
      ],
      "description": "Recorded model funding; omitted when any call has unknown funding."
    },
    "tokens": {
      "$ref": "#/components/schemas/TokenUsage"
    },
    "cost": {
      "$ref": "#/components/schemas/Cost"
    },
    "model_calls": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "description": "Billed provider call count.",
      "format": "int64"
    },
    "capture_status": {
      "type": "string",
      "enum": [
        "complete",
        "partial",
        "missing"
      ],
      "description": "Token capture coverage."
    }
  },
  "required": [
    "tokens",
    "cost",
    "capture_status"
  ],
  "description": "Usage when available; unknown measurements are null.",
  "x-ref-description": "Usage when available; unknown measurements are null."
}

components/schemas/TokenUsage

json
{
  "type": "object",
  "properties": {
    "input": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "description": "Input tokens excluding cache reads and writes.",
      "format": "int64"
    },
    "output": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "description": "Output tokens including reasoning.",
      "format": "int64"
    },
    "cache": {
      "type": "object",
      "properties": {
        "read": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Tokens read from the provider cache.",
          "format": "int64"
        },
        "write": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Tokens written to the provider cache.",
          "format": "int64"
        }
      },
      "required": [
        "read",
        "write"
      ]
    },
    "reasoning": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "description": "Reasoning tokens included in output.",
      "format": "int64"
    },
    "total": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "description": "Sum of input, output, cache-read and cache-write tokens.",
      "format": "int64"
    }
  },
  "required": [
    "input",
    "output",
    "cache",
    "total"
  ],
  "description": "Input excludes cache reads/writes; output includes reasoning. Total is input + output + cache.read + cache.write. Null means unknown, never zero."
}

components/schemas/Cost

json
{
  "type": "object",
  "properties": {
    "currency": {
      "type": "string",
      "enum": [
        "EUR"
      ],
      "description": "Currency of reference usage value and provider costs."
    },
    "status": {
      "type": "string",
      "enum": [
        "estimated",
        "posted",
        "unavailable"
      ],
      "description": "Whether charges are estimated, posted or unavailable."
    },
    "provider": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^-?\\d+(\\.\\d{1,8})?$",
      "description": "Recorded provider USD cost converted to EUR at the catalog reference rate; null when unknown."
    },
    "platform": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^-?\\d+(\\.\\d{1,8})?$",
      "description": "Reference usage value minus estimated provider cost; null when either amount is unknown."
    },
    "total": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^-?\\d+(\\.\\d{1,8})?$",
      "description": "Billed credits valued at EUR 0.10 per credit, independent of subscription or purchase discounts."
    },
    "credits": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^-?\\d+(\\.\\d{1,8})?$",
      "description": "Billed credit units."
    }
  },
  "required": [
    "currency",
    "status",
    "provider",
    "platform",
    "total",
    "credits"
  ],
  "description": "Estimated EUR usage value before tax: total values billed credits at EUR 0.10 each; provider converts recorded USD cost at the catalog reference rate; platform is total minus provider and can be negative. These amounts are visible to authorized run readers and do not represent invoice charges or actual purchase prices. Descendants sum the same per-run amounts. Credits are exact billed units. Signed decimal strings have at most eight fractional digits. Unknown provider costs leave provider and platform null. Status is independent of token capture; unavailable requires all amounts null. Posted amounts come from the billing ledger and may change through later adjustments.",
  "allOf": [
    {
      "if": {
        "properties": {
          "status": {
            "enum": [
              "unavailable"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "then": {
        "properties": {
          "provider": {
            "type": "null"
          },
          "platform": {
            "type": "null"
          },
          "total": {
            "type": "null"
          },
          "credits": {
            "type": "null"
          }
        }
      },
      "else": {}
    }
  ]
}

components/schemas/RunArtifact

json
{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Immutable artifact identifier."
    },
    "type": {
      "type": "string",
      "minLength": 1,
      "description": "Artifact kind."
    },
    "media_type": {
      "type": "string",
      "minLength": 1,
      "description": "File media type."
    },
    "size_bytes": {
      "type": "integer",
      "minimum": 0,
      "description": "File size in bytes."
    },
    "sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "SHA-256 digest of the file."
    },
    "href": {
      "type": "string",
      "format": "uri",
      "description": "Authorized artifact URL."
    }
  },
  "required": [
    "artifact_id",
    "type",
    "media_type",
    "size_bytes",
    "sha256",
    "href"
  ],
  "description": "An immutable file reference authorized through the run’s project and conversation permissions."
}

components/schemas/RunCreationReceipt

json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the admitted run (a full run calls it id). A receipt carries no public run ID."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "waiting",
        "completed",
        "failed",
        "cancelled"
      ],
      "description": "Current execution state."
    }
  },
  "required": [
    "run_id",
    "status"
  ],
  "additionalProperties": false,
  "description": "Minimal admission receipt for a caller who cannot read the created run. No private fields are disclosed."
}

components/schemas/TargetRunProblem

json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Problem type URI reference."
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599,
      "format": "int64"
    },
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "cause": {
      "type": "string",
      "enum": [
        "schedule_concurrency_forbidden",
        "schedule_fire_in_progress",
        "schedule_run_limit_reached"
      ],
      "description": "Schedule admission refusal."
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "field",
          "message"
        ]
      }
    }
  },
  "required": [
    "type",
    "title",
    "status",
    "code"
  ]
}

Operation contract

json
{
  "operationId": "createRun",
  "tags": [
    "execution/Runs/Runs"
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyAuth": []
    },
    {
      "runExecutionAuth": []
    }
  ],
  "summary": "Create run",
  "description": "Create a run.",
  "parameters": [
    {
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "required": false,
      "name": "Idempotency-Key",
      "in": "header"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateRunRequest"
        },
        "examples": {
          "minimal": {
            "summary": "Minimal request",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "task",
                "id": "health-check"
              }
            }
          },
          "agent": {
            "summary": "API-started agent",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "agent",
                "id": "coordinator"
              },
              "input": {
                "message": "Research the topic and summarize it."
              }
            }
          },
          "task": {
            "summary": "Task run",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "task",
                "id": "summarize"
              },
              "input": {
                "text": "A short document."
              }
            }
          },
          "workflow": {
            "summary": "Workflow run",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "workflow",
                "id": "review"
              },
              "input": {
                "document_id": "document_example"
              }
            }
          },
          "child": {
            "summary": "Child run",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "agent",
                "id": "research"
              },
              "input": {
                "question": "Find relevant sources."
              },
              "parent_run_id": "22222222-2222-4222-8222-222222222222",
              "tool_call_id": "call_invoke_agent"
            }
          },
          "workflow_child": {
            "summary": "Workflow starts an agent",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "agent",
                "id": "coordinator"
              },
              "input": {
                "topic": "Energy storage"
              },
              "parent_run_id": "11111111-1111-4111-8111-111111111111",
              "node_id": "research"
            }
          },
          "evaluation": {
            "summary": "Evaluation run",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "task",
                "id": "eval"
              },
              "config": {
                "eval_id": "eval_example"
              }
            }
          },
          "relationships": {
            "summary": "Conversation and batch",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "agent",
                "id": "support"
              },
              "input": {
                "message": "Summarize this document."
              },
              "conversation_id": "00000000-0000-4000-8000-000000000002",
              "batch_id": "00000000-0000-4000-8000-000000000003"
            }
          },
          "runtime": {
            "summary": "Registered runtime",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "task",
                "id": "summarize"
              },
              "input": {
                "text": "A short document."
              },
              "execution": {
                "runtime": {
                  "type": "registered",
                  "id": "runtime_example"
                }
              }
            }
          },
          "schedule": {
            "summary": "Saved schedule",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "source": {
                "type": "schedule",
                "id": "00000000-0000-4000-8000-000000000002"
              }
            }
          },
          "webhook": {
            "summary": "Webhook run",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "input": {
                "event": "document_uploaded"
              },
              "source": {
                "type": "webhook",
                "id": "webhook_example"
              }
            }
          },
          "agent_configuration": {
            "summary": "Agent with client tools and model configuration",
            "value": {
              "project_id": "00000000-0000-4000-8000-000000000001",
              "target": {
                "type": "agent",
                "id": "researcher"
              },
              "input": "Research the topic and summarize it.",
              "config": {
                "conversation_mode": "create_new",
                "tools": [
                  {
                    "name": "read_document",
                    "description": "Reads a document.",
                    "parameters": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id"
                      ]
                    }
                  }
                ],
                "context": [
                  {
                    "type": "text",
                    "text": "Use the provided document."
                  }
                ],
                "forwarded_props": {
                  "model": "provider/model"
                }
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Run admitted. Project-owned runs need project.runs.write; conversation-owned runs need editor access on the conversation.",
      "headers": {
        "Location": {
          "schema": {
            "type": "string",
            "format": "uri-reference"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateRunResult"
          },
          "examples": {
            "minimal": {
              "summary": "Minimal request",
              "value": {
                "id": "11111111-1111-4111-8111-111111111111",
                "run_id": "11111111-1111-4111-8111-111111111111",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "task",
                  "id": "health-check"
                },
                "input": null,
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                }
              }
            },
            "agent": {
              "summary": "API-started agent",
              "value": {
                "id": "22222222-2222-4222-8222-222222222222",
                "run_id": "22222222-2222-4222-8222-222222222222",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "agent",
                  "id": "coordinator"
                },
                "input": {
                  "message": "Research the topic and summarize it."
                },
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                }
              }
            },
            "task": {
              "summary": "Task run",
              "value": {
                "id": "11111111-1111-4111-8111-111111111111",
                "run_id": "11111111-1111-4111-8111-111111111111",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "task",
                  "id": "summarize"
                },
                "input": {
                  "text": "A short document."
                },
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                }
              }
            },
            "workflow": {
              "summary": "Workflow run",
              "value": {
                "id": "11111111-1111-4111-8111-111111111111",
                "run_id": "11111111-1111-4111-8111-111111111111",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "workflow",
                  "id": "review"
                },
                "input": {
                  "document_id": "document_example"
                },
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                }
              }
            },
            "child": {
              "summary": "Child run",
              "value": {
                "id": "33333333-3333-4333-8333-333333333333",
                "run_id": "33333333-3333-4333-8333-333333333333",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "agent",
                  "id": "research"
                },
                "input": {
                  "question": "Find relevant sources."
                },
                "output": null,
                "parent_run_id": "22222222-2222-4222-8222-222222222222",
                "root_run_id": "22222222-2222-4222-8222-222222222222",
                "created_at": "2026-10-02T10:00:01Z",
                "updated_at": "2026-10-02T10:00:01Z",
                "trigger": {
                  "type": "agent",
                  "id": "coordinator",
                  "tool_call_id": "call_invoke_agent"
                }
              }
            },
            "workflow_child": {
              "summary": "Workflow starts an agent",
              "value": {
                "id": "33333333-3333-4333-8333-333333333333",
                "run_id": "33333333-3333-4333-8333-333333333333",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "agent",
                  "id": "coordinator"
                },
                "input": {
                  "topic": "Energy storage"
                },
                "output": null,
                "parent_run_id": "11111111-1111-4111-8111-111111111111",
                "root_run_id": "11111111-1111-4111-8111-111111111111",
                "created_at": "2026-10-02T10:00:01Z",
                "updated_at": "2026-10-02T10:00:01Z",
                "trigger": {
                  "type": "workflow",
                  "id": "daily-brief",
                  "node_id": "research"
                }
              }
            },
            "evaluation": {
              "summary": "Evaluation run",
              "value": {
                "id": "11111111-1111-4111-8111-111111111111",
                "run_id": "11111111-1111-4111-8111-111111111111",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "task",
                  "id": "eval"
                },
                "input": null,
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                },
                "config": {
                  "eval_id": "eval_example"
                }
              }
            },
            "relationships": {
              "summary": "Conversation and batch",
              "value": {
                "id": "11111111-1111-4111-8111-111111111111",
                "run_id": "11111111-1111-4111-8111-111111111111",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "agent",
                  "id": "support"
                },
                "input": {
                  "message": "Summarize this document."
                },
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                },
                "conversation_id": "00000000-0000-4000-8000-000000000002",
                "batch_id": "00000000-0000-4000-8000-000000000003"
              }
            },
            "runtime": {
              "summary": "Registered runtime",
              "value": {
                "id": "11111111-1111-4111-8111-111111111111",
                "run_id": "11111111-1111-4111-8111-111111111111",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "task",
                  "id": "summarize"
                },
                "input": {
                  "text": "A short document."
                },
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                },
                "execution": {
                  "runtime": {
                    "type": "registered",
                    "id": "runtime_example"
                  }
                }
              }
            },
            "schedule": {
              "summary": "Saved schedule",
              "value": {
                "id": "11111111-1111-4111-8111-111111111111",
                "run_id": "11111111-1111-4111-8111-111111111111",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "task",
                  "id": "summarize"
                },
                "input": null,
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                }
              }
            },
            "webhook": {
              "summary": "Webhook run",
              "value": {
                "id": "11111111-1111-4111-8111-111111111111",
                "run_id": "11111111-1111-4111-8111-111111111111",
                "status": "pending",
                "project_id": "00000000-0000-4000-8000-000000000001",
                "target": {
                  "type": "task",
                  "id": "summarize"
                },
                "input": {
                  "event": "document_uploaded"
                },
                "output": null,
                "created_at": "2026-10-02T10:00:00Z",
                "updated_at": "2026-10-02T10:00:02Z",
                "trigger": {
                  "type": "api_key",
                  "id": "key_example"
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Bad request",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 400
                  }
                }
              }
            ]
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 401
                  }
                }
              }
            ]
          }
        }
      }
    },
    "403": {
      "description": "Forbidden",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 403
                  }
                }
              }
            ]
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 404
                  }
                }
              }
            ]
          }
        }
      }
    },
    "409": {
      "description": "Conflict",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 409
                  }
                }
              }
            ]
          }
        }
      }
    },
    "413": {
      "description": "Payload too large",
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 413
                  }
                }
              }
            ]
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded",
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer",
            "format": "int32",
            "minimum": 1
          }
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TargetRunProblem"
              },
              {
                "properties": {
                  "status": {
                    "const": 429
                  }
                }
              }
            ]
          }
        }
      }
    }
  },
  "x-codeSamples": [
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "minimal",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"task\",\n    \"id\": \"health-check\"\n  }\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "agent",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"coordinator\"\n  },\n  \"input\": {\n    \"message\": \"Research the topic and summarize it.\"\n  }\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "task",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"task\",\n    \"id\": \"summarize\"\n  },\n  \"input\": {\n    \"text\": \"A short document.\"\n  }\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "workflow",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"workflow\",\n    \"id\": \"review\"\n  },\n  \"input\": {\n    \"document_id\": \"document_example\"\n  }\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "child",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"research\"\n  },\n  \"input\": {\n    \"question\": \"Find relevant sources.\"\n  },\n  \"parent_run_id\": \"22222222-2222-4222-8222-222222222222\",\n  \"tool_call_id\": \"call_invoke_agent\"\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "workflow_child",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"coordinator\"\n  },\n  \"input\": {\n    \"topic\": \"Energy storage\"\n  },\n  \"parent_run_id\": \"11111111-1111-4111-8111-111111111111\",\n  \"node_id\": \"research\"\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "evaluation",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"task\",\n    \"id\": \"eval\"\n  },\n  \"config\": {\n    \"eval_id\": \"eval_example\"\n  }\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "relationships",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"support\"\n  },\n  \"input\": {\n    \"message\": \"Summarize this document.\"\n  },\n  \"conversation_id\": \"00000000-0000-4000-8000-000000000002\",\n  \"batch_id\": \"00000000-0000-4000-8000-000000000003\"\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "runtime",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"task\",\n    \"id\": \"summarize\"\n  },\n  \"input\": {\n    \"text\": \"A short document.\"\n  },\n  \"execution\": {\n    \"runtime\": {\n      \"type\": \"registered\",\n      \"id\": \"runtime_example\"\n    }\n  }\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "schedule",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"source\": {\n    \"type\": \"schedule\",\n    \"id\": \"00000000-0000-4000-8000-000000000002\"\n  }\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "webhook",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"input\": {\n    \"event\": \"document_uploaded\"\n  },\n  \"source\": {\n    \"type\": \"webhook\",\n    \"id\": \"webhook_example\"\n  }\n}"
    },
    {
      "lang": "json",
      "label": "Request JSON",
      "example": "agent_configuration",
      "contentType": "application/json",
      "source": "{\n  \"project_id\": \"00000000-0000-4000-8000-000000000001\",\n  \"target\": {\n    \"type\": \"agent\",\n    \"id\": \"researcher\"\n  },\n  \"input\": \"Research the topic and summarize it.\",\n  \"config\": {\n    \"conversation_mode\": \"create_new\",\n    \"tools\": [\n      {\n        \"name\": \"read_document\",\n        \"description\": \"Reads a document.\",\n        \"parameters\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"id\": {\n              \"type\": \"string\"\n            }\n          },\n          \"required\": [\n            \"id\"\n          ]\n        }\n      }\n    ],\n    \"context\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"Use the provided document.\"\n      }\n    ],\n    \"forwarded_props\": {\n      \"model\": \"provider/model\"\n    }\n  }\n}"
    }
  ],
  "x-documentation-source-tag": "Run resource",
  "x-canonical-documentation": {
    "domain": "execution",
    "resource": "Runs",
    "subgroup": "Runs",
    "name": "Create run",
    "description": "Create a run.",
    "operationId": "createRun"
  },
  "x-mint": {
    "href": "/cloud/rest/api-reference/execution-runs-runs/create-run"
  }
}