HUD Registry API

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