JetStream API Headers

This document provides a comprehensive reference for all headers used in JetStream operations. These headers are used for message publishing, delivery, and various JetStream features.

Message Publishing Headers

Headers used when publishing messages to JetStream streams.

Message Identification and Deduplication

Header	Value	Description
Nats-Msg-Id	Unique message ID	Unique message ID for deduplication. Messages with the same ID within the deduplication window will be rejected as duplicates.
Nats-Expected-Last-Msg-Id	Message ID	Message will only be stored if the last message ID matches this value

Expected State Headers

These headers enforce expected state conditions when publishing. If conditions are not met, the publish will fail.

Header	Value	Description
Nats-Expected-Stream	Stream name	Verifies the message is being published to the expected stream
Nats-Expected-Last-Sequence	Sequence number	Message will only be stored if the stream's last sequence matches this value
Nats-Expected-Last-Subject-Sequence	Sequence number	Message will only be stored if the last sequence for this subject matches this value
Nats-Expected-Last-Subject-Sequence-Subject	Subject	Specifies the subject for the expected last subject sequence check

Message Rollup

Header	Value	Description
Nats-Rollup	sub or all	Indicates this message should replace previous messages. sub replaces all previous messages on the same subject, all replaces all messages in the stream
Nats-Schedule-Rollup	String

Message Size

Header	Value	Description
Nats-Msg-Size	Size in bytes	Indicates the size of the message payload

Message TTL

Header	Value	Description
Nats-TTL	Duration string (e.g., 60s, 5m)	Time-to-live for the message. Message will be automatically removed after this duration

Counter Operations

Header	Value	Description
Nats-Incr	Number	Increment value for counter operations
Nats-Counter-Sources	JSON	Sources for counter values in JSON format

Batch Operations

Headers for atomic batch publishing:

Header	Value	Description
Nats-Batch-Id	Batch ID	Unique identifier for the batch
Nats-Batch-Sequence	Sequence number	Sequence number within the batch
Nats-Batch-Commit	1	Marks the final message in a batch, triggering atomic commit

Scheduled Messages

Headers for scheduled message delivery:

Header	Value	Description
Nats-Schedule	Cron expression	Schedule pattern for message delivery
Nats-Schedule-Time-Zone	String
Nats-Schedule-TTL	Duration string (e.g., 60s, 5m)	Time-to-live for the schedule
Nats-Schedule-Target	Subject	Target subject for scheduled delivery
Nats-Schedule-Source	Subject	Source subject for scheduled message delivery
Nats-Scheduler	Scheduler ID	Identifier for the scheduler
Nats-Schedule-Next	RFC3339 timestamp or purge	Next scheduled time or purge indicator

Message Delivery Headers

Headers added by JetStream when delivering messages to consumers.

Stream Information

Header	Value	Description
Nats-Last-Stream	Sequence number	Stream's last sequence at delivery time
Nats-Stream	Stream name	Name of the stream the message came from
Nats-Sequence	Sequence number	Stream sequence number of the message
Nats-Time-Stamp	RFC3339 timestamp	Timestamp when the message was stored
Nats-Subject	Subject	Original subject the message was published to
Nats-Last-Sequence	Sequence number	Last sequence number in the stream when this message was delivered
Nats-UpTo-Sequence	Sequence number	Upper bound sequence for batch delivery
Nats-Stream-Identity	String	JSStreamIdentity is the stream's identity used to reject consumer create on a mismatch, and return the stream identity in the consumer create/reset responses.

Consumer Information

Header	Value	Description
Nats-Last-Consumer	Sequence number	Consumer's last delivered sequence
Nats-Consumer-Stalled	Reply subject	Indicates consumer is stalled with delivery count

Pull Request Headers

Headers used in pull request responses:

Header	Value	Description
Nats-Num-Pending	Count	Number of pending messages for the consumer
Nats-Pending-Messages	Count	Number of pending messages for the pull request
Nats-Pending-Bytes	Size in bytes	Number of pending bytes for the pull request
Nats-Pin-Id	NUID	Priority group pin identifier for the pull request

Source and Mirror Information

Header	Value	Description
Nats-Stream-Source	Stream source info	Information about the source stream in format: stream-name > seq > subject

Response Type

Header	Value	Description
Nats-Response-Type	Response type string	Type of response being sent

API Headers

Headers used in JetStream API requests and responses.

Header	Value	Description
Nats-Required-Api-Level	API level number	Minimum API level required for the request

Marker Headers

Headers used to mark special message types in streams.

Header	Value	Description
Nats-Marker-Reason	MaxAge, Purge, or Remove	Reason for the marker: MaxAge, Purge, or Remove

Authentication and Authorization Headers

Headers used for authentication callout and authorization.

Header	Value	Description
Nats-Request-Info	JSON-encoded client info	Client authorization information for the request
Nats-Server-Xkey	X-Key string	Server X-Key for encrypted auth callout requests

Message Tracing Headers

Headers used for message tracing and diagnostics.

Header	Value	Description
Nats-Trace-Dest	Subject	Destination subject for message tracing
Nats-Trace-Hop	Hop count	Number of hops in the trace
Nats-Trace-Origin-Account	Account name	Origin account for message tracing
Nats-Trace-Only	Boolean flag	Indicates trace-only mode (message is not delivered)

Key-Value Store Headers

Headers used by the NATS Key-Value store built on JetStream.

Header	Value	Description
KV-Operation	PUT, DEL, or PURGE	Type of KV operation: PUT, DEL, or PURGE

Usage Examples

Publishing with Deduplication

Nats-Msg-Id: unique-message-123

Publishing with Expected State

Nats-Expected-Last-Sequence: 42
Nats-Expected-Stream: my-stream

Batch Publishing

Nats-Batch-Id: batch-456
Nats-Batch-Sequence: 1

For the last message in batch:

Nats-Batch-Id: batch-456
Nats-Batch-Sequence: 10
Nats-Batch-Commit: 1

Scheduled Message

Nats-Schedule: 0 */5 * * * *
Nats-Schedule-TTL: 24h
Nats-Schedule-Target: notifications.email

Notes

• Headers are case-sensitive
• Some headers are set automatically by the server and should not be manually set by clients
• Headers prefixed with Nats-Expected- are used for optimistic concurrency control
• The Nats-Rollup header is used in conjunction with the stream's MaxMsgsPerSubject setting
• Batch operations require all messages in a batch to succeed or the entire batch is rejected
• Counter operations are atomic and support distributed counters across clustered streams