HUD Instances API
The instances API from HUD — 2 operation(s) for instances.
The instances API from HUD — 2 operation(s) for instances.
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-instances-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 Instances API
version: 2.0.0
tags:
- name: Instances
paths:
/v2/instance:
get:
tags:
- Instances
summary: List Instances
description: List a registry's instances, optionally including recently terminated ones.
operationId: list_instances_v2_instance_get
parameters:
- name: registry_id
in: query
required: true
schema:
type: string
format: uuid
description: Filter instances to this registry
title: Registry Id
description: Filter instances to this registry
- name: include_terminated
in: query
required: false
schema:
type: boolean
description: Include recently terminated instances
default: false
title: Include Terminated
description: Include recently terminated instances
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
maximum: 2147483647
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ActiveInstancesResponse'
'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/instance/stop:
post:
tags:
- Instances
summary: Stop Instances
description: Stop the given instances of a registry, reporting per-instance results.
operationId: stop_instances_v2_instance_stop_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StopInstancesRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StopInstancesResponse'
'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:
ActiveInstance:
properties:
id:
type: string
format: uuid
title: Id
registry_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Registry Id
build_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Build Id
status:
type: string
title: Status
created_at:
type: string
format: date-time
title: Created At
terminated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Terminated At
public_ip:
anyOf:
- type: string
- type: 'null'
title: Public Ip
ec2_instance_type:
anyOf:
- type: string
- type: 'null'
title: Ec2 Instance Type
max_runtime_seconds:
anyOf:
- type: integer
- type: 'null'
title: Max Runtime Seconds
user_name:
anyOf:
- type: string
- type: 'null'
title: User Name
user_avatar_url:
anyOf:
- type: string
- type: 'null'
title: User Avatar Url
actual_cost:
anyOf:
- type: number
- type: 'null'
title: Actual Cost
hourly_rate:
anyOf:
- type: number
- type: 'null'
title: Hourly Rate
tier:
anyOf:
- type: string
- type: 'null'
title: Tier
cpu_millicores:
anyOf:
- type: integer
- type: 'null'
title: Cpu Millicores
memory_gb:
anyOf:
- type: number
- type: 'null'
title: Memory Gb
timeout_seconds:
anyOf:
- type: integer
- type: 'null'
title: Timeout Seconds
max_session_seconds:
anyOf:
- type: integer
- type: 'null'
title: Max Session Seconds
file_tracking_enabled:
anyOf:
- type: boolean
- type: 'null'
title: File Tracking Enabled
no_external_access:
anyOf:
- type: boolean
- type: 'null'
title: No External Access
protocol_version:
anyOf:
- type: string
- type: 'null'
title: Protocol Version
vnc_url:
anyOf:
- type: string
- type: 'null'
title: Vnc Url
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
trace:
anyOf:
- $ref: '#/components/schemas/ActiveInstanceTrace'
- type: 'null'
type: object
required:
- id
- status
- created_at
title: ActiveInstance
StopInstancesRequest:
properties:
registry_id:
type: string
format: uuid
title: Registry Id
instance_ids:
items:
type: string
format: uuid
type: array
maxItems: 100
minItems: 1
title: Instance Ids
type: object
required:
- registry_id
- instance_ids
title: StopInstancesRequest
ActiveInstancesResponse:
properties:
instances:
items:
$ref: '#/components/schemas/ActiveInstance'
type: array
title: Instances
total:
type: integer
title: Total
running_count:
type: integer
title: Running Count
terminated_count:
type: integer
title: Terminated Count
has_more:
type: boolean
title: Has More
type: object
required:
- instances
- total
- running_count
- terminated_count
- has_more
title: ActiveInstancesResponse
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.
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).'
StopInstancesResponse:
properties:
stopped:
type: integer
title: Stopped
errors:
items:
type: string
type: array
title: Errors
type: object
required:
- stopped
title: StopInstancesResponse
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
ActiveInstanceTrace:
properties:
id:
type: string
format: uuid
title: Id
status:
anyOf:
- type: string
- type: 'null'
title: Status
reward:
anyOf:
- type: number
- type: 'null'
title: Reward
created_at:
type: string
format: date-time
title: Created At
thumbnail_url:
anyOf:
- type: string
- type: 'null'
title: Thumbnail Url
error:
anyOf:
- type: string
- type: 'null'
title: Error
type: object
required:
- id
- created_at
title: ActiveInstanceTrace
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
x-hud-contract-scope: platform_public