> ## 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. # Get workflow head files > Get the editable head rendered as a directory of files. Structural files carry inline content; user agent files are referenced by id. The returned `rev` can be supplied as `baseRev` to patch without a second fetch. ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /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: get: tags: - Files summary: Get workflow head files description: >- Get the editable head rendered as a directory of files. Structural files carry inline content; user agent files are referenced by id. The returned `rev` can be supplied as `baseRev` to patch without a second fetch. operationId: AgentWorkflowHeadGetFiles parameters: - description: The ID of the agent in: path name: agentId required: true schema: $ref: '#/components/schemas/Common.uuid' - description: >- Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus agent-file bytes within the response budget). Supersedes includeAgentFileContents when both are sent. explode: false in: query name: contents schema: $ref: '#/components/schemas/Agents.Workflow.WorkflowFileContentsMode' - description: >- Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip. in: query name: paths schema: items: type: string type: array - description: >- Narrow which variants// files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response's variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant. in: query name: variants schema: type: string - deprecated: true description: >- Fetch user agent-file bytes from storage and inline them as contentBase64, so the whole directory can be materialised in one request. Off by default, in which case agent files are returned as references. Files exceeding the per-file or per-response budget stay references even when this is set. Deprecated: superseded by `contents`. explode: false in: query name: includeAgentFileContents schema: type: boolean - description: >- Per-file ceiling, in bytes, for inlined agent-file contents. Clamped to the server maximum; a caller with tighter limits of its own passes them here so the response does not carry bytes it will discard. Files above the ceiling stay references. explode: false in: query name: maxFileBytes schema: format: int64 type: integer - description: >- Ceiling, in bytes, on the total inlined agent-file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references. explode: false in: query name: maxTotalBytes schema: format: int64 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/Agents.Workflow.WorkflowFileTree' 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. '500': content: application/json: schema: $ref: '#/components/schemas/Common.InternalServerErrorBody' description: Server error components: schemas: Common.uuid: format: uuid type: string Agents.Workflow.WorkflowFileContentsMode: description: Which file contents a tree read carries inline. enum: - none - structural - all type: string Agents.Workflow.WorkflowFileTree: description: >- A workflow rendered as a directory of files. Structural files are derived from the structured workflow and carry inline content; user agent files are referenced by id. properties: agentName: description: >- The owning agent's name. The directory is rendered relative to the workflow root, so a client that lays it out under a per-agent folder needs the name to derive that folder — and would otherwise have to fetch the agent for it. type: string files: description: The files in the workflow, sorted by path. items: $ref: '#/components/schemas/Agents.Workflow.WorkflowFileEntry' type: array rev: description: >- The revision the tree reflects. For the editable head, supply this as `baseRev` when patching; a stale value is rejected with 409. type: integer variantKeys: description: >- Every variant key the workflow's files carry, sorted, regardless of any variants filter on the read — a narrowed tree still names what it could ask for. Absent unless the workflow has variant mode enabled. items: type: string type: array version: description: >- The workflow's version number, absent for a draft that has never been published. type: integer workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The id of the workflow this tree renders. Lets a client that materialises the directory record what it holds without a second fetch. required: - rev - workflowId - agentName - files 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.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError message: type: string required: - code - message type: object Agents.Workflow.WorkflowFileEntry: description: A single entry in a workflow's directory-of-files representation. properties: checksum: description: >- Hex-encoded SHA-256 of the file contents, when known. Lets a client materialising the directory skip files it already has. Absent for structural files, whose content is inlined anyway. type: string content: description: >- Inline UTF-8 content. Present for structural files only, and omitted under `contents=none`; agent files carry their bytes in contentBase64, since arbitrary uploads are not guaranteed to be valid UTF-8. type: string contentBase64: description: >- Base64-encoded file bytes. Present only for agent files, and only when `contents=all` (or the deprecated `includeAgentFileContents=true`) and the file fits the response budget. Absent when contents were not requested, the file exceeded the budget, or storage could not be read — fall back to the workflow agent-file download endpoints using fileId. type: string downloadUrl: description: >- For an agent file: a URL that redirects to a short-lived signed URL for the file's bytes. Browser clients with no bucket access use this to preview, download and diff files the response did not inline. Absent for structural files, whose content is inlined, and on the internal surface, whose callers read a skipped file straight from storage by `storageObjectKey`. format: uri type: string fileId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- For an agent file: the id used to fetch its content via the workflow agent-file endpoints. kind: allOf: - $ref: '#/components/schemas/Agents.Workflow.WorkflowFileKind' description: >- Whether this is a derived structural file (content inlined) or a user agent file (referenced by fileId). mimeType: description: The file's MIME type, when known. type: string path: description: >- The file path, relative to the workflow root (e.g. `settings.yaml`, `nodes/login/instructions.md`). type: string size: description: The file size in bytes. format: int64 type: integer storageObjectKey: description: >- For an agent file: the object key of its blob in the agents bucket. A caller with bucket access (astro-agent) reads a file the response budget skipped straight from storage, instead of a signed-URL mint plus a download redirect. Absent for structural files, which have no blob. type: string updatedAt: description: 'For an agent file: when its contents were last written.' format: date-time type: string required: - path - kind - size type: object Agents.Workflow.WorkflowFileKind: description: The kind of file in a workflow's directory representation. enum: - structural - agent_file type: string securitySchemes: ApiKeyAuth: in: header name: X-Asteroid-Agents-Api-Key type: apiKey ````