HUD Registry API
The registry API from HUD — 4 operation(s) for registry.
The registry API from HUD — 4 operation(s) for registry.
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-registry-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 Registry API
version: 2.0.0
tags:
- name: Registry
paths:
/v2/registry:
get:
tags:
- Registry
summary: List Registries
description: List registries visible to the caller, with search, ownership, and sort filters.
operationId: list_registries_v2_registry_get
parameters:
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
maximum: 2147483647
minimum: 0
default: 0
title: Offset
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ILIKE-match on name
title: Search
description: ILIKE-match on name
- name: match_templates
in: query
required: false
schema:
type: boolean
description: When search is set, also match environment description and latest-build template name, description, and setup_description
default: false
title: Match Templates
description: When search is set, also match environment description and latest-build template name, description, and setup_description
- name: include_latest_scenarios
in: query
required: false
schema:
type: boolean
description: Embed latest-build templates on each list row
default: false
title: Include Latest Scenarios
description: Embed latest-build templates on each list row
- name: public_only
in: query
required: false
schema:
type: boolean
description: Only public registries; anonymous browsing requires this or featured_only
default: false
title: Public Only
description: Only public registries; anonymous browsing requires this or featured_only
- name: featured_only
in: query
required: false
schema:
type: boolean
description: Only platform-featured registries, which are always public
default: false
title: Featured Only
description: Only platform-featured registries, which are always public
- name: owner_only
in: query
required: false
schema:
type: boolean
description: Only registries owned by the caller's membership; ignored when public_only=True
default: false
title: Owner Only
description: Only registries owned by the caller's membership; ignored when public_only=True
- name: project_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: Only registries contained by this Project; omitted lists every Project
title: Project Id
description: Only registries contained by this Project; omitted lists every Project
- name: sort_by
in: query
required: false
schema:
enum:
- starred
- date
- name
- stars
type: string
description: 'Sort order: starred (caller''s starred first), date (updated_at DESC), name (A-Z), stars (star_count DESC)'
default: starred
title: Sort By
description: 'Sort order: starred (caller''s starred first), date (updated_at DESC), name (A-Z), stars (star_count DESC)'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponse_RegistryDetailResponse_'
'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/registry/{registry_id}:
get:
tags:
- Registry
summary: Get Registry
description: Get a registry by id with its latest build details.
operationId: get_registry_v2_registry__registry_id__get
parameters:
- name: registry_id
in: path
required: true
schema:
type: string
format: uuid
title: Registry Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RegistryDetailResponse'
'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/registry/{registry_id}/source-url:
get:
tags:
- Registry
summary: Get Registry Source Url
description: 'Get a presigned download URL for the registry''s source archive.
Readers outside the owning team download only the latest build of a public environment
whose owner published its source.'
operationId: get_registry_source_url_v2_registry__registry_id__source_url_get
parameters:
- name: registry_id
in: path
required: true
schema:
type: string
format: uuid
title: Registry Id
- name: build_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: Download a specific build's source archive. Defaults to the registry's latest build when omitted.
title: Build Id
description: Download a specific build's source archive. Defaults to the registry's latest build when omitted.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrySourceUrlResponse'
'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/registry/{registry_id}/scenarios:
get:
tags:
- Registry
summary: List Registry Scenarios
description: List scenarios for a registry build (latest build by default).
operationId: list_registry_scenarios_v2_registry__registry_id__scenarios_get
parameters:
- name: registry_id
in: path
required: true
schema:
type: string
format: uuid
title: Registry Id
- name: build_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: Filter scenarios to a specific build of this registry. Defaults to the registry's latest build when omitted.
title: Build Id
description: Filter scenarios to a specific build of this registry. Defaults to the registry's latest build when omitted.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScenarioResponse'
title: Response List Registry Scenarios V2 Registry Registry Id Scenarios Get
'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:
LatestBuildSummary:
properties:
id:
type: string
format: uuid
title: Id
status:
type: string
title: Status
sdk_generation:
type: string
title: Sdk Generation
version:
anyOf:
- type: integer
- type: 'null'
title: Version
manifest:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Manifest
lock:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Lock
type: object
required:
- id
- status
- sdk_generation
title: LatestBuildSummary
description: Projection of `builds` returned alongside a registry.
ExternalOrigin:
properties:
system:
$ref: '#/components/schemas/ExternalSystem'
external_id:
type: string
title: External Id
type: object
required:
- system
- external_id
title: ExternalOrigin
description: 'Where an imported entity comes from: a system and the entity''s id in it.'
RegistrySourceUrlResponse:
properties:
registry_id:
type: string
format: uuid
title: Registry Id
build_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Build Id
download_url:
anyOf:
- type: string
- type: 'null'
title: Download Url
github_url:
anyOf:
- type: string
- type: 'null'
title: Github Url
type: object
required:
- registry_id
title: RegistrySourceUrlResponse
description: Source archive locator for a selected build, plus legacy repo metadata.
RegistryDetailResponse:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
registry_type:
type: string
title: Registry Type
project_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Project Id
public:
type: boolean
title: Public
featured:
type: boolean
title: Featured
source_public:
type: boolean
title: Source Public
description:
anyOf:
- type: string
- type: 'null'
title: Description
latest_build_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Latest Build Id
github_url:
anyOf:
- type: string
- type: 'null'
title: Github Url
branch:
anyOf:
- type: string
- type: 'null'
title: Branch
entry_folder:
anyOf:
- type: string
- type: 'null'
title: Entry Folder
build_args:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Build Args
instance_config:
additionalProperties: true
type: object
title: Instance Config
default: {}
star_count:
type: integer
title: Star Count
default: 0
origin:
anyOf:
- $ref: '#/components/schemas/ExternalOrigin'
- type: 'null'
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
latest_build:
anyOf:
- $ref: '#/components/schemas/LatestBuildSummary'
- type: 'null'
source_build_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Source Build Id
is_starred:
type: boolean
title: Is Starred
default: false
is_owner:
type: boolean
title: Is Owner
default: false
can_edit:
type: boolean
title: Can Edit
default: false
can_manage:
type: boolean
title: Can Manage
default: false
owner_name:
anyOf:
- type: string
- type: 'null'
title: Owner Name
owner_avatar_url:
anyOf:
- type: string
- type: 'null'
title: Owner Avatar Url
team_name:
anyOf:
- type: string
- type: 'null'
title: Team Name
scenario_count:
type: integer
title: Scenario Count
default: 0
latest_scenarios:
anyOf:
- items:
$ref: '#/components/schemas/ScenarioResponse'
type: array
- type: 'null'
title: Latest Scenarios
example_trace_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Example Trace Id
featured_source:
anyOf:
- $ref: '#/components/schemas/FeaturedSourceResponse'
- type: 'null'
type: object
required:
- id
- name
- registry_type
- project_id
- public
- featured
- source_public
- created_at
- updated_at
title: RegistryDetailResponse
FeaturedSourceResponse:
properties:
repository_url:
type: string
title: Repository Url
path:
type: string
title: Path
description: Directory of the environment within the repository
url:
type: string
title: Url
description: Browsable URL of that directory on the default branch
type: object
required:
- repository_url
- path
- url
title: FeaturedSourceResponse
description: Where a featured environment's source lives in the public SDK repository.
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.
PaginatedResponse_RegistryDetailResponse_:
properties:
items:
items:
$ref: '#/components/schemas/RegistryDetailResponse'
type: array
title: Items
total:
type: integer
title: Total
limit:
type: integer
title: Limit
offset:
type: integer
title: Offset
type: object
required:
- items
- total
- limit
- offset
title: PaginatedResponse[RegistryDetailResponse]
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).'
ExternalSystem:
type: string
enum:
- harbor
title: ExternalSystem
description: A system HUD imports environments and runs from.
ScenarioResponse:
properties:
id:
type: string
format: uuid
title: Id
registry_id:
type: string
format: uuid
title: Registry Id
build_id:
type: string
format: uuid
title: Build Id
name:
type: string
title: Name
slug:
anyOf:
- type: string
- type: 'null'
title: Slug
description:
anyOf:
- type: string
- type: 'null'
title: Description
args_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Args Schema
arguments:
items:
$ref: '#/components/schemas/ScenarioArgument'
type: array
title: Arguments
default: []
metadata:
additionalProperties: true
type: object
title: Metadata
default: {}
trace_name_template:
anyOf:
- type: string
- type: 'null'
title: Trace Name Template
created_at:
type: string
format: date-time
title: Created At
type: object
required:
- id
- registry_id
- build_id
- name
- created_at
title: ScenarioResponse
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
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
ScenarioArgument:
properties:
name:
type: string
title: Name
required:
type: boolean
title: Required
default: false
description:
anyOf:
- type: string
- type: 'null'
title: Description
type:
anyOf:
- type: string
- type: 'null'
title: Type
default:
anyOf:
- {}
- type: 'null'
title: Default
inputSchema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Inputschema
type: object
required:
- name
title: ScenarioArgument
x-hud-contract-scope: platform_public