HUD Storage API
The storage API from HUD — 3 operation(s) for storage.
The storage API from HUD — 3 operation(s) for storage.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/hud-ai:hud-ai-storage-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: HUD Platform Storage API
version: 2.0.0
tags:
- name: Storage
paths:
/v2/storage/traces/{trace_id}/artifacts:
get:
tags:
- Storage
summary: List Trace Artifacts
description: List trace-owned screenshots, recordings, and captured files.
operationId: list_trace_artifacts_v2_storage_traces__trace_id__artifacts_get
parameters:
- name: trace_id
in: path
required: true
schema:
type: string
format: uuid
title: Trace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TraceStorageObjectListResponse'
'400':
description: Invalid or malformed request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Caller may not access this resource
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Referenced entity does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Resource already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded; wait at least Retry-After seconds
headers:
Retry-After:
description: Seconds until the request budget has room
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: The server is at capacity; retry after Retry-After seconds
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/storage/traces/{trace_id}/workspace/changes:
get:
tags:
- Storage
summary: Trace Workspace Changes
description: Return filetracking snapshots, patches, and captured files for a trace.
operationId: trace_workspace_changes_v2_storage_traces__trace_id__workspace_changes_get
parameters:
- name: trace_id
in: path
required: true
schema:
type: string
format: uuid
title: Trace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TraceWorkspaceChangesResponse'
'400':
description: Invalid or malformed request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Caller may not access this resource
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Referenced entity does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Resource already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded; wait at least Retry-After seconds
headers:
Retry-After:
description: Seconds until the request budget has room
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: The server is at capacity; retry after Retry-After seconds
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/storage/traces/{trace_id}/workspace/files:
get:
tags:
- Storage
summary: Trace Workspace Files
description: Return final captured file contents for a trace workspace.
operationId: trace_workspace_files_v2_storage_traces__trace_id__workspace_files_get
parameters:
- name: trace_id
in: path
required: true
schema:
type: string
format: uuid
title: Trace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TraceWorkspaceFilesResponse'
'400':
description: Invalid or malformed request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Caller may not access this resource
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Referenced entity does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Resource already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded; wait at least Retry-After seconds
headers:
Retry-After:
description: Seconds until the request budget has room
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: The server is at capacity; retry after Retry-After seconds
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
TraceWorkspaceChangesResponse:
properties:
trace_id:
type: string
format: uuid
title: Trace Id
events:
items:
anyOf:
- $ref: '#/components/schemas/FileSnapshotEvent'
- $ref: '#/components/schemas/FileSetupEvent'
- $ref: '#/components/schemas/FileChangeEvent'
- $ref: '#/components/schemas/FileCaptureEvent'
type: array
title: Events
type: object
required:
- trace_id
- events
title: TraceWorkspaceChangesResponse
FileSnapshotEvent:
properties:
id:
type: string
title: Id
parent_id:
anyOf:
- type: string
- type: 'null'
title: Parent Id
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
seq:
type: integer
title: Seq
default: 0
kind:
type: string
const: file_snapshot
title: Kind
files_scanned:
type: integer
title: Files Scanned
default: 0
truncated:
type: boolean
title: Truncated
default: false
files:
items:
$ref: '#/components/schemas/FileManifestEntry'
type: array
title: Files
default: []
additionalProperties: false
type: object
required:
- id
- kind
title: FileSnapshotEvent
description: 'A post-setup workspace manifest of paths + hashes captured before the agent starts.
Emitted as ``filetracking.snapshot`` under ``hud.filetracking.v1``.
Build source plus :class:`FileSetupEvent` patches derive this state; applying
subsequent :class:`FileChangeEvent` patches reconstructs the agent timeline.'
TraceStorageObjectListResponse:
properties:
trace_id:
type: string
format: uuid
title: Trace Id
kind:
type: string
const: artifact
title: Kind
objects:
items:
$ref: '#/components/schemas/TraceStorageObject'
type: array
title: Objects
type: object
required:
- trace_id
- kind
- objects
title: TraceStorageObjectListResponse
ErrorResponse:
properties:
error:
type: string
title: Error
source:
$ref: '#/components/schemas/ErrorSource'
detail:
type: string
title: Detail
type: object
required:
- error
- source
- detail
title: ErrorResponse
description: The uniform `{error, source, detail}` envelope returned for every 4xx/5xx.
FileSetupEvent:
properties:
id:
type: string
title: Id
parent_id:
anyOf:
- type: string
- type: 'null'
title: Parent Id
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
seq:
type: integer
title: Seq
default: 0
kind:
type: string
const: file_setup
title: Kind
files_scanned:
type: integer
title: Files Scanned
default: 0
files_changed:
type: integer
title: Files Changed
default: 0
truncated:
type: boolean
title: Truncated
default: false
patches:
items:
$ref: '#/components/schemas/FilePatch'
type: array
title: Patches
default: []
additionalProperties: false
type: object
required:
- id
- kind
title: FileSetupEvent
description: Workspace changes made by scenario setup before the agent starts.
FilePatch:
properties:
path:
type: string
title: Path
status:
type: string
enum:
- added
- modified
- deleted
title: Status
patch:
type: string
title: Patch
default: ''
size_before:
type: integer
title: Size Before
default: 0
size_after:
type: integer
title: Size After
default: 0
content_hash_before:
anyOf:
- type: string
- type: 'null'
title: Content Hash Before
content_hash_after:
anyOf:
- type: string
- type: 'null'
title: Content Hash After
additionalProperties: false
type: object
required:
- path
- status
title: FilePatch
description: 'A unified-diff patch for one file in a workspace change.
Byte-identical to the legacy ``tool_call.result_data.file_diff`` patch shape
so the frontend''s existing diff parsing/reconstruction ports unchanged.
``patch`` may be a placeholder string for over-cap files when ``truncated``.'
FileChangeEvent:
properties:
id:
type: string
title: Id
parent_id:
anyOf:
- type: string
- type: 'null'
title: Parent Id
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
seq:
type: integer
title: Seq
default: 0
kind:
type: string
const: file_change
title: Kind
files_scanned:
type: integer
title: Files Scanned
default: 0
files_changed:
type: integer
title: Files Changed
default: 0
truncated:
type: boolean
title: Truncated
default: false
patches:
items:
$ref: '#/components/schemas/FilePatch'
type: array
title: Patches
default: []
additionalProperties: false
type: object
required:
- id
- kind
title: FileChangeEvent
description: 'A workspace diff captured between steps.
Projected from ``filetracking.diff`` under ``hud.filetracking.v1``: the
files that changed since the previous scan.
Interleaves with tool/agent events by ``seq``/time; correlate to the step
timeline by ``started_at``. ``truncated`` marks a big diff capped over the
per-scan budget (e.g. an ``npm install`` / ``git checkout``).'
ErrorSource:
type: string
enum:
- user
- platform
- provider
title: ErrorSource
description: 'Who is at fault for a failure.
``user``: the customer''s input, account, environment, or agent code.
``platform``: HUD infrastructure or a broken platform invariant.
``provider``: a third-party dependency (cloud runtime, upstream LLM API).'
TraceWorkspaceFilesResponse:
properties:
trace_id:
type: string
format: uuid
title: Trace Id
files:
items:
$ref: '#/components/schemas/CapturedFile'
type: array
title: Files
type: object
required:
- trace_id
- files
title: TraceWorkspaceFilesResponse
FileCaptureEvent:
properties:
id:
type: string
title: Id
parent_id:
anyOf:
- type: string
- type: 'null'
title: Parent Id
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
seq:
type: integer
title: Seq
default: 0
kind:
type: string
const: file_capture
title: Kind
files_scanned:
type: integer
title: Files Scanned
default: 0
files_changed:
type: integer
title: Files Changed
default: 0
files_eligible:
type: integer
title: Files Eligible
default: 0
files_captured:
type: integer
title: Files Captured
default: 0
files_skipped:
type: integer
title: Files Skipped
default: 0
truncated:
type: boolean
title: Truncated
default: false
files:
items:
$ref: '#/components/schemas/CapturedFile'
type: array
title: Files
default: []
additionalProperties: false
type: object
required:
- id
- kind
title: FileCaptureEvent
description: Final changed-file artifacts captured from ``filetracking.capture``.
HTTPValidationError:
title: HTTPValidationError
type: object
properties:
error:
type: string
const: validation_error
title: Error
source:
type: string
enum:
- user
- platform
- provider
title: Source
detail:
type: string
title: Detail
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
title: Errors
required:
- error
- source
- detail
- errors
FileManifestEntry:
properties:
path:
type: string
title: Path
size:
type: integer
title: Size
default: 0
content_hash:
anyOf:
- type: string
- type: 'null'
title: Content Hash
additionalProperties: false
type: object
required:
- path
title: FileManifestEntry
description: 'One file in a workspace snapshot manifest: path + size + content hash.
The manifest carries identity, not content. The viewer derives unchanged
content from immutable build source and applies setup changes separately.'
ValidationError:
title: ValidationError
type: object
properties:
type:
type: string
title: Error Type
loc:
type: array
items:
anyOf:
- type: string
- type: integer
title: Location
msg:
type: string
title: Message
required:
- type
- loc
- msg
CapturedFile:
properties:
path:
type: string
title: Path
status:
type: string
enum:
- added
- modified
title: Status
size:
type: integer
title: Size
content_hash:
anyOf:
- type: string
- type: 'null'
title: Content Hash
content_type:
type: string
title: Content Type
default: application/octet-stream
url:
anyOf:
- type: string
- type: 'null'
title: Url
download_url:
anyOf:
- type: string
- type: 'null'
title: Download Url
additionalProperties: false
type: object
required:
- path
- status
- size
title: CapturedFile
description: One changed workspace file preserved as a downloadable telemetry artifact.
TraceStorageObject:
properties:
path:
type: string
title: Path
download_url:
type: string
title: Download Url
type: object
required:
- path
- download_url
title: TraceStorageObject
x-hud-contract-scope: platform_public