> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt > Use this file to discover all available pages before exploring further. # Patch workflow head files > 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. ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml patch /workflows/{workflowId}/head/files openapi: 3.1.0 info: title: Agent Service version: v1 servers: - description: V2 API url: https://odyssey.asteroid.ai/agents/v2 security: - ApiKeyAuth: [] tags: - name: Agents - name: Environments - name: Schedules - name: Execution - name: Files - name: Profiles - name: Profile Groups - name: Agent Profiles - name: Agent Profile Pools - name: Workflows - name: Execution Batches - name: Scheduled Executions - name: Schema - name: Documentation - name: Context - name: Admin Customer Activity - name: Reference - name: Workflow Tags - name: Secrets - name: Vault - name: Workflow Versions paths: /workflows/{workflowId}/head/files: patch: tags: - Files summary: Patch workflow head files description: >- 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. operationId: WorkflowHeadPatchFiles parameters: - description: The ID of the workflow in: path name: workflowId required: true schema: $ref: '#/components/schemas/Common.uuid' requestBody: content: application/json: schema: $ref: '#/components/schemas/Workflows.Version.FilesPatchRequest' description: The file writes and deletes to apply required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Workflows.Version.Snapshot' description: The request has succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/Common.BadRequestErrorBody' description: The server could not understand the request due to invalid syntax. '401': content: application/json: schema: $ref: '#/components/schemas/Common.UnauthorizedErrorBody' description: Access is unauthorized. '403': content: application/json: schema: $ref: '#/components/schemas/Common.ForbiddenErrorBody' description: Access is forbidden. '404': content: application/json: schema: $ref: '#/components/schemas/Common.NotFoundErrorBody' description: The server cannot find the requested resource. '409': content: application/json: schema: $ref: '#/components/schemas/Common.ConflictErrorBody' description: The request conflicts with the current state of the server. '500': content: application/json: schema: $ref: '#/components/schemas/Common.InternalServerErrorBody' description: Server error components: schemas: Common.uuid: format: uuid type: string Workflows.Version.FilesPatchRequest: description: Request to patch the editable head's file representation properties: baseRev: description: >- 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. type: integer deletes: description: Paths of files to delete. items: type: string type: array writes: description: Files to upsert. items: $ref: '#/components/schemas/Agents.Workflow.WorkflowFileWrite' type: array required: - baseRev - writes - deletes type: object Workflows.Version.Snapshot: description: An immutable snapshot of a workflow's configuration properties: author: description: The email of the user who created this workflow. type: string createdAt: description: >- 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. format: date-time type: string environmentTemplate: allOf: - $ref: '#/components/schemas/Agents.Workflow.ExternalEnvironmentTemplate' description: >- Optional environment template. Defaults to browser/anchor if not provided. files: description: >- The files stored on this workflow version. Empty when the workflow has no files. items: $ref: '#/components/schemas/Agents.Workflow.WorkflowFile' type: array graph: allOf: - $ref: '#/components/schemas/Agents.Graph.Models.AgentGraph' description: The workflow graph id: allOf: - $ref: '#/components/schemas/Common.uuid' description: The unique ID of this workflow inputs: description: >- Typed input definitions for workflow execution. Includes names referenced in prompts, which default to optional strings. items: $ref: '#/components/schemas/Agents.Workflow.Input' type: array isPublished: description: >- Whether this is the workflow's published version (the API default). At most one version per workflow is published. type: boolean parentId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The ID of the parent workflow this was derived from (for lineage tracking) rev: description: >- 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. type: integer rules: description: The rules/instructions for this workflow type: string settings: allOf: - $ref: '#/components/schemas/Agents.Graph.Models.ExternalSettings' description: The settings for this version version: description: The monotonic per-workflow version number. type: integer workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The ID of the workflow this version belongs to required: - id - version - isPublished - rules - graph - inputs - files - createdAt - rev - workflowId - settings type: object Common.BadRequestErrorBody: properties: code: enum: - 400 type: number x-enum-varnames: - BadRequest detail: description: Explanation of this occurrence. Same text as message type: string errors: description: The parameters that failed validation, when known items: $ref: '#/components/schemas/Common.FieldError' type: array instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.UnauthorizedErrorBody: properties: code: enum: - 401 type: number x-enum-varnames: - Unauthorized detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.ForbiddenErrorBody: properties: code: enum: - 403 type: number x-enum-varnames: - Forbidden detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.NotFoundErrorBody: properties: code: enum: - 404 type: number x-enum-varnames: - NotFound detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.ConflictErrorBody: properties: code: enum: - 409 type: number x-enum-varnames: - Conflict detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Agents.Workflow.WorkflowFileWrite: description: >- A single file write in a files patch: upsert the file at `path`. Content is base64 uniformly — structural files decode as UTF-8, agent files are arbitrary bytes — so one write shape carries both. properties: contentBase64: description: Base64-encoded file content. type: string path: description: >- The file path, relative to the workflow root — the same paths the file tree returns. type: string required: - path - contentBase64 type: object Agents.Workflow.ExternalEnvironmentTemplate: description: Environment template on the external API. Omits admin-only OS fields. properties: config: anyOf: - $ref: '#/components/schemas/Agents.Workflow.BrowserTemplateConfig' - $ref: '#/components/schemas/Agents.Workflow.ExternalOsTemplateConfig' description: Environment-specific configuration type: allOf: - $ref: '#/components/schemas/Agents.Workflow.EnvironmentType' description: Type of environment (browser or os) required: - type - config type: object Agents.Workflow.WorkflowFile: description: >- A file stored on a workflow version. Content is fetched via the workflow-scoped shared-file download endpoints using this id. properties: checksum: description: Hex-encoded SHA-256 of the file contents, when known type: string createdAt: description: When this file was first added to the workflow lineage format: date-time type: string fileName: description: The file's base name type: string filePath: description: The file path, relative to the workflow's shared directory type: string fileSize: description: The file size in bytes format: int64 type: integer id: allOf: - $ref: '#/components/schemas/Common.uuid' description: The unique ID of this file within the workflow version mimeType: description: The file's MIME type, when known type: string updatedAt: description: When this file was last modified format: date-time type: string required: - id - filePath - fileName - fileSize - createdAt - updatedAt type: object Agents.Graph.Models.AgentGraph: properties: nodes: items: $ref: '#/components/schemas/Agents.Graph.Models.Nodes.Node' type: array sticky_notes: items: $ref: '#/components/schemas/Agents.Graph.Models.StickyNote' type: array transitions: items: $ref: '#/components/schemas/Agents.Graph.Models.Transitions.Transition' type: array required: - nodes - transitions - sticky_notes type: object Agents.Workflow.Input: description: >- A typed input variable a workflow declares. Referenced as {{.name}} in prompts. properties: defaultValue: description: Optional value used when the input is omitted at execution time. description: description: Optional human-readable description of the input. type: string name: description: >- The variable name. Matches [a-zA-Z_][a-zA-Z0-9_]* and is unique within the workflow. pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: string required: description: >- Whether a value must be supplied at execution time. Defaults to false. type: boolean schema: description: >- 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. type: object unevaluatedProperties: {} required: - name - schema - required type: object Agents.Graph.Models.ExternalSettings: description: Configuration settings for workflow execution properties: custom_environment_id: anyOf: - type: string - type: 'null' description: >- 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. format: uuid max_timeout_mins: description: Maximum timeout in minutes type: integer viewport_height: description: Browser viewport height in pixels type: integer viewport_width: description: Browser viewport width in pixels type: integer required: - viewport_width - viewport_height - max_timeout_mins type: object Common.FieldError: description: A problem with one request parameter properties: detail: description: What is wrong with it type: string parameter: description: The query or path parameter name type: string required: - parameter - detail type: object Agents.Workflow.BrowserTemplateConfig: description: Customer-facing browser environment template configuration properties: provider: allOf: - $ref: '#/components/schemas/Agents.Workflow.BrowserProvider' deprecated: true description: >- Ignored, and always anchor. Kept so SDKs released before it was dropped still parse. required: - provider type: object Agents.Workflow.ExternalOsTemplateConfig: description: >- Customer-facing OS environment template configuration. Admin-only fields live on OsTemplateConfig. properties: osType: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsType' description: >- Operating system the sandbox runs. Defaults to linux. Setting to windows is admin-only and selects the Windows snapshot/image. provider: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsProvider' description: OS provider type public: deprecated: true description: >- Ignored and always false. Kept so SDKs released before it was dropped still parse. type: boolean snapshotName: deprecated: true description: >- Ignored, and never returned. A workflow boots the snapshot of the custom environment it is bound to, or the default image. type: string required: - provider - public type: object Agents.Workflow.EnvironmentType: description: Type of execution environment enum: - browser - os type: string Agents.Graph.Models.Nodes.Node: properties: description: deprecated: true description: 'Deprecated: field is no longer populated and will be removed.' type: string id: $ref: '#/components/schemas/Common.uuid' name: description: >- 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). type: string position: $ref: '#/components/schemas/Agents.Graph.Models.Nodes.Position' properties: $ref: '#/components/schemas/Agents.Graph.Models.Nodes.NodePropertiesUnion' type: $ref: '#/components/schemas/Agents.Graph.Models.Nodes.NodeType' required: - id - name - type - properties type: object Agents.Graph.Models.StickyNote: properties: color: type: string content: type: string id: $ref: '#/components/schemas/Common.uuid' position: $ref: '#/components/schemas/Agents.Graph.Models.Nodes.Position' size: $ref: '#/components/schemas/Agents.Graph.Models.Nodes.Size' required: - id - content type: object Agents.Graph.Models.Transitions.Transition: properties: description: type: string from: $ref: '#/components/schemas/Common.uuid' id: $ref: '#/components/schemas/Common.uuid' properties: $ref: >- #/components/schemas/Agents.Graph.Models.Transitions.TransitionPropertiesUnion require_confirmation: type: boolean schema: type: object unevaluatedProperties: {} to: $ref: '#/components/schemas/Common.uuid' type: $ref: '#/components/schemas/Agents.Graph.Models.Transitions.TransitionType' required: - id - from - to - type - require_confirmation - properties type: object Agents.Workflow.BrowserProvider: description: Browser provider type enum: - anchor type: string Agents.Workflow.OsType: description: Operating system the environment sandbox runs enum: - linux - windows type: string Agents.Workflow.OsProvider: description: OS provider type enum: - daytona - local type: string Agents.Graph.Models.Nodes.Position: properties: x: format: int32 type: integer 'y': format: int32 type: integer required: - x - 'y' type: object Agents.Graph.Models.Nodes.NodePropertiesUnion: discriminator: mapping: api: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.APIProperties iris: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.IrisProperties output: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.OutputProperties playwright_script: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.PlaywrightScriptProperties start: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.StartProperties url: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.URLProperties propertyName: type oneOf: - $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.StartProperties - $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.IrisProperties - $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.PlaywrightScriptProperties - $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.APIProperties - $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.URLProperties - $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.OutputProperties type: object Agents.Graph.Models.Nodes.NodeType: enum: - start - iris - playwright_script - api - url - output type: string Agents.Graph.Models.Nodes.Size: properties: height: format: int32 type: integer width: format: int32 type: integer required: - width - height type: object Agents.Graph.Models.Transitions.TransitionPropertiesUnion: discriminator: mapping: iris: >- #/components/schemas/Agents.Graph.Models.Transitions.Properties.IrisProperties outcome_success: >- #/components/schemas/Agents.Graph.Models.Transitions.Properties.OutcomeSuccessProperties selector: >- #/components/schemas/Agents.Graph.Models.Transitions.Properties.SelectorProperties propertyName: type oneOf: - $ref: >- #/components/schemas/Agents.Graph.Models.Transitions.Properties.IrisProperties - $ref: >- #/components/schemas/Agents.Graph.Models.Transitions.Properties.SelectorProperties - $ref: >- #/components/schemas/Agents.Graph.Models.Transitions.Properties.OutcomeSuccessProperties type: object Agents.Graph.Models.Transitions.TransitionType: enum: - iris - selector - outcome_success type: string Agents.Graph.Models.Nodes.Properties.APIProperties: deprecated: true properties: body: type: object unevaluatedProperties: {} headers: type: object unevaluatedProperties: type: string method: $ref: '#/components/schemas/Agents.Graph.Models.Nodes.Properties.APIMethod' type: enum: - api type: string url: type: string required: - type - method - url - body - headers type: object Agents.Graph.Models.Nodes.Properties.IrisProperties: properties: capabilities: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.NodeCapabilities compression_strategies: items: type: string type: array input_schema: type: object unevaluatedProperties: {} instructions: type: string model: type: string x-go-type: llmtypes.Model x-go-type-import: name: llmtypes path: github.com/asteroidai/agents/go/common/llmtypes playwright_script_properties: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.IrisPlaywrightScriptProperties script_failure_action: description: |- 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. enum: - fallback_to_ai - cancel_execution type: string script_filepath: description: >- 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`. - 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/`. maxLength: 512 minLength: 1 pattern: ^(?!\/)(?!shared\/)(?!.*\.\.(?:\/|$))(?!.*\/\/)[^/].*\.js$ type: string thinking_budget_tokens: minimum: 1 type: integer thinking_effort: enum: - low - medium - high - max type: string thinking_mode: enum: - adaptive - enabled - disabled type: string type: enum: - iris type: string required: - type - instructions - model type: object Agents.Graph.Models.Nodes.Properties.OutputProperties: properties: instructions: type: string instructionsEnabled: type: boolean model: type: string x-go-type: llmtypes.Model x-go-type-import: name: llmtypes path: github.com/asteroidai/agents/go/common/llmtypes outcomes: items: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.OutcomeString minItems: 1 type: array schema: type: object unevaluatedProperties: {} type: enum: - output type: string required: - type - outcomes type: object Agents.Graph.Models.Nodes.Properties.PlaywrightScriptProperties: properties: llm_vars: items: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.PlaywrightScriptLLMVar type: array script: type: string type: enum: - playwright_script type: string required: - type - script - llm_vars type: object Agents.Graph.Models.Nodes.Properties.StartProperties: properties: type: enum: - start type: string required: - type type: object Agents.Graph.Models.Nodes.Properties.URLProperties: deprecated: true properties: type: enum: - url type: string url: type: string required: - type - url type: object Agents.Graph.Models.Transitions.Properties.IrisProperties: properties: type: enum: - iris type: string required: - type type: object Agents.Graph.Models.Transitions.Properties.OutcomeSuccessProperties: properties: type: enum: - outcome_success type: string required: - type type: object Agents.Graph.Models.Transitions.Properties.SelectorProperties: properties: name: type: string selectors: items: type: string minItems: 1 type: array type: enum: - selector type: string required: - type - name - selectors type: object Agents.Graph.Models.Nodes.Properties.APIMethod: enum: - GET - POST - PUT - DELETE type: string Agents.Graph.Models.Nodes.Properties.NodeCapabilities: description: Coarse environment-level capability toggles for an AI node. properties: ask_user_question: type: boolean browser_use: type: boolean computer_use: type: boolean required: - browser_use - computer_use - ask_user_question type: object Agents.Graph.Models.Nodes.Properties.IrisPlaywrightScriptProperties: properties: freeze_script: type: boolean llm_vars: items: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.PlaywrightScriptLLMVar type: array script: type: string required: - script - llm_vars - freeze_script type: object Agents.Graph.Models.Nodes.Properties.OutcomeString: maxLength: 30 minLength: 1 pattern: ^[a-z0-9_]{1,30}$ type: string Agents.Graph.Models.Nodes.Properties.PlaywrightScriptLLMVar: properties: description: type: string name: type: string type: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.PlaywrightScriptLLMVarType required: - name - type - description type: object Agents.Graph.Models.Nodes.Properties.PlaywrightScriptLLMVarType: enum: - string - number - boolean type: string securitySchemes: ApiKeyAuth: in: header name: X-Api-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.