ASasteroid
Files

Get workflow head files

Get the editable head rendered as a directory of files. Structural files carry inline content; the workflow's own files are referenced by id. The returned rev can be supplied as baseRev to patch without a second fetch.

get/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

Path parameters

workflowIdstring uuid required

Query parameters

contents'none' | 'structural' | 'all'

Which file contents a tree read carries inline.

Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).

pathsstring[]

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.

variantsstring

Narrow which variants/<key>/ 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.

maxFileBytesinteger

Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.

maxTotalBytesinteger

Ceiling, in bytes, on the total inlined 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.

Response

The request has succeeded.

contentHashstring

Hex-encoded SHA-256 over the workflow's whole file directory: every structural file's path and content, and every agent file's path and checksum. It covers the whole workflow regardless of any paths, variants or contents narrowing on the read, so two reads of the same workflow always agree. A client keeping the directory in version control compares this one string to answer "does the published agent still match my checkout?" instead of diffing every file. Absent when an agent file has no checksum yet, since the tree cannot then be hashed in full.

revinteger required

The revision the tree reflects. For the editable head, supply this as baseRev when patching. Agent-file-only patches overlay the current head if it has moved; structural-file patches are rejected with 409 when stale.

variantKeysstring[]

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.

versioninteger

The workflow's version number, absent for a draft that has never been published.

versionIdstring uuid required
workflowIdstring uuid required
workflowNamestring required

The workflow's name. The directory is rendered relative to the workflow root, so a client that lays it out under a per-workflow folder needs the name to derive that folder — and would otherwise have to fetch the workflow for it.

Changes

No recorded changes to this operation across all 1 revision of this API.