wasmCloud Control Interface API

asyncapi: 2.6.0
info:
  title: wasmCloud Control Interface API
  description: >-
    AsyncAPI specification for the wasmCloud Control Interface, a NATS-based
    API for managing the wasmCloud lattice. Operators and tooling (wash CLI,
    wasmCloud dashboard, wadm) interact with wasmCloud hosts by publishing
    requests to well-known NATS subjects under the wasmbus.ctl.v1.{lattice}
    prefix. Hosts respond with typed JSON payloads. The interface supports
    starting and stopping components and providers, querying host inventories,
    linking components to providers, and scaling application instances.
  version: '1.0'
  contact:
    name: wasmCloud Community
    url: https://wasmcloud.com/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: wasmCloud Control Interface Documentation
  url: https://wasmcloud.com/docs/hosts/lattice-protocols/control-interface/
servers:
  natsServer:
    url: '{natsUrl}'
    protocol: nats
    description: >-
      NATS server used as the message broker for the wasmCloud lattice.
      All control interface messages are published and subscribed on this
      server. For local development wash uses an embedded NATS server on
      port 4222.
    variables:
      natsUrl:
        default: nats://localhost:4222
        description: NATS server connection URL
    security:
      - natsCredentials: []
channels:
  wasmbus.ctl.v1.{lattice}.host.get:
    description: >-
      Query channel for retrieving the list of all wasmCloud hosts participating
      in the lattice. The response is an array of host summary objects including
      host IDs, friendly names, uptime, and version information.
    parameters:
      lattice:
        description: The lattice identifier, typically the NATS account name
        schema:
          type: string
    publish:
      operationId: getHosts
      summary: Query all hosts in the lattice
      description: >-
        Publish an empty request to this subject to retrieve a list of all
        wasmCloud hosts currently participating in the specified lattice.
        The requesting client provides a reply-to subject; each host responds
        with its summary.
      message:
        $ref: '#/components/messages/EmptyRequest'
    subscribe:
      operationId: receiveHostList
      summary: Receive host summary responses
      description: >-
        Each host in the lattice responds to the get hosts request by publishing
        its HostSummary to the reply-to subject. Collect responses until the
        timeout to build the complete host list.
      message:
        $ref: '#/components/messages/HostSummaryResponse'

  wasmbus.ctl.v1.{lattice}.host.{hostId}.inv:
    description: >-
      Query channel for retrieving the inventory of a specific wasmCloud host.
      Returns all running components (actors) and capability providers on
      the host, along with their metadata.
    parameters:
      lattice:
        description: The lattice identifier
        schema:
          type: string
      hostId:
        description: The public key (nkey) of the target wasmCloud host
        schema:
          type: string
    publish:
      operationId: getHostInventory
      summary: Query a host for its running inventory
      description: >-
        Publish to this subject to retrieve the complete inventory of a
        specific wasmCloud host, including all running components and
        capability providers with their IDs, images, and link names.
      message:
        $ref: '#/components/messages/EmptyRequest'
    subscribe:
      operationId: receiveHostInventory
      summary: Receive host inventory response
      description: >-
        The target host responds with its full inventory including running
        components, capability providers, and their associated metadata.
      message:
        $ref: '#/components/messages/HostInventoryResponse'

  wasmbus.ctl.v1.{lattice}.component.scale.{hostId}:
    description: >-
      Command channel for scaling a WebAssembly component on a specific
      wasmCloud host. Scaling to 0 stops all instances; scaling to a positive
      integer sets the desired replica count.
    parameters:
      lattice:
        description: The lattice identifier
        schema:
          type: string
      hostId:
        description: The public key of the target wasmCloud host
        schema:
          type: string
    publish:
      operationId: scaleComponent
      summary: Scale a component to a desired replica count on a host
      description: >-
        Publishes a scale command to start, stop, or adjust the replica count
        of a WebAssembly component on the specified host. The component is
        identified by its OCI image reference or component ID. Setting
        replicas to 0 stops all running instances.
      message:
        $ref: '#/components/messages/ScaleComponentCommand'
    subscribe:
      operationId: receiveScaleResponse
      summary: Receive scale command acknowledgment
      description: >-
        The host acknowledges receipt of the scale command. Actual scaling
        is asynchronous; monitor host events for completion.
      message:
        $ref: '#/components/messages/CtlOperationAck'

  wasmbus.ctl.v1.{lattice}.provider.start.{hostId}:
    description: >-
      Command channel for starting a capability provider on a specific
      wasmCloud host. Providers are identified by their OCI image reference
      and a link name that scopes their configuration.
    parameters:
      lattice:
        description: The lattice identifier
        schema:
          type: string
      hostId:
        description: The public key of the target wasmCloud host
        schema:
          type: string
    publish:
      operationId: startProvider
      summary: Start a capability provider on a host
      description: >-
        Publishes a start command to launch a capability provider on the
        specified host. The provider is identified by its OCI image reference.
        Provider startup is asynchronous; monitor host events for the
        provider_started event.
      message:
        $ref: '#/components/messages/StartProviderCommand'
    subscribe:
      operationId: receiveStartProviderAck
      summary: Receive start provider acknowledgment
      description: >-
        The host acknowledges receipt of the start provider command.
      message:
        $ref: '#/components/messages/CtlOperationAck'

  wasmbus.ctl.v1.{lattice}.provider.stop.{hostId}:
    description: >-
      Command channel for stopping a running capability provider on a
      specific wasmCloud host.
    parameters:
      lattice:
        description: The lattice identifier
        schema:
          type: string
      hostId:
        description: The public key of the target wasmCloud host
        schema:
          type: string
    publish:
      operationId: stopProvider
      summary: Stop a running capability provider on a host
      description: >-
        Publishes a stop command to shut down a specific capability provider
        on the target host. The provider is identified by its provider ID
        (public key).
      message:
        $ref: '#/components/messages/StopProviderCommand'
    subscribe:
      operationId: receiveStopProviderAck
      summary: Receive stop provider acknowledgment
      description: >-
        The host acknowledges receipt of the stop provider command.
      message:
        $ref: '#/components/messages/CtlOperationAck'

  wasmbus.ctl.v1.{lattice}.link.put:
    description: >-
      Command channel for creating a link between a wasmCloud component and
      a capability provider. Links establish named connections with optional
      configuration values that enable components to use provider capabilities.
    parameters:
      lattice:
        description: The lattice identifier
        schema:
          type: string
    publish:
      operationId: putLink
      summary: Create or update a component-to-provider link
      description: >-
        Publishes a link definition to connect a component to a capability
        provider. The link includes the component ID, provider ID, contract
        identifier, link name, and optional key-value configuration passed
        to the provider at link time.
      message:
        $ref: '#/components/messages/PutLinkCommand'
    subscribe:
      operationId: receivePutLinkAck
      summary: Receive put link acknowledgment
      description: >-
        Acknowledges that the link definition was accepted and is being
        propagated to the appropriate host.
      message:
        $ref: '#/components/messages/CtlOperationAck'

  wasmbus.ctl.v1.{lattice}.link.del:
    description: >-
      Command channel for removing an existing link between a component
      and a capability provider.
    parameters:
      lattice:
        description: The lattice identifier
        schema:
          type: string
    publish:
      operationId: deleteLink
      summary: Remove a component-to-provider link
      description: >-
        Publishes a delete link command to remove the link between a component
        and a capability provider identified by the combination of component ID,
        provider contract, and link name.
      message:
        $ref: '#/components/messages/DeleteLinkCommand'
    subscribe:
      operationId: receiveDeleteLinkAck
      summary: Receive delete link acknowledgment
      description: >-
        Acknowledges that the link deletion was accepted.
      message:
        $ref: '#/components/messages/CtlOperationAck'

  wasmbus.ctl.v1.{lattice}.evt.{hostId}:
    description: >-
      Event stream published by wasmCloud hosts for observability. Hosts
      emit structured CloudEvents-formatted events for all significant
      lifecycle changes including component start/stop, provider start/stop,
      link changes, and health check results.
    parameters:
      lattice:
        description: The lattice identifier
        schema:
          type: string
      hostId:
        description: The public key of the host emitting events
        schema:
          type: string
    subscribe:
      operationId: receiveHostEvent
      summary: Receive a wasmCloud host lifecycle event
      description: >-
        Receive CloudEvents-formatted event messages from a wasmCloud host.
        Events cover component lifecycle (component_scaled, component_scale_failed),
        provider lifecycle (provider_started, provider_start_failed, provider_stopped),
        link changes (linkdef_set, linkdef_deleted), host lifecycle
        (host_started, host_stopped, host_heartbeat), and configuration
        updates.
      message:
        oneOf:
          - $ref: '#/components/messages/ComponentScaledEvent'
          - $ref: '#/components/messages/ProviderStartedEvent'
          - $ref: '#/components/messages/ProviderStoppedEvent'
          - $ref: '#/components/messages/LinkdefSetEvent'
          - $ref: '#/components/messages/HostHeartbeatEvent'

