> For the complete documentation index, see [llms.txt](https://docs.apolo.us/index/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apolo.us/index/apolo-mcp/capabilities/tools/flow.md).
# Flow
[Back to the MCP tool reference](/index/apolo-mcp/capabilities/tools.md).
## `flow_config_schema`
Explore a bounded root or definition from the version-pinned Flow schema.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"config_type": {
"enum": [
"live",
"batch",
"project"
],
"title": "Config Type",
"type": "string"
},
"definition": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Definition"
}
},
"required": [
"config_type"
],
"title": "flow_config_schemaArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_config_schemaDictOutput",
"type": "object"
}
```
## `flow_config_validate`
Validate one canonical .apolo YAML file against its pinned Flow schema.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"batch_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Batch Name"
},
"config_type": {
"enum": [
"live",
"batch",
"project"
],
"title": "Config Type",
"type": "string"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"workspace_path",
"config_type"
],
"title": "flow_config_validateArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_config_validateDictOutput",
"type": "object"
}
```
## `flow_config_write`
Validate and create one new canonical .apolo YAML file without overwrite.
**Operation type:** Write
**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"batch_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Batch Name"
},
"config": {
"additionalProperties": true,
"title": "Config",
"type": "object"
},
"config_type": {
"enum": [
"live",
"batch",
"project"
],
"title": "Config Type",
"type": "string"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"workspace_path",
"config_type",
"config"
],
"title": "flow_config_writeArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_config_writeDictOutput",
"type": "object"
}
```
## `flow_live_list`
List Flow live jobs within explicit context and local path scope. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"title": "Cluster",
"type": "string"
},
"limit": {
"default": 20,
"title": "Limit",
"type": "integer"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_live_listArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_live_listDictOutput",
"type": "object"
}
```
## `flow_live_get`
Resolve one logical Flow job, with a bounded multi-job result. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"title": "Cluster",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"limit": {
"default": 20,
"title": "Limit",
"type": "integer"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"suffix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Suffix"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"job_id",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_live_getArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_live_getDictOutput",
"type": "object"
}
```
## `flow_live_run`
Start a detached Flow live job under the server mutation policy. Set `detach: true` on the selected job so this operation returns after submission. Monitor it separately with get, logs, and bounded wait. Pre/post raw-ID comparison journals only newly created jobs when upstream startup times out after submission. workspace\_path is the Flow project root and must contain a real .apolo directory. flow\_live\_run reads .apolo/live.yml or .apolo/live.yaml, whose minimum shape is `kind: live` plus a `jobs` mapping; job\_id selects a key in that mapping. Each plain job needs an image and may define cmd or bash. Set `detach: true` on jobs started by MCP, then monitor them with separate get, logs, and bounded wait calls. Optional project settings belong in .apolo/project.yml or .apolo/project.yaml.
**Operation type:** Write
**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"title": "Cluster",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"org": {
"title": "Org",
"type": "string"
},
"params": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Params"
},
"project": {
"title": "Project",
"type": "string"
},
"suffix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Suffix"
},
"timeout_seconds": {
"default": 300,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"job_id",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_live_runArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_live_runDictOutput",
"type": "object"
}
```
## `flow_live_logs`
Read bounded Flow live logs with MCP-side credential redaction. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"title": "Cluster",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"max_bytes": {
"default": 100000,
"title": "Max Bytes",
"type": "integer"
},
"max_chunks": {
"default": 100,
"title": "Max Chunks",
"type": "integer"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"suffix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Suffix"
},
"timeout_seconds": {
"default": 60,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"job_id",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_live_logsArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_live_logsDictOutput",
"type": "object"
}
```
## `flow_live_wait`
Wait a bounded time for a Flow live job to terminate. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"title": "Cluster",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"limit": {
"default": 20,
"title": "Limit",
"type": "integer"
},
"org": {
"title": "Org",
"type": "string"
},
"poll_interval_seconds": {
"default": 2,
"title": "Poll Interval Seconds",
"type": "number"
},
"project": {
"title": "Project",
"type": "string"
},
"suffix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Suffix"
},
"timeout_seconds": {
"default": 300,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"job_id",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_live_waitArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_live_waitDictOutput",
"type": "object"
}
```
## `flow_live_kill`
Kill a Flow live job under the server mutation policy. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Destructive write
**Annotations:** read-only `false`, destructive `true`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"title": "Cluster",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"limit": {
"default": 20,
"title": "Limit",
"type": "integer"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"suffix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Suffix"
},
"timeout_seconds": {
"default": 300,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"job_id",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_live_killArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_live_killDictOutput",
"type": "object"
}
```
## `flow_live_kill_all`
Kill all jobs in exactly one explicit Flow context. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Destructive write
**Annotations:** read-only `false`, destructive `true`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"title": "Cluster",
"type": "string"
},
"limit": {
"default": 20,
"title": "Limit",
"type": "integer"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"timeout_seconds": {
"default": 300,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_live_kill_allArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_live_kill_allDictOutput",
"type": "object"
}
```
## `flow_bake_start`
Start a bake only through FlowAPI BatchRunner orchestration. An internal unique correlation tag lets MCP journal a bake even when the upstream runner fails after creating it. workspace\_path is the Flow project root and must contain a real .apolo directory. flow\_bake\_start reads .apolo/.yml or .yaml, whose minimum shape is `kind: batch` plus a `tasks` list; batch selects that workflow. Each plain task needs an image and may define cmd or bash. Optional project settings belong in .apolo/project.yml or .apolo/project.yaml.
**Operation type:** Write
**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"batch": {
"title": "Batch",
"type": "string"
},
"cluster": {
"title": "Cluster",
"type": "string"
},
"local_executor": {
"default": false,
"title": "Local Executor",
"type": "boolean"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"org": {
"title": "Org",
"type": "string"
},
"params": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Params"
},
"project": {
"title": "Project",
"type": "string"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tags"
},
"task_limit": {
"default": 100,
"title": "Task Limit",
"type": "integer"
},
"timeout_seconds": {
"default": 300,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"batch",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_bake_startArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_bake_startDictOutput",
"type": "object"
}
```
## `flow_bake_list`
List bakes and bounded task state in one explicit context. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"title": "Cluster",
"type": "string"
},
"limit": {
"default": 20,
"title": "Limit",
"type": "integer"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tags"
},
"task_limit": {
"default": 100,
"title": "Task Limit",
"type": "integer"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_bake_listArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_bake_listDictOutput",
"type": "object"
}
```
## `flow_bake_get`
Get structured bake, attempt, and bounded task state. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"attempt_no": {
"default": -1,
"title": "Attempt No",
"type": "integer"
},
"bake_id_or_name": {
"title": "Bake Id Or Name",
"type": "string"
},
"cluster": {
"title": "Cluster",
"type": "string"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"task_limit": {
"default": 100,
"title": "Task Limit",
"type": "integer"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"bake_id_or_name",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_bake_getArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_bake_getDictOutput",
"type": "object"
}
```
## `flow_bake_logs`
Read bounded bake task logs with MCP-side credential redaction. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"attempt_no": {
"default": -1,
"title": "Attempt No",
"type": "integer"
},
"bake_id_or_name": {
"title": "Bake Id Or Name",
"type": "string"
},
"cluster": {
"title": "Cluster",
"type": "string"
},
"max_bytes": {
"default": 100000,
"title": "Max Bytes",
"type": "integer"
},
"max_chunks": {
"default": 100,
"title": "Max Chunks",
"type": "integer"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"task_id": {
"title": "Task Id",
"type": "string"
},
"timeout_seconds": {
"default": 60,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"bake_id_or_name",
"task_id",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_bake_logsArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_bake_logsDictOutput",
"type": "object"
}
```
## `flow_bake_wait`
Wait a bounded time for a bake attempt to terminate. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Read-only
**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`
**Input schema:**
```json
{
"properties": {
"attempt_no": {
"default": -1,
"title": "Attempt No",
"type": "integer"
},
"bake_id_or_name": {
"title": "Bake Id Or Name",
"type": "string"
},
"cluster": {
"title": "Cluster",
"type": "string"
},
"org": {
"title": "Org",
"type": "string"
},
"poll_interval_seconds": {
"default": 2,
"title": "Poll Interval Seconds",
"type": "number"
},
"project": {
"title": "Project",
"type": "string"
},
"task_limit": {
"default": 100,
"title": "Task Limit",
"type": "integer"
},
"timeout_seconds": {
"default": 300,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"bake_id_or_name",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_bake_waitArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_bake_waitDictOutput",
"type": "object"
}
```
## `flow_bake_cancel`
Cancel a bake attempt under the server mutation policy. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Destructive write
**Annotations:** read-only `false`, destructive `true`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"attempt_no": {
"default": -1,
"title": "Attempt No",
"type": "integer"
},
"bake_id_or_name": {
"title": "Bake Id Or Name",
"type": "string"
},
"cluster": {
"title": "Cluster",
"type": "string"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"task_limit": {
"default": 100,
"title": "Task Limit",
"type": "integer"
},
"timeout_seconds": {
"default": 300,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"bake_id_or_name",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_bake_cancelArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_bake_cancelDictOutput",
"type": "object"
}
```
## `flow_bake_restart`
Restart a bake through BatchRunner under the server mutation policy. workspace\_path is the Flow project root and must contain a real .apolo directory.
**Operation type:** Destructive write
**Annotations:** read-only `false`, destructive `true`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"attempt_no": {
"default": -1,
"title": "Attempt No",
"type": "integer"
},
"bake_id_or_name": {
"title": "Bake Id Or Name",
"type": "string"
},
"cluster": {
"title": "Cluster",
"type": "string"
},
"from_failed": {
"default": true,
"title": "From Failed",
"type": "boolean"
},
"local_executor": {
"default": false,
"title": "Local Executor",
"type": "boolean"
},
"org": {
"title": "Org",
"type": "string"
},
"project": {
"title": "Project",
"type": "string"
},
"task_limit": {
"default": 100,
"title": "Task Limit",
"type": "integer"
},
"timeout_seconds": {
"default": 300,
"title": "Timeout Seconds",
"type": "number"
},
"workspace_path": {
"title": "Workspace Path",
"type": "string"
}
},
"required": [
"bake_id_or_name",
"cluster",
"org",
"project",
"workspace_path"
],
"title": "flow_bake_restartArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "flow_bake_restartDictOutput",
"type": "object"
}
```