asyncapi: 2.6.0 info: title: wasmCloud wadm Application Deployment Manager API version: 1.0.0 description: >- The wasmCloud Application Deployment Manager (wadm) API is exposed entirely as a NATS service using a subject-per-operation model. All API requests and responses are JSON-encoded and published on subjects following the pattern wadm.api.{lattice}.{category}.{operation}. wadm manages the desired state of wasmCloud applications declared as OAM manifests, performing reconciliation to match observed lattice state with the declared specification. Operations include storing, retrieving, deploying, and undeploying application models, as well as querying deployment status. 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: wadm API Documentation url: https://wasmcloud.com/docs/ecosystem/wadm/api/ servers: nats: url: 'nats://localhost:4222' protocol: nats description: >- NATS server that wadm subscribes to for receiving API requests. In production deployments, this is typically the same NATS cluster used by the wasmCloud lattice. Authentication uses NATS credentials or NKey-based JWT authentication. channels: wadm.api.{lattice}.model.put: description: >- Store a new version of an application model (OAM manifest). Model storage is append-only: new versions are added to the version history. The request body is the OAM manifest in YAML or JSON format. The Content-Type header can be set to hint the format; if absent, wadm attempts YAML first. parameters: lattice: $ref: '#/components/parameters/lattice' publish: operationId: putModel summary: Store Application Model description: >- Stores a new version of an OAM application manifest in wadm. If the model does not exist, it is created. If it exists, a new version is appended to its version history. The manifest must include apiVersion, kind, metadata, and spec fields conforming to the wasmCloud OAM schema. message: $ref: '#/components/messages/PutModelRequest' tags: - name: Models subscribe: operationId: putModelResponse summary: Store Application Model Response description: >- Response to a model put request indicating success or failure and the version number assigned to the stored manifest. message: $ref: '#/components/messages/PutModelResponse' tags: - name: Models wadm.api.{lattice}.model.list: description: >- List all application models stored in the lattice with their current deployment status and version information. parameters: lattice: $ref: '#/components/parameters/lattice' publish: operationId: listModels summary: List Application Models description: >- Returns a list of all application models stored in the wadm instance for the specified lattice, including each model's name, current version, deployed version, and status summary. message: $ref: '#/components/messages/EmptyRequest' tags: - name: Models subscribe: operationId: listModelsResponse summary: List Models Response description: >- Response containing an array of application model summaries. message: $ref: '#/components/messages/ModelListResponse' tags: - name: Models wadm.api.{lattice}.model.get.{name}: description: >- Retrieve all versions of a specific application model by name. parameters: lattice: $ref: '#/components/parameters/lattice' name: $ref: '#/components/parameters/modelName' publish: operationId: getModel summary: Get Application Model description: >- Retrieves all stored versions of the named application model including the full OAM manifest for each version. message: $ref: '#/components/messages/EmptyRequest' tags: - name: Models subscribe: operationId: getModelResponse summary: Get Model Response description: >- Response containing the model versions and their OAM manifests. message: $ref: '#/components/messages/ModelGetResponse' tags: - name: Models wadm.api.{lattice}.model.del.{name}: description: >- Delete a specific application model and all its versions from storage. If the model is currently deployed, it will be undeployed first. parameters: lattice: $ref: '#/components/parameters/lattice' name: $ref: '#/components/parameters/modelName' publish: operationId: deleteModel summary: Delete Application Model description: >- Deletes the named application model and all stored versions. If the model is currently deployed, an undeploy operation is performed as part of the deletion. The response indicates success, failure, or noop if the model did not exist. message: $ref: '#/components/messages/EmptyRequest' tags: - name: Models subscribe: operationId: deleteModelResponse summary: Delete Model Response description: >- Response indicating whether the delete succeeded, failed, or was a noop because the model did not exist. message: $ref: '#/components/messages/DeleteModelResponse' tags: - name: Models wadm.api.{lattice}.model.deploy.{name}: description: >- Deploy an application model, activating autonomous reconciliation of the declared desired state against the live lattice state. parameters: lattice: $ref: '#/components/parameters/lattice' name: $ref: '#/components/parameters/modelName' publish: operationId: deployModel summary: Deploy Application Model description: >- Deploys the named application model. If a version is specified in the request, that version is deployed; if the version field is empty or "latest", the newest stored version is deployed. This operation is idempotent: deploying an already-deployed model succeeds without error. The previous deployed version is automatically replaced. message: $ref: '#/components/messages/DeployModelRequest' tags: - name: Deployments subscribe: operationId: deployModelResponse summary: Deploy Model Response description: >- Response indicating deployment success or failure. message: $ref: '#/components/messages/DeployModelResponse' tags: - name: Deployments wadm.api.{lattice}.model.undeploy.{name}: description: >- Undeploy a running application model, stopping all its components and providers managed by wadm. parameters: lattice: $ref: '#/components/parameters/lattice' name: $ref: '#/components/parameters/modelName' publish: operationId: undeployModel summary: Undeploy Application Model description: >- Undeploys the named application model, stopping reconciliation and removing all components and providers that were started by wadm for this application. Returns success, failure, or noop if the model was not deployed. message: $ref: '#/components/messages/EmptyRequest' tags: - name: Deployments subscribe: operationId: undeployModelResponse summary: Undeploy Model Response description: >- Response indicating whether the undeploy succeeded, failed, or was a noop. message: $ref: '#/components/messages/DeployModelResponse' tags: - name: Deployments wadm.api.{lattice}.model.status.{name}: description: >- Query the current deployment status of an application model, including the reconciliation state of each component and provider. parameters: lattice: $ref: '#/components/parameters/lattice' name: $ref: '#/components/parameters/modelName' publish: operationId: getModelStatus summary: Get Model Status description: >- Retrieves the current deployment status of the named application model, including per-component and per-provider status indicating whether they are reconciled, compensating, or in an error state. message: $ref: '#/components/messages/EmptyRequest' tags: - name: Deployments subscribe: operationId: getModelStatusResponse summary: Get Model Status Response description: >- Response containing the deployment status summary for the application. message: $ref: '#/components/messages/ModelStatusResponse' tags: - name: Deployments components: parameters: lattice: description: >- The lattice ID (also called lattice name) that identifies the wasmCloud lattice this API request targets. Defaults to "default" for single-lattice deployments. schema: type: string description: Lattice identifier string. default: default modelName: description: >- The name of the application model as defined in the metadata.name field of the OAM manifest. schema: type: string description: Application model name. messages: EmptyRequest: name: EmptyRequest title: Empty Request summary: A request with no payload body. contentType: application/json payload: type: object description: Empty request payload. PutModelRequest: name: PutModelRequest title: Put Model Request summary: An OAM application manifest to store in wadm. contentType: application/yaml payload: $ref: '#/components/schemas/OAMManifest' PutModelResponse: name: PutModelResponse title: Put Model Response summary: Response to a model storage request. contentType: application/json payload: $ref: '#/components/schemas/PutModelResponse' ModelListResponse: name: ModelListResponse title: Model List Response summary: List of all application model summaries. contentType: application/json payload: $ref: '#/components/schemas/ModelListResponse' ModelGetResponse: name: ModelGetResponse title: Model Get Response summary: All versions of a specific application model. contentType: application/json payload: $ref: '#/components/schemas/ModelGetResponse' DeleteModelResponse: name: DeleteModelResponse title: Delete Model Response summary: Result of a model deletion operation. contentType: application/json payload: $ref: '#/components/schemas/DeleteModelResponse' DeployModelRequest: name: DeployModelRequest title: Deploy Model Request summary: Request to deploy or undeploy an application model version. contentType: application/json payload: $ref: '#/components/schemas/DeployModelRequest' DeployModelResponse: name: DeployModelResponse title: Deploy Model Response summary: Result of a deploy or undeploy operation. contentType: application/json payload: $ref: '#/components/schemas/DeployModelResponse' ModelStatusResponse: name: ModelStatusResponse title: Model Status Response summary: Current deployment status of an application model. contentType: application/json payload: $ref: '#/components/schemas/ModelStatusResponse' schemas: OAMManifest: type: object description: >- An Open Application Model (OAM) manifest defining a wasmCloud application. The manifest declares components (WebAssembly actors) and capability providers along with the links and scaling traits that govern their deployment across the lattice. required: - apiVersion - kind - metadata - spec properties: apiVersion: type: string description: The OAM API version. enum: - core.oam.dev/v1beta1 kind: type: string description: The manifest kind, always Application for wasmCloud OAM manifests. enum: - Application metadata: type: object description: Application metadata including name, version, and annotations. properties: name: type: string description: Unique name of the application within the lattice. annotations: type: object description: >- Key-value annotations. The version annotation specifies the semantic version of the application. properties: version: type: string description: Semantic version of the application manifest. description: type: string description: Human-readable description of the application. spec: type: object description: The application specification containing components and their traits. properties: components: type: array description: >- Array of component definitions, each specifying a WebAssembly component or capability provider and its associated traits. items: $ref: '#/components/schemas/OAMComponent' OAMComponent: type: object description: >- A component definition in a wasmCloud OAM manifest. Components represent either WebAssembly components (type: component) or capability providers (type: capability). required: - name - type - properties properties: name: type: string description: >- Unique name for this component within the application, used as the component identifier in link definitions. type: type: string description: >- The component type: "component" for WebAssembly components or "capability" for capability providers. enum: - component - capability properties: $ref: '#/components/schemas/ComponentProperties' traits: type: array description: >- Array of trait definitions controlling scaling, links, and other runtime behaviors for this component. items: $ref: '#/components/schemas/ComponentTrait' ComponentProperties: type: object description: >- Properties for a wasmCloud OAM component specifying the image reference and optional configuration. required: - image properties: image: type: string description: >- OCI image reference or file path for the WebAssembly component or capability provider artifact (e.g., ghcr.io/wasmcloud/http-server:0.21.0). id: type: string description: >- Optional explicit component ID. If omitted, wadm generates an ID from the application and component names. config: type: array description: >- List of named configuration references to pass to the component at startup. items: type: object description: A named configuration reference. properties: name: type: string description: Name of the configuration entry. properties: type: object description: Inline configuration key-value pairs. additionalProperties: type: string ComponentTrait: type: object description: >- A trait definition applied to a component controlling its scaling behavior or links to other components and providers. required: - type - properties properties: type: type: string description: >- The trait type: spreadscaler for scaling configuration, or link for establishing connections between components and providers. enum: - spreadscaler - link properties: description: Trait-specific configuration properties. oneOf: - $ref: '#/components/schemas/SpreadScalerProperties' - $ref: '#/components/schemas/LinkProperties' SpreadScalerProperties: type: object description: >- Properties for a spreadscaler trait controlling how many instances of a component run and how they are distributed across hosts. properties: instances: type: integer description: >- Total number of instances of this component to run across the lattice. minimum: 0 spread: type: array description: >- List of spread requirements specifying host affinity rules and the weight of instances to place on matching hosts. items: type: object description: A spread requirement with host affinity and weight. properties: name: type: string description: Descriptive name for this spread requirement. requirements: type: object description: >- Key-value host label requirements. Hosts must have all specified labels to be eligible for this spread. additionalProperties: type: string weight: type: integer description: >- Relative weight of instances to place on hosts matching these requirements. minimum: 1 LinkProperties: type: object description: >- Properties for a link trait defining a connection between a source component and a target component or capability provider. required: - target properties: namespace: type: string description: >- The WIT interface namespace for the link (e.g., wasi, wasmcloud). package: type: string description: >- The WIT interface package for the link (e.g., http, keyvalue). interfaces: type: array description: List of WIT interface names exposed over this link. items: type: string description: A WIT interface name. target: type: object description: The target component or provider of this link. required: - name properties: name: type: string description: >- Name of the target component as defined in the spec.components array of this manifest. config: type: array description: >- Configuration entries passed to the target over this link. items: type: object description: A named configuration reference for the link target. source: type: object description: >- Optional source configuration passed to the source component side of this link. properties: config: type: array description: Configuration entries passed to the source side. items: type: object description: A named configuration reference for the link source. PutModelResponse: type: object description: Response from a model put operation. properties: result: type: string description: Outcome of the put operation. enum: - created - new_version - error total_versions: type: integer description: Total number of versions stored for this model after the put. current_version: type: string description: The version string assigned to the stored manifest. name: type: string description: The name of the model that was stored. message: type: string description: >- Human-readable message providing context, especially for error results. ModelSummary: type: object description: A summary of an application model with current deployment information. properties: name: type: string description: The model name. version: type: string description: The latest stored version of the model. deployed_version: type: string description: The version currently deployed, if any. status: type: string description: The overall deployment status of the model. enum: - Undeployed - Reconciling - Deployed - Failed status_message: type: string description: Human-readable description of the current status. ModelListResponse: type: object description: Response to a model list request. properties: models: type: array description: Array of model summaries for all stored application models. items: $ref: '#/components/schemas/ModelSummary' ModelGetResponse: type: object description: Response containing all versions of a specific model. properties: name: type: string description: The model name. versions: type: array description: All stored versions of this model. items: type: object description: A versioned model entry with its OAM manifest. properties: version: type: string description: The version string. deployed: type: boolean description: Whether this version is currently deployed. manifest: $ref: '#/components/schemas/OAMManifest' DeleteModelResponse: type: object description: Response to a model delete request. properties: result: type: string description: Outcome of the delete operation. enum: - deleted - noop - error message: type: string description: Human-readable message providing context for the result. undeploy: type: boolean description: >- Whether an undeploy operation was performed as part of the deletion because the model was deployed. DeployModelRequest: type: object description: Request body for a model deploy operation. properties: version: type: string description: >- The version of the model to deploy. Use "latest" or omit to deploy the newest stored version. DeployModelResponse: type: object description: Response to a deploy or undeploy operation. properties: result: type: string description: Outcome of the deploy/undeploy operation. enum: - acknowledged - error - noop message: type: string description: Human-readable message providing context for the result. ComponentStatus: type: object description: Status of an individual component or provider within a deployment. properties: name: type: string description: The component name from the OAM manifest. type: type: string description: The component type (component or capability). status: type: string description: Reconciliation status of this component. enum: - Undeployed - Compensating - Reconciling - Deployed - Failed traits: type: array description: Status of each trait applied to this component. items: type: object description: Status of a single trait. properties: type: type: string description: The trait type. status: type: string description: The trait reconciliation status. ModelStatusResponse: type: object description: Current deployment status of an application model. properties: name: type: string description: The model name. version: type: string description: The deployed version. status: type: string description: Overall deployment status. enum: - Undeployed - Reconciling - Deployed - Failed components: type: array description: Per-component status entries. items: $ref: '#/components/schemas/ComponentStatus'