components:
  securitySchemes:
    natsCredentials:
      type: userPassword
      description: >-
        NATS credentials file (.creds) for authenticating with the NATS server
        using NKeys and JWT-based authentication. In a multi-tenant lattice
        each lattice is scoped to a NATS account.
  messages:
    EmptyRequest:
      name: EmptyRequest
      title: Empty Request
      summary: An empty request body used for query operations that require no parameters
      contentType: application/json
      payload:
        type: object
        description: Empty JSON object for query operations requiring no parameters.

    HostSummaryResponse:
      name: HostSummaryResponse
      title: Host Summary Response
      summary: Summary information about a wasmCloud host
      contentType: application/json
      payload:
        $ref: '#/components/schemas/HostSummary'

    HostInventoryResponse:
      name: HostInventoryResponse
      title: Host Inventory Response
      summary: Full inventory of components and providers running on a host
      contentType: application/json
      payload:
        $ref: '#/components/schemas/HostInventory'

    ScaleComponentCommand:
      name: ScaleComponentCommand
      title: Scale Component Command
      summary: Command to scale a WebAssembly component to a desired replica count
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ScaleComponentCommand'

    StartProviderCommand:
      name: StartProviderCommand
      title: Start Provider Command
      summary: Command to start a capability provider on a wasmCloud host
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StartProviderCommand'

    StopProviderCommand:
      name: StopProviderCommand
      title: Stop Provider Command
      summary: Command to stop a running capability provider on a wasmCloud host
      contentType: application/json
      payload:
        $ref: '#/components/schemas/StopProviderCommand'

    PutLinkCommand:
      name: PutLinkCommand
      title: Put Link Command
      summary: Command to create or update a link between a component and a provider
      contentType: application/json
      payload:
        $ref: '#/components/schemas/LinkDefinition'

    DeleteLinkCommand:
      name: DeleteLinkCommand
      title: Delete Link Command
      summary: Command to remove a link between a component and a provider
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DeleteLinkCommand'

    CtlOperationAck:
      name: CtlOperationAck
      title: Control Operation Acknowledgment
      summary: Acknowledgment response for control interface commands
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CtlOperationAck'

    ComponentScaledEvent:
      name: ComponentScaledEvent
      title: Component Scaled Event
      summary: CloudEvent emitted when a component's replica count changes
      contentType: application/json
      payload:
        $ref: '#/components/schemas/HostEvent'

    ProviderStartedEvent:
      name: ProviderStartedEvent
      title: Provider Started Event
      summary: CloudEvent emitted when a capability provider successfully starts
      contentType: application/json
      payload:
        $ref: '#/components/schemas/HostEvent'

    ProviderStoppedEvent:
      name: ProviderStoppedEvent
      title: Provider Stopped Event
      summary: CloudEvent emitted when a capability provider stops
      contentType: application/json
      payload:
        $ref: '#/components/schemas/HostEvent'

    LinkdefSetEvent:
      name: LinkdefSetEvent
      title: Link Definition Set Event
      summary: CloudEvent emitted when a link definition is created or updated
      contentType: application/json
      payload:
        $ref: '#/components/schemas/HostEvent'

    HostHeartbeatEvent:
      name: HostHeartbeatEvent
      title: Host Heartbeat Event
      summary: Periodic heartbeat event emitted by each wasmCloud host
      contentType: application/json
      payload:
        $ref: '#/components/schemas/HostEvent'

  schemas:
    HostSummary:
      type: object
      description: >-
        Summary information about a wasmCloud host participating in the lattice.
      required:
        - id
        - uptime_seconds
        - version
      properties:
        id:
          type: string
          description: >-
            The public key (nkey) uniquely identifying this host in the lattice.
        friendly_name:
          type: string
          description: Human-readable name assigned to the host for display purposes.
        uptime_seconds:
          type: integer
          description: Number of seconds the host has been running.
        version:
          type: string
          description: wasmCloud host version string, e.g. '0.82.0'.
        labels:
          type: object
          description: >-
            Key-value labels assigned to the host for scheduling and placement
            constraints in wadm manifests.
          additionalProperties:
            type: string

    HostInventory:
      type: object
      description: >-
        Complete inventory of a wasmCloud host including all running components
        and capability providers.
      required:
        - host_id
        - components
        - providers
      properties:
        host_id:
          type: string
          description: Public key of the host this inventory belongs to.
        friendly_name:
          type: string
          description: Human-readable name of the host.
        labels:
          type: object
          description: Host labels used for scheduling constraints.
          additionalProperties:
            type: string
        components:
          type: array
          description: List of WebAssembly components currently running on this host.
          items:
            $ref: '#/components/schemas/ComponentDescription'
        providers:
          type: array
          description: List of capability providers currently running on this host.
          items:
            $ref: '#/components/schemas/ProviderDescription'

    ComponentDescription:
      type: object
      description: Description of a WebAssembly component running on a wasmCloud host.
      required:
        - id
        - image_ref
      properties:
        id:
          type: string
          description: Unique identifier for the component instance, typically a public key.
        image_ref:
          type: string
          description: >-
            OCI image reference of the component, e.g.
            'ghcr.io/wasmcloud/components/http-hello-world:0.1.0'.
        name:
          type: string
          description: Human-readable name of the component.
        max_instances:
          type: integer
          description: Maximum number of concurrent instances of this component.
        annotations:
          type: object
          description: Annotations applied to the component instance.
          additionalProperties:
            type: string

    ProviderDescription:
      type: object
      description: Description of a capability provider running on a wasmCloud host.
      required:
        - id
        - image_ref
      properties:
        id:
          type: string
          description: Provider ID, typically the provider's public key.
        image_ref:
          type: string
          description: >-
            OCI image reference of the provider, e.g.
            'ghcr.io/wasmcloud/http-server:0.22.0'.
        name:
          type: string
          description: Human-readable name of the capability provider.
        annotations:
          type: object
          description: Annotations applied to the provider instance.
          additionalProperties:
            type: string

    ScaleComponentCommand:
      type: object
      description: >-
        Command to scale a WebAssembly component to a desired number of replicas
        on a specific wasmCloud host.
      required:
        - component_ref
        - component_id
        - max_instances
      properties:
        component_ref:
          type: string
          description: >-
            OCI image reference of the component to scale, e.g.
            'ghcr.io/wasmcloud/components/http-hello-world:0.1.0'.
        component_id:
          type: string
          description: >-
            Unique identifier for the component. Used to distinguish multiple
            instances of the same image with different configurations.
        max_instances:
          type: integer
          minimum: 0
          description: >-
            Desired number of concurrent instances. Setting to 0 stops all
            running instances of this component on the target host.
        annotations:
          type: object
          description: Annotations to apply to the component instances.
          additionalProperties:
            type: string
        config:
          type: array
          description: Named configuration references to pass to the component.
          items:
            type: string

    StartProviderCommand:
      type: object
      description: Command to start a capability provider on a wasmCloud host.
      required:
        - provider_ref
        - provider_id
      properties:
        provider_ref:
          type: string
          description: >-
            OCI image reference of the capability provider, e.g.
            'ghcr.io/wasmcloud/http-server:0.22.0'.
        provider_id:
          type: string
          description: >-
            Unique identifier for the provider instance. Scopes the provider
            within the lattice.
        annotations:
          type: object
          description: Annotations to apply to the started provider.
          additionalProperties:
            type: string
        config:
          type: array
          description: Named configuration references to pass to the provider at startup.
          items:
            type: string

    StopProviderCommand:
      type: object
      description: Command to stop a running capability provider on a wasmCloud host.
      required:
        - provider_id
      properties:
        provider_id:
          type: string
          description: >-
            The provider ID of the running instance to stop.

    LinkDefinition:
      type: object
      description: >-
        A link definition connecting a wasmCloud component to a capability provider.
        Links enable components to use provider capabilities and carry optional
        configuration passed to the provider at link time.
      required:
        - source_id
        - target
        - name
        - wit_namespace
        - wit_package
      properties:
        source_id:
          type: string
          description: >-
            Component ID of the source component that will use this link to
            invoke capability provider operations.
        target:
          type: string
          description: >-
            Provider ID or component ID of the link target that will receive
            invocations through this link.
        name:
          type: string
          description: >-
            Link name scoping this link within the lattice. Allows a component
            to have multiple links to providers of the same interface using
            different names.
          default: default
        wit_namespace:
          type: string
          description: >-
            WIT namespace of the interface this link implements, e.g. 'wasi'.
        wit_package:
          type: string
          description: >-
            WIT package name of the interface this link implements, e.g.
            'http' or 'keyvalue'.
        interfaces:
          type: array
          description: >-
            List of WIT interface names from the package that this link
            covers, e.g. ['incoming-handler'].
          items:
            type: string
        source_config:
          type: array
          description: Named configuration references provided to the source component.
          items:
            type: string
        target_config:
          type: array
          description: Named configuration references provided to the target provider.
          items:
            type: string

    DeleteLinkCommand:
      type: object
      description: Command to remove an existing link definition from the lattice.
      required:
        - source_id
        - name
        - wit_namespace
        - wit_package
      properties:
        source_id:
          type: string
          description: Component ID of the source side of the link to delete.
        name:
          type: string
          description: Link name of the link to delete.
        wit_namespace:
          type: string
          description: WIT namespace of the interface the link implements.
        wit_package:
          type: string
          description: WIT package name of the interface the link implements.

    CtlOperationAck:
      type: object
      description: >-
        Acknowledgment returned by a wasmCloud host in response to a control
        interface command. Indicates whether the command was accepted; actual
        completion is asynchronous and signalled via host events.
      required:
        - accepted
      properties:
        accepted:
          type: boolean
          description: >-
            Whether the host accepted the command for processing. A false value
            indicates the command was rejected, typically due to invalid parameters.
        error:
          type: string
          description: >-
            Human-readable error message when accepted is false, describing why
            the command was rejected.

    HostEvent:
      type: object
      description: >-
        A CloudEvents-formatted event emitted by a wasmCloud host for observability.
        Covers component and provider lifecycle changes, link definition changes,
        heartbeats, and configuration updates.
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
          description: CloudEvents spec version.
        type:
          type: string
          description: >-
            Event type identifier. Known values include com.wasmcloud.lattice.component_scaled,
            com.wasmcloud.lattice.provider_started, com.wasmcloud.lattice.provider_stopped,
            com.wasmcloud.lattice.linkdef_set, com.wasmcloud.lattice.linkdef_deleted,
            com.wasmcloud.lattice.host_heartbeat, com.wasmcloud.lattice.host_started,
            com.wasmcloud.lattice.host_stopped.
          examples:
            - com.wasmcloud.lattice.component_scaled
            - com.wasmcloud.lattice.provider_started
            - com.wasmcloud.lattice.host_heartbeat
        source:
          type: string
          description: >-
            URI identifying the host that emitted this event. Typically the
            host public key prefixed with a scheme.
        id:
          type: string
          description: Unique identifier for this event instance.
        time:
          type: string
          format: date-time
          description: Timestamp when the event occurred.
        datacontenttype:
          type: string
          const: application/json
          description: Content type of the event data field.
        data:
          type: object
          description: >-
            Event-specific payload. Structure varies by event type and contains
            the relevant entity details (component ID, provider ID, etc.).
          additionalProperties: true