asyncapi: 3.0.0 info: title: NATS Messaging API version: 2.10.0 description: >- AsyncAPI specification for NATS messaging patterns including core pub/sub, request-reply, queue groups, and JetStream persistent messaging. NATS provides a simple, high-performance messaging system for cloud-native applications, microservices, IoT, and edge computing. contact: name: NATS.io url: https://nats.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 externalDocs: description: NATS Documentation url: https://docs.nats.io servers: default: host: localhost:4222 protocol: nats description: Default NATS server connection cluster: host: localhost:6222 protocol: nats description: NATS cluster route connection websocket: host: localhost:443 protocol: ws description: NATS WebSocket connection defaultContentType: application/json channels: corePublish: address: '{subject}' title: Core NATS Publish description: >- Core NATS publish/subscribe channel. Messages are delivered at-most-once with no persistence. Supports subject-based routing with wildcards (* for single token, > for multiple tokens). parameters: subject: description: >- NATS subject for message routing. Supports dot-separated hierarchical subjects and wildcards. Examples: orders.new, events.*, logs.> messages: coreMessage: $ref: '#/components/messages/CoreNATSMessage' requestReply: address: '{subject}' title: Request-Reply description: >- NATS request-reply pattern. A client sends a request on a subject and receives a reply on an auto-generated inbox subject. Supports scatter-gather patterns when multiple responders exist. parameters: subject: description: NATS subject for the request messages: request: $ref: '#/components/messages/RequestMessage' reply: $ref: '#/components/messages/ReplyMessage' queueGroup: address: '{subject}' title: Queue Group Subscription description: >- Queue group subscriptions distribute messages among members of a named group. Only one member of the group receives each message, enabling load-balanced message processing. parameters: subject: description: NATS subject for queue group subscription messages: queueMessage: $ref: '#/components/messages/CoreNATSMessage' jetStreamPublish: address: '{stream_subject}' title: JetStream Publish description: >- JetStream publish channel for persistent messaging. Messages are stored in streams with configurable retention policies, storage backends, and replication factors. Publishers receive acknowledgments confirming message storage. parameters: stream_subject: description: >- JetStream stream subject. Must match a configured stream subject filter. Example: orders.>, events.processed messages: jetStreamMessage: $ref: '#/components/messages/JetStreamMessage' publishAck: $ref: '#/components/messages/JetStreamPublishAck' jetStreamConsume: address: '$JS.API.CONSUMER.MSG.NEXT.{stream}.{consumer}' title: JetStream Consumer description: >- JetStream consumer channel for pulling messages from streams. Consumers track delivery state and support multiple delivery policies including all, last, new, by-start-sequence, and by-start-time. Messages require explicit acknowledgment. parameters: stream: description: JetStream stream name consumer: description: JetStream consumer name messages: consumeMessage: $ref: '#/components/messages/JetStreamMessage' jetStreamKeyValue: address: '$KV.{bucket}.{key}' title: JetStream Key-Value Store description: >- JetStream Key-Value store built on top of streams. Provides a familiar key-value interface with watch capabilities for real-time change notification. Supports TTL, history, and cross-cluster replication. parameters: bucket: description: Key-Value bucket name key: description: Key within the bucket messages: kvEntry: $ref: '#/components/messages/KeyValueEntry' jetStreamObjectStore: address: '$OBJ.{bucket}' title: JetStream Object Store description: >- JetStream Object Store for storing large objects that exceed the maximum message size. Objects are chunked and stored in a stream with metadata tracking. parameters: bucket: description: Object Store bucket name messages: objectMeta: $ref: '#/components/messages/ObjectStoreMeta' operations: publishMessage: action: send channel: $ref: '#/channels/corePublish' summary: Publish a message to a NATS subject description: >- Publishes a message to the specified subject. All subscribers matching the subject receive the message. Fire-and-forget with at-most-once delivery semantics. messages: - $ref: '#/channels/corePublish/messages/coreMessage' subscribeMessage: action: receive channel: $ref: '#/channels/corePublish' summary: Subscribe to messages on a NATS subject description: >- Subscribes to messages matching the specified subject pattern. Supports wildcard subjects for flexible routing. messages: - $ref: '#/channels/corePublish/messages/coreMessage' sendRequest: action: send channel: $ref: '#/channels/requestReply' summary: Send a request and await a reply description: >- Sends a request message and waits for a reply on an auto-generated inbox subject. Supports timeouts. messages: - $ref: '#/channels/requestReply/messages/request' receiveReply: action: receive channel: $ref: '#/channels/requestReply' summary: Receive a reply to a request messages: - $ref: '#/channels/requestReply/messages/reply' queueSubscribe: action: receive channel: $ref: '#/channels/queueGroup' summary: Subscribe as part of a queue group description: >- Subscribes to messages as a member of a named queue group. Messages are load-balanced across group members. messages: - $ref: '#/channels/queueGroup/messages/queueMessage' jetStreamPublish: action: send channel: $ref: '#/channels/jetStreamPublish' summary: Publish a persistent message to a JetStream stream description: >- Publishes a message to a JetStream stream. The server acknowledges successful storage. Supports deduplication via Nats-Msg-Id header. messages: - $ref: '#/channels/jetStreamPublish/messages/jetStreamMessage' jetStreamConsume: action: receive channel: $ref: '#/channels/jetStreamConsume' summary: Consume messages from a JetStream consumer description: >- Pulls or pushes messages from a JetStream consumer. Requires explicit acknowledgment (ack, nak, in-progress, term). messages: - $ref: '#/channels/jetStreamConsume/messages/consumeMessage' watchKeyValue: action: receive channel: $ref: '#/channels/jetStreamKeyValue' summary: Watch for key-value changes description: >- Watches a key or wildcard pattern in a Key-Value bucket for real-time change notifications. messages: - $ref: '#/channels/jetStreamKeyValue/messages/kvEntry' components: messages: CoreNATSMessage: name: CoreNATSMessage title: Core NATS Message summary: A basic NATS message with subject, payload, and optional headers contentType: application/octet-stream headers: type: object properties: Nats-Msg-Id: type: string description: Optional message deduplication ID payload: type: object description: >- Message payload. NATS is payload-agnostic and supports any binary or text content. RequestMessage: name: RequestMessage title: NATS Request Message summary: A request message with an auto-generated reply subject contentType: application/json headers: type: object properties: Nats-Msg-Id: type: string description: Optional message deduplication ID payload: type: object description: Request payload ReplyMessage: name: ReplyMessage title: NATS Reply Message summary: A reply message sent in response to a request contentType: application/json payload: type: object description: Reply payload JetStreamMessage: name: JetStreamMessage title: JetStream Message summary: >- A persistent message stored in a JetStream stream with delivery tracking and acknowledgment support contentType: application/json headers: type: object properties: Nats-Msg-Id: type: string description: Message deduplication ID Nats-Expected-Stream: type: string description: Expected stream name for publish verification Nats-Expected-Last-Msg-Id: type: string description: Expected last message ID for optimistic concurrency Nats-Expected-Last-Sequence: type: string description: Expected last sequence for optimistic concurrency Nats-Expected-Last-Subject-Sequence: type: string description: Expected last subject sequence payload: type: object description: Message payload stored in the stream JetStreamPublishAck: name: JetStreamPublishAck title: JetStream Publish Acknowledgment summary: Acknowledgment returned after a successful JetStream publish contentType: application/json payload: type: object properties: stream: type: string description: Name of the stream the message was stored in seq: type: integer description: Sequence number assigned to the message duplicate: type: boolean description: Whether the message was a duplicate domain: type: string description: JetStream domain KeyValueEntry: name: KeyValueEntry title: Key-Value Entry summary: A key-value entry with revision tracking contentType: application/json payload: type: object properties: key: type: string description: Entry key value: type: string description: Entry value (base64 encoded if binary) revision: type: integer description: Entry revision number created: type: string format: date-time description: Entry creation timestamp operation: type: string enum: - PUT - DEL - PURGE description: Operation type bucket: type: string description: Bucket name ObjectStoreMeta: name: ObjectStoreMeta title: Object Store Metadata summary: Metadata for an object stored in the Object Store contentType: application/json payload: type: object properties: name: type: string description: Object name description: type: string description: Object description size: type: integer description: Object size in bytes chunks: type: integer description: Number of chunks bucket: type: string description: Bucket name nuid: type: string description: Unique object identifier digest: type: string description: Object digest for integrity verification deleted: type: boolean description: Whether the object has been deleted