--- title: "Patch workflow head files" method: PATCH path: "/agents/v2/workflows/{workflowId}/head/files" tags: ["Files"] --- # Patch workflow head files `PATCH /agents/v2/workflows/{workflowId}/head/files` ## Request - Base URL: `https://odyssey.asteroid.ai` - URL: `https://odyssey.asteroid.ai/agents/v2/workflows/{workflowId}/head/files` - Auth: API key in header `X-Api-Key` Patch the editable head's file representation in place: apply file writes and deletes, re-derive the structured workflow, and persist it. Structural-file writes require a matching baseRev. When the head is frozen (published or executed) the edit forks a fresh version behind the scenes. ## Path parameters - `workflowId` string, uuid, required ## Request body - WorkflowsVersionFilesPatchRequest: Request to patch the editable head's file representation - `baseRev` integer, required: The revision this edit is based on. Agent-file-only patches overlay the current head even when this is stale. A structural-file patch is rejected with 409 when it does not match the stored head revision. - `deletes` string[], required - `writes` AgentsWorkflowWorkflowFileWrite[], required: Files to upsert. - `content` string: The file as UTF-8 text, for text files such as settings.yaml, instructions.md, JSON schemas and scripts. Set this or contentBase64, not both. - `contentBase64` string: The file as base64-encoded bytes, for any file, binary included. Set this or content, not both. - `path` string, required: The file path, relative to the workflow root — the same paths the file tree returns. ## Response `200` The request has succeeded. - WorkflowsVersionSnapshot: An immutable snapshot of a workflow's configuration - `author` string: The email of the user who created this workflow. - `createdAt` string, date-time, required: When this workflow was created. For the editable head this is restamped on each in-place edit, so it doubles as the last-edited time. - `environmentTemplate` AgentsWorkflowExternalEnvironmentTemplate: Environment template on the external API. Omits admin-only OS fields. - `config` union, required - AgentsWorkflowBrowserTemplateConfig: Customer-facing browser environment template configuration - `provider` 'anchor', required: Browser provider type - AgentsWorkflowExternalOsTemplateConfig: Customer-facing OS environment template configuration. Admin-only fields live on OsTemplateConfig. - `osType` 'linux' | 'windows' | 'citrix': Operating system the environment sandbox runs - `provider` 'daytona' | 'local', required: OS provider type - `public` boolean, required: Ignored and always false. Kept so SDKs released before it was dropped still parse. - `snapshotName` string: Ignored, and never returned. A workflow boots the snapshot of the custom environment it is bound to, or the default image. - `type` 'browser' | 'os', required: Type of execution environment - `files` AgentsWorkflowWorkflowFile[], required: The files stored on this workflow version. Empty when the workflow has no files. - `checksum` string: Hex-encoded SHA-256 of the file contents, when known - `createdAt` string, date-time, required: When this file was first added to the workflow lineage - `fileName` string, required - `filePath` string, required: The file path, relative to the workflow's shared directory - `fileSize` integer, required: The file size in bytes - `id` string, uuid, required - `mimeType` string: The file's MIME type, when known - `updatedAt` string, date-time, required - `graph` AgentsGraphModelsAgentGraph, required - `nodes` AgentsGraphModelsNodesNode[], required - `description` string: Deprecated: field is no longer populated and will be removed. - `id` string, uuid, required - `name` string, required: Display name. New and renamed nodes accept letters, digits, spaces, and hyphens only (historical versions may carry other characters, so responses are not pattern-constrained). - `position` AgentsGraphModelsNodesPosition - `x` integer, required - `y` integer, required - `properties` union, required - object - `type` 'start', required - object - `capabilities` AgentsGraphModelsNodesPropertiesNodeCapabilities: Coarse environment-level capability toggles for an AI node. - `ask_user_question` boolean, required - `browser_use` boolean, required - `computer_use` boolean, required - `compression_strategies` string[] - `input_schema` object - `instructions` string, required - `model` string, required - `playwright_script_properties` AgentsGraphModelsNodesPropertiesIrisPlaywrightScriptProperties - `freeze_script` boolean, required - `llm_vars` AgentsGraphModelsNodesPropertiesPlaywrightScriptLLMVar[], required - … - `script` string, required - `script_failure_action` 'fallback_to_ai' | 'cancel_execution': What happens when a script fails on a scripted node. `fallback_to_ai` (default): fall back to LLM-driven execution. `cancel_execution`: cancel the execution immediately. - `script_filepath` string: Relative path (within the node's own shared directory) of the Playwright script that the runtime should execute before the LLM. Setting this turns the node into a fast-path scripted node — combine with `script_failure_action: "cancel_execution"` to skip the LLM entirely on success and cancel on failure. The path is resolved at runtime against the node's shared directory — i.e. `shared//` on disk in the sandbox. `` is owned by the runtime (currently the node's slug, may move to its UUID), so authors do not have to encode it and renaming a node does not break the path. Examples (typical): - `./scripts/main.js` - `./scripts/login.js` A leading `./` is optional but canonical — both `scripts/main.js` and `./scripts/main.js` are accepted, and the platform normalizes to the `./`-prefixed form when it writes this value back out. Constraints: - Must be relative (no leading `/`). - Must NOT start with `shared/` — it is already relative to the node's shared directory; the runtime adds the `shared//` prefix. - Must end in `.js` (Playwright, browser), `.ps1` (PowerShell, Windows desktop) or `.sh` (bash, Linux desktop). - Must not contain `..` segments or duplicate slashes. - May contain a single `{{variant_key}}` placeholder, which the runtime substitutes with the execution's `variant_key` so a single workflow can target per-tenant script trees (e.g. `./variants/{{variant_key}}/scripts/main.js` → `shared//variants//scripts/main.js`). Requires the agent to have `variant_mode` enabled, and the placeholder must be the segment directly under `variants/`. - `thinking_budget_tokens` integer - `thinking_effort` 'low' | 'medium' | 'high' | 'max' - `thinking_mode` 'adaptive' | 'enabled' | 'disabled' - `type` 'iris', required - object - `llm_vars` AgentsGraphModelsNodesPropertiesPlaywrightScriptLLMVar[], required - `description` string, required - `name` string, required - `type` 'string' | 'number' | 'boolean', required - `script` string, required - `type` 'playwright_script', required - object - `body` object, required - `headers` object, required - `method` 'GET' | 'POST' | 'PUT' | 'DELETE', required - `type` 'api', required - `url` string, required - object - `type` 'url', required - `url` string, required - object - `instructions` string - `instructionsEnabled` boolean - `model` string - `outcomes` AgentsGraphModelsNodesPropertiesOutcomeString[], required - `schema` object - `type` 'output', required - `type` 'start' | 'iris' | 'playwright_script' | 'api' | 'url' | 'output', required - `sticky_notes` AgentsGraphModelsStickyNote[], required - `color` string - `content` string, required - `id` string, uuid, required - `position` AgentsGraphModelsNodesPosition - `x` integer, required - `y` integer, required - `size` AgentsGraphModelsNodesSize - `height` integer, required - `width` integer, required - `transitions` AgentsGraphModelsTransitionsTransition[], required - `description` string - `from` string, uuid, required - `id` string, uuid, required - `properties` union, required - object - `type` 'iris', required - object - `name` string, required - `selectors` string[], required - `type` 'selector', required - object - `type` 'outcome_success', required - `require_confirmation` boolean, required - `schema` object - `to` string, uuid, required - `type` 'iris' | 'selector' | 'outcome_success', required - `id` string, uuid, required - `inputs` AgentsWorkflowInput[], required: Typed input definitions for workflow execution. Includes names referenced in prompts, which default to optional strings. - `defaultValue` unknown - `description` string - `name` string, required: The variable name. Matches [a-zA-Z_][a-zA-Z0-9_]* and is unique within the workflow. - `required` boolean, required: Whether a value must be supplied at execution time. Defaults to false. - `schema` object, required: A single-field JSON Schema fragment describing the input's type, e.g. {type: "string"}, {type: "number"}, {type: "object", properties: {...}}. Validated adaptively at execution time. - `isPublished` boolean, required: Whether this is the workflow's published version (the API default). At most one version per workflow is published. - `issues` AgentsWorkflowWorkflowValidationIssue[]: The validation findings publish and run would report for this version, as `workflow head validate` lists them. Set on the response to a head files patch; absent elsewhere. - `message` string, required - `path` string[], required: Path to the offending field, e.g. ["nodes", "My Node", "model"]. - `severity` 'error' | 'warning', required: Severity of a workflow validation issue. Error-severity issues make the workflow un-runnable; warnings are advisory. - `parentId` string, uuid - `rev` integer, required: Monotonic optimistic-concurrency revision. Only meaningful for the editable head: supply it as baseRev on the next head patch. Agent-file-only patches overlay the current head if it has moved; structural-file patches are rejected with 409 when stale. Frozen snapshots never receive in-place patches. - `rules` string, required - `settings` AgentsGraphModelsExternalSettings, required: Configuration settings for workflow execution - `custom_environment_id` string, uuid, nullable: Custom environment executions of this workflow boot on: its environment type and snapshot replace the workflow's own environment, its profile rows restrict which profile an execution may use, and a kept-warm environment hands out a pre-warmed copy. On a new version, omit it to keep the environment of the workflow's latest version (its editable head, which can be newer than the published one), or send null to boot the workflow's own environment. On a new workflow, there is nothing to keep: omit it or send null for no custom environment. - `max_timeout_mins` integer, required: Maximum timeout in minutes - `viewport_height` integer, required: Browser viewport height in pixels - `viewport_width` integer, required: Browser viewport width in pixels - `version` integer, required: The monotonic per-workflow version number. - `workflowId` string, uuid, required ## Other responses - `400`: The server could not understand the request due to invalid syntax. - `401`: Access is unauthorized. - `403`: Access is forbidden. - `404`: The server cannot find the requested resource. - `409`: The request conflicts with the current state of the server. - `500`: Server error --- [API](https://skmtc.dev/asteroid/apis/agent-service.md) - [All operations](https://skmtc.dev/asteroid/apis/agent-service/llms.txt) - [OpenAPI document](https://skmtc.dev/asteroid/apis/agent-service/revisions/ccc134d1d510?raw)