> ## 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/deletes, re-derive the structured workflow, and persist it. Structural files re-derive the graph; agent files go to the blob store. Guarded by baseRev for optimistic concurrency. 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 /agents/{agentId}/workflow-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: Execution - name: Files - 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 paths: /agents/{agentId}/workflow-head/files: patch: tags: - Files summary: Patch workflow head files description: >- Patch the editable head's file representation in place: apply file writes/deletes, re-derive the structured workflow, and persist it. Structural files re-derive the graph; agent files go to the blob store. Guarded by baseRev for optimistic concurrency. When the head is frozen (published or executed) the edit forks a fresh version behind the scenes. operationId: AgentWorkflowHeadPatchFiles parameters: - description: The ID of the agent in: path name: agentId required: true schema: $ref: '#/components/schemas/Common.uuid' requestBody: content: application/json: schema: $ref: '#/components/schemas/Agents.Workflow.WorkflowFilesPatchRequest' description: The file writes and deletes to apply required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Agents.Workflow.ExternalWorkflowSnapshot' 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 Agents.Workflow.WorkflowFilesPatchRequest: description: >- Request to patch the editable head's file representation. The server classifies each path: structural files re-derive the structured workflow, the agent's own files (memory, uploads, node scripts) go to their blob store — the client just writes files. Rev-guarded by `baseRev`: a stale value is rejected with 409. properties: baseRev: description: >- The revision this edit is based on. The patch only applies when it still matches the stored head revision; otherwise it is rejected with 409. 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 Agents.Workflow.ExternalWorkflowSnapshot: description: >- A workflow (commit) representing an immutable snapshot of agent configuration properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The agent ID this workflow belongs to 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.EnvironmentTemplate' 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 snapshot is the agent's published version (the API default). At most one snapshot per agent 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; a stale baseRev is rejected with 409. 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 workflow version: description: The monotonic per-agent snapshot version number. type: integer required: - id - agentId - version - isPublished - rules - graph - inputs - files - createdAt - rev - settings type: object Common.BadRequestErrorBody: properties: code: enum: - 400 type: number x-enum-varnames: - BadRequest message: type: string required: - code - message type: object Common.UnauthorizedErrorBody: properties: code: enum: - 401 type: number x-enum-varnames: - Unauthorized message: type: string required: - code - message type: object Common.ForbiddenErrorBody: properties: code: enum: - 403 type: number x-enum-varnames: - Forbidden message: type: string required: - code - message type: object Common.NotFoundErrorBody: properties: code: enum: - 404 type: number x-enum-varnames: - NotFound message: type: string required: - code - message type: object Common.ConflictErrorBody: properties: code: enum: - 409 type: number x-enum-varnames: - Conflict message: type: string required: - code - message type: object Common.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError message: 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.EnvironmentTemplate: description: Environment template for workflow execution properties: config: anyOf: - $ref: '#/components/schemas/Agents.Workflow.BrowserTemplateConfig' - $ref: '#/components/schemas/Agents.Workflow.OsTemplateConfig' 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 agent'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: max_timeout_mins: description: Maximum timeout in minutes type: integer new_agent_loop: description: Whether to use the new agent loop for execution (beta) type: boolean 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 Agents.Workflow.BrowserTemplateConfig: description: Browser environment template configuration properties: provider: allOf: - $ref: '#/components/schemas/Agents.Workflow.BrowserProvider' description: Browser provider type required: - provider type: object Agents.Workflow.OsTemplateConfig: description: OS environment template configuration 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: description: Whether the snapshot is public type: boolean snapshotName: description: >- Name of the snapshot to use. If omitted or empty, the server uses the configured default snapshot for the selected osType. 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 - steel 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: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.APIProperties iris: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.IrisProperties output: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.OutputProperties playwright_script: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.PlaywrightScriptProperties start: $ref: >- #/components/schemas/Agents.Graph.Models.Nodes.Properties.StartProperties url: $ref: >- #/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: $ref: >- #/components/schemas/Agents.Graph.Models.Transitions.Properties.IrisProperties outcome_success: $ref: >- #/components/schemas/Agents.Graph.Models.Transitions.Properties.OutcomeSuccessProperties selector: $ref: >- #/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-Asteroid-Agents-Api-Key type: apiKey ````