Reference
JetStream Protocol
Like the client protocol, the standard way of leveraging JetStream-based functionality is to use a client SDK for your preferred programming language.
However, one important difference is that the JetStream protocol is built on top of the standard client protocol, using standard pub-sub interactions between the client and server.
Overview
All JetStream operations are account-scoped. There are some operations which must be performed by a user within the system account rather than host account. This is noted by the System Account: true flag.
- Account - Account-specific operations.
- Stream API - Operations pertaining to streams.
- Consumer API - Operations pertaining to consumers.
- Meta API - JetStream meta layer API.
- Advisory events - Published notifications for significant events.
- Metrics - Published metrics.
- Errors - Index of JetStream errors.
Account
| Name | Subject | System Account |
|---|---|---|
| Info | $JS.API.INFO | false |
| Purge data | $JS.API.ACCOUNT.PURGE | true |
Info
Retrieves stats and limits for the connected user's account.
Subject
$JS.API.INFO
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/account_info_response.json",
"description": "A response from the JetStream $JS.API.INFO API",
"title": "io.nats.jetstream.api.v1.account_info_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"memory",
"storage",
"streams",
"limits",
"api",
"consumers"
],
"properties": {
"memory": {
"description": "Memory Storage being used for Stream Message storage",
"type": "integer",
"minimum": 0
},
"storage": {
"description": "File Storage being used for Stream Message storage",
"type": "integer",
"minimum": 0
},
"streams": {
"description": "Number of active Streams",
"type": "integer",
"minimum": 0
},
"consumers": {
"description": "Number of active Consumers",
"type": "integer",
"minimum": 0
},
"domain": {
"description": "The JetStream domain this account is in",
"type": "string"
},
"limits": {
"type": "object",
"additionalProperties": false,
"required": [
"max_consumers",
"max_memory",
"max_storage",
"max_streams"
],
"properties": {
"max_memory": {
"type": "integer",
"description": "The maximum amount of Memory storage Stream Messages may consume",
"minimum": -1
},
"max_storage": {
"type": "integer",
"description": "The maximum amount of File storage Stream Messages may consume",
"minimum": -1
},
"max_streams": {
"type": "integer",
"description": "The maximum number of Streams an account can create",
"minimum": -1
},
"max_consumers": {
"type": "integer",
"description": "The maximum number of Consumer an account can create",
"minimum": -1
},
"max_bytes_required": {
"type": "boolean",
"description": "Indicates if Streams created in this account requires the max_bytes property set",
"default": false
},
"max_ack_pending": {
"type": "integer",
"description": "The maximum number of outstanding ACKs any consumer may configure"
},
"memory_max_stream_bytes": {
"type": "integer",
"description": "The maximum size any single memory stream may be",
"minimum": -1,
"default": -1
},
"storage_max_stream_bytes": {
"type": "integer",
"description": "The maximum size any single storage based stream may be",
"minimum": -1,
"default": -1
}
}
},
"tiers": {
"type": "object",
"patternProperties": {
".*": {
"type": "object",
"required": [
"memory",
"storage",
"streams",
"limits",
"consumers"
],
"properties": {
"memory": {
"description": "Memory Storage being used for Stream Message storage",
"type": "integer",
"minimum": 0
},
"storage": {
"description": "File Storage being used for Stream Message storage",
"type": "integer",
"minimum": 0
},
"streams": {
"description": "Number of active Streams",
"type": "integer",
"minimum": 0
},
"consumers": {
"description": "Number of active Consumers",
"type": "integer",
"minimum": 0
},
"limits": {
"type": "object",
"additionalProperties": false,
"required": [
"max_consumers",
"max_memory",
"max_storage",
"max_streams"
],
"properties": {
"max_memory": {
"type": "integer",
"description": "The maximum amount of Memory storage Stream Messages may consume",
"minimum": -1
},
"max_storage": {
"type": "integer",
"description": "The maximum amount of File storage Stream Messages may consume",
"minimum": -1
},
"max_streams": {
"type": "integer",
"description": "The maximum number of Streams an account can create",
"minimum": -1
},
"max_consumers": {
"type": "integer",
"description": "The maximum number of Consumer an account can create",
"minimum": -1
},
"max_bytes_required": {
"type": "boolean",
"description": "Indicates if Streams created in this account requires the max_bytes property set",
"default": false
},
"max_ack_pending": {
"type": "integer",
"description": "The maximum number of outstanding ACKs any consumer may configure"
},
"memory_max_stream_bytes": {
"type": "integer",
"description": "The maximum size any single memory stream may be",
"minimum": -1,
"default": -1
},
"storage_max_stream_bytes": {
"type": "integer",
"description": "The maximum size any single storage based stream may be",
"minimum": -1,
"default": -1
}
}
}
}
}
}
},
"api": {
"type": "object",
"required": [
"total",
"errors"
],
"properties": {
"total": {
"description": "Total number of API requests received for this account",
"minimum": 0,
"type": "integer"
},
"errors": {
"description": "API requests that resulted in an error response",
"minimum": 0,
"type": "integer"
}
}
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.account_info_response"
}
}
}Purge data
Initiates a purge for all stream data in the connected user's account.
Subject
$JS.API.ACCOUNT.PURGE
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/meta_account_purge_response.json",
"description": "A response from the JetStream $JS.API.ACCOUNT.PURGE API",
"title": "io.nats.jetstream.api.v1.account_purge_response",
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"properties": {
"initiated": {
"type": "boolean",
"description": "If the purge operation was succesfully started",
"default": false
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.account_purge_response"
}
}
}Stream API
| Name | Subject | System Account |
|---|---|---|
| List stream names | $JS.API.STREAM.NAMES | false |
| List streams | $JS.API.STREAM.LIST | false |
| Create stream | $JS.API.STREAM.CREATE.{stream} | false |
| Update stream | $JS.API.STREAM.UPDATE.{stream} | false |
| Delete stream | $JS.API.STREAM.DELETE.{stream} | false |
| Purge stream data | $JS.API.STREAM.PURGE.{stream} | false |
| Delete stream message | $JS.API.STREAM.MSG.DELETE.{stream} | false |
| Get stream message | $JS.API.STREAM.MSG.GET.{stream} | false |
| Direct get stream message | $JS.API.DIRECT.GET.{stream} | false |
| Get stream info | $JS.API.STREAM.INFO.{stream} | false |
| Initiate stream backup | $JS.API.STREAM.SNAPSHOT.{stream} | false |
| Initiate stream restore | $JS.API.STREAM.RESTORE.{stream} | false |
| Create stream template | $JS.API.STREAM.TEMPLATE.CREATE.{name} | false |
| Delete stream template | $JS.API.STREAM.TEMPLATE.DELETE.{name} | false |
| Stream template info | $JS.API.STREAM.TEMPLATE.INFO.{name} | false |
| List stream template names | $JS.API.STREAM.TEMPLATE.NAMES | false |
| Remove peer from clustered stream | $JS.API.STREAM.PEER.REMOVE.{stream} | false |
| Stepdown leader for a clustered stream | $JS.API.STREAM.LEADER.STEPDOWN.{stream} | false |
| Move stream | $JS.API.ACCOUNT.STREAM.MOVE.{stream}.{??} | true |
| Cancel move stream | $JS.API.ACCOUNT.STREAM.CANCEL_MOVE.{stream}.{??} | true |
| Publish Ack | _INBOX.*.*.* | false |
List stream names
Paginated list of stream names.
Subject
$JS.API.STREAM.NAMES
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_names_request.json",
"description": "A request to the JetStream $JS.API.STREAM.NAMES API",
"title": "io.nats.jetstream.api.v1.stream_names_request",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Limit the list to streams matching this subject filter"
},
"offset": {
"type": "integer",
"minimum": 0
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_names_response.json",
"description": "A response from the JetStream $JS.API.STREAM.NAMES API",
"title": "io.nats.jetstream.api.v1.stream_names_response",
"type": "object",
"required": [
"type"
],
"allOf": [
{
"type": "object",
"required": [
"total",
"offset",
"limit"
],
"properties": {
"total": {
"type": "integer",
"minimum": 0
},
"offset": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"minimum": 0
}
}
}
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"streams"
],
"properties": {
"consumers": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_names_response"
}
}
}List streams
Paginated list known streams including their current configuration and state.
Subject
$JS.API.STREAM.LIST
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_list_request.json",
"description": "A request to the JetStream $JS.API.STREAM.LIST API",
"title": "io.nats.jetstream.api.v1.stream_list_request",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "Limit the list to streams matching this subject filter"
},
"offset": {
"type": "integer",
"minimum": 0
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_list_response.json",
"description": "A response from the JetStream $JS.API.STREAM.LIST API",
"title": "io.nats.jetstream.api.v1.stream_list_response",
"type": "object",
"required": [
"type"
],
"allOf": [
{
"type": "object",
"required": [
"total",
"offset",
"limit"
],
"properties": {
"total": {
"type": "integer",
"minimum": 0
},
"offset": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"minimum": 0
}
}
}
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"streams"
],
"properties": {
"streams": {
"description": "Full Stream information for each known Stream",
"type": "array",
"items": {
"type": "object",
"required": [
"config",
"state",
"created"
],
"properties": {
"config": {
"type": "object",
"description": "The active configuration for the Stream",
"allOf": [
{
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
]
},
"state": {
"type": "object",
"description": "Detail about the current State of the Stream",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"messages",
"bytes",
"first_seq",
"last_seq",
"consumer_count"
],
"properties": {
"messages": {
"description": "Number of messages stored in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"bytes": {
"description": "Combined size of all messages in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_seq": {
"description": "Sequence number of the first message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_ts": {
"type": "string",
"description": "The timestamp of the first message in the Stream"
},
"last_seq": {
"description": "Sequence number of the last message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"last_ts": {
"type": "string",
"description": "The timestamp of the last message in the Stream"
},
"deleted": {
"description": "IDs of messages that were deleted using the Message Delete API or Interest based streams removing messages out of order",
"type": "array",
"minLength": 0,
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"subjects": {
"description": "Subjects and their message counts when a subjects_filter was set",
"type": "object",
"additionalProperties": {
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
},
"num_subjects": {
"description": "The number of unique subjects held in the stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_deleted": {
"description": "The number of deleted messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"lost": {
"type": "object",
"description": "Records messages that were damaged and unrecoverable",
"properties": {
"msgs": {
"type": [
"array",
"null"
],
"description": "The messages that were lost",
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"bytes": {
"description": "The number of bytes that were lost",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
}
},
"consumer_count": {
"description": "Number of Consumers attached to the Stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
}
}
}
]
},
"created": {
"description": "Timestamp when the stream was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"ts": {
"description": "The server time the stream info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"mirror": {
"required": [
"name",
"lag",
"active"
],
"type": "object",
"description": "Information about an upstream stream source in a mirror",
"properties": {
"name": {
"type": "string",
"description": "The name of the Stream being replicated"
},
"filter_subject": {
"type": "string",
"description": "The subject filter to apply to the messages"
},
"subject_transform_dest": {
"type": "string",
"description": "The subject transform destination to apply to the messages"
},
"lag": {
"description": "How many messages behind the mirror operation is",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"active": {
"description": "When last the mirror had activity, in nanoseconds. Value will be -1 when there has been no activity.",
"minimum": -1,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
"sources": {
"type": "array",
"description": "Streams being sourced into this Stream",
"items": {
"required": [
"name",
"lag",
"active"
],
"type": "object",
"description": "Information about an upstream stream source in a mirror",
"properties": {
"name": {
"type": "string",
"description": "The name of the Stream being replicated"
},
"filter_subject": {
"type": "string",
"description": "The subject filter to apply to the messages"
},
"subject_transform_dest": {
"type": "string",
"description": "The subject transform destination to apply to the messages"
},
"lag": {
"description": "How many messages behind the mirror operation is",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"active": {
"description": "When last the mirror had activity, in nanoseconds. Value will be -1 when there has been no activity.",
"minimum": -1,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
},
"alternates": {
"type": "array",
"description": "List of mirrors sorted by priority",
"items": {
"type": "object",
"description": "An alternate location to read mirrored data",
"required": [
"name",
"cluster"
],
"properties": {
"name": {
"type": "string",
"description": "The mirror stream name"
},
"cluster": {
"type": "string",
"description": "The name of the cluster holding the stream"
},
"domain": {
"type": "string",
"description": "The domain holding the string"
}
}
}
}
}
}
},
"missing": {
"description": "In clustered environments gathering Stream info might time out, this list would be a list of Streams for which information was not obtainable",
"type": "array",
"items": {
"type": "string"
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_list_response"
}
}
}Create stream
Create a stream with the provided configuration.
Subject
$JS.API.STREAM.CREATE.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_create_request.json",
"description": "A request to the JetStream $JS.API.STREAM.CREATE API",
"title": "io.nats.jetstream.api.v1.stream_create_request",
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
]
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_create_response.json",
"description": "A response from the JetStream $JS.API.STREAM.CREATE API",
"title": "io.nats.jetstream.api.v1.stream_create_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"config",
"state",
"created"
],
"properties": {
"config": {
"type": "object",
"description": "The active configuration for the Stream",
"allOf": [
{
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
]
},
"state": {
"type": "object",
"description": "Detail about the current State of the Stream",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"messages",
"bytes",
"first_seq",
"last_seq",
"consumer_count"
],
"properties": {
"messages": {
"description": "Number of messages stored in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"bytes": {
"description": "Combined size of all messages in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_seq": {
"description": "Sequence number of the first message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_ts": {
"type": "string",
"description": "The timestamp of the first message in the Stream"
},
"last_seq": {
"description": "Sequence number of the last message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"last_ts": {
"type": "string",
"description": "The timestamp of the last message in the Stream"
},
"deleted": {
"description": "IDs of messages that were deleted using the Message Delete API or Interest based streams removing messages out of order",
"type": "array",
"minLength": 0,
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"subjects": {
"description": "Subjects and their message counts when a subjects_filter was set",
"type": "object",
"additionalProperties": {
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
},
"num_subjects": {
"description": "The number of unique subjects held in the stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_deleted": {
"description": "The number of deleted messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"lost": {
"type": "object",
"description": "Records messages that were damaged and unrecoverable",
"properties": {
"msgs": {
"type": [
"array",
"null"
],
"description": "The messages that were lost",
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"bytes": {
"description": "The number of bytes that were lost",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
}
},
"consumer_count": {
"description": "Number of Consumers attached to the Stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
}
}
}
]
},
"created": {
"description": "Timestamp when the stream was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"ts": {
"description": "The server time the stream info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"mirror": {
"required": [
"name",
"lag",
"active"
],
"type": "object",
"description": "Information about an upstream stream source in a mirror",
"properties": {
"name": {
"type": "string",
"description": "The name of the Stream being replicated"
},
"filter_subject": {
"type": "string",
"description": "The subject filter to apply to the messages"
},
"subject_transform_dest": {
"type": "string",
"description": "The subject transform destination to apply to the messages"
},
"lag": {
"description": "How many messages behind the mirror operation is",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"active": {
"description": "When last the mirror had activity, in nanoseconds. Value will be -1 when there has been no activity.",
"minimum": -1,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
"sources": {
"type": "array",
"description": "Streams being sourced into this Stream",
"items": {
"required": [
"name",
"lag",
"active"
],
"type": "object",
"description": "Information about an upstream stream source in a mirror",
"properties": {
"name": {
"type": "string",
"description": "The name of the Stream being replicated"
},
"filter_subject": {
"type": "string",
"description": "The subject filter to apply to the messages"
},
"subject_transform_dest": {
"type": "string",
"description": "The subject transform destination to apply to the messages"
},
"lag": {
"description": "How many messages behind the mirror operation is",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"active": {
"description": "When last the mirror had activity, in nanoseconds. Value will be -1 when there has been no activity.",
"minimum": -1,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
},
"alternates": {
"type": "array",
"description": "List of mirrors sorted by priority",
"items": {
"type": "object",
"description": "An alternate location to read mirrored data",
"required": [
"name",
"cluster"
],
"properties": {
"name": {
"type": "string",
"description": "The mirror stream name"
},
"cluster": {
"type": "string",
"description": "The name of the cluster holding the stream"
},
"domain": {
"type": "string",
"description": "The domain holding the string"
}
}
}
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_create_response"
}
}
}Update stream
Update a stream with the provided configuration.
Subject
$JS.API.STREAM.UPDATE.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_update_request.json",
"description": "A request to the JetStream $JS.API.STREAM.UPDATE API",
"title": "io.nats.jetstream.api.v1.stream_update_request",
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
]
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_update_response.json",
"description": "A response from the JetStream $JS.API.STREAM.UPDATE API",
"title": "io.nats.jetstream.api.v1.stream_update_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"config",
"state",
"created"
],
"properties": {
"config": {
"type": "object",
"description": "The active configuration for the Stream",
"allOf": [
{
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
]
},
"state": {
"type": "object",
"description": "Detail about the current State of the Stream",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"messages",
"bytes",
"first_seq",
"last_seq",
"consumer_count"
],
"properties": {
"messages": {
"description": "Number of messages stored in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"bytes": {
"description": "Combined size of all messages in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_seq": {
"description": "Sequence number of the first message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_ts": {
"type": "string",
"description": "The timestamp of the first message in the Stream"
},
"last_seq": {
"description": "Sequence number of the last message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"last_ts": {
"type": "string",
"description": "The timestamp of the last message in the Stream"
},
"deleted": {
"description": "IDs of messages that were deleted using the Message Delete API or Interest based streams removing messages out of order",
"type": "array",
"minLength": 0,
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"subjects": {
"description": "Subjects and their message counts when a subjects_filter was set",
"type": "object",
"additionalProperties": {
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
},
"num_subjects": {
"description": "The number of unique subjects held in the stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_deleted": {
"description": "The number of deleted messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"lost": {
"type": "object",
"description": "Records messages that were damaged and unrecoverable",
"properties": {
"msgs": {
"type": [
"array",
"null"
],
"description": "The messages that were lost",
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"bytes": {
"description": "The number of bytes that were lost",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
}
},
"consumer_count": {
"description": "Number of Consumers attached to the Stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
}
}
}
]
},
"created": {
"description": "Timestamp when the stream was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"ts": {
"description": "The server time the stream info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"mirror": {
"required": [
"name",
"lag",
"active"
],
"type": "object",
"description": "Information about an upstream stream source in a mirror",
"properties": {
"name": {
"type": "string",
"description": "The name of the Stream being replicated"
},
"filter_subject": {
"type": "string",
"description": "The subject filter to apply to the messages"
},
"subject_transform_dest": {
"type": "string",
"description": "The subject transform destination to apply to the messages"
},
"lag": {
"description": "How many messages behind the mirror operation is",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"active": {
"description": "When last the mirror had activity, in nanoseconds. Value will be -1 when there has been no activity.",
"minimum": -1,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
"sources": {
"type": "array",
"description": "Streams being sourced into this Stream",
"items": {
"required": [
"name",
"lag",
"active"
],
"type": "object",
"description": "Information about an upstream stream source in a mirror",
"properties": {
"name": {
"type": "string",
"description": "The name of the Stream being replicated"
},
"filter_subject": {
"type": "string",
"description": "The subject filter to apply to the messages"
},
"subject_transform_dest": {
"type": "string",
"description": "The subject transform destination to apply to the messages"
},
"lag": {
"description": "How many messages behind the mirror operation is",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"active": {
"description": "When last the mirror had activity, in nanoseconds. Value will be -1 when there has been no activity.",
"minimum": -1,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
},
"alternates": {
"type": "array",
"description": "List of mirrors sorted by priority",
"items": {
"type": "object",
"description": "An alternate location to read mirrored data",
"required": [
"name",
"cluster"
],
"properties": {
"name": {
"type": "string",
"description": "The mirror stream name"
},
"cluster": {
"type": "string",
"description": "The name of the cluster holding the stream"
},
"domain": {
"type": "string",
"description": "The domain holding the string"
}
}
}
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_update_response"
}
}
}Delete stream
Delete a stream.
Subject
$JS.API.STREAM.DELETE.{stream}
Params:
stream- stream
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_delete_response.json",
"description": "A response from the JetStream $JS.API.STREAM.DELETE API",
"title": "io.nats.jetstream.api.v1.stream_delete_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"success"
],
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_delete_response"
}
}
}Purge stream data
Purge messages in the stream. The request payload provides a way to choose which messages to purge.
Subject
$JS.API.STREAM.PURGE.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_purge_request.json",
"description": "A request to the JetStream $JS.API.STREAM.PURGE API",
"title": "io.nats.jetstream.api.v1.stream_purge_request",
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Restrict purging to messages that match this subject"
},
"seq": {
"description": "Purge all messages up to but not including the message with this sequence. Can be combined with subject filter but not the keep option",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"keep": {
"description": "Ensures this many messages are present after the purge. Can be combined with the subject filter but not the sequence",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_purge_response.json",
"description": "A response from the JetStream $JS.API.STREAM.PURGE API",
"title": "io.nats.jetstream.api.v1.stream_purge_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"success",
"purged"
],
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"purged": {
"description": "Number of messages purged from the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_purge_response"
}
}
}Delete stream message
Delete a specific message in the stream by sequence.
Subject
$JS.API.STREAM.MSG.DELETE.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_msg_delete_request.json",
"description": "A request to the JetStream $JS.API.STREAM.MSG.DELETE API",
"title": "io.nats.jetstream.api.v1.stream_msg_delete_request",
"type": "object",
"required": [
"seq"
],
"properties": {
"seq": {
"description": "Stream sequence number of the message to delete",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"no_erase": {
"type": "boolean",
"description": "Default will securely remove a message and rewrite the data with random data, set this to true to only remove the message"
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_msg_delete_response.json",
"description": "A response from the JetStream $JS.API.STREAM.MSG.DELETE API",
"title": "io.nats.jetstream.api.v1.stream_msg_delete_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"success"
],
"properties": {
"success": {
"type": "boolean"
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_msg_delete_response"
}
}
}Get stream message
Get a specific message in the stream by sequence or the latest by subject.
Subject
$JS.API.STREAM.MSG.GET.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_msg_get_request.json",
"description": "A request to the JetStream $JS.API.STREAM.MSG.GET API",
"title": "io.nats.jetstream.api.v1.stream_msg_get_request",
"type": "object",
"properties": {
"seq": {
"type": "integer",
"description": "Stream sequence number of the message to retrieve, cannot be combined with last_by_subj"
},
"last_by_subj": {
"type": "string",
"description": "Retrieves the last message for a given subject, cannot be combined with seq"
},
"next_by_subj": {
"type": "string",
"description": "Combined with sequence gets the next message for a subject with the given sequence or higher"
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_msg_get_response.json",
"description": "A response from the JetStream $JS.API.STREAM.MSG.GET API",
"title": "io.nats.jetstream.api.v1.stream_msg_get_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "object",
"additionalProperties": false,
"required": [
"subject",
"seq",
"time"
],
"properties": {
"subject": {
"type": "string",
"description": "The subject the message was originally received on",
"minLength": 1
},
"seq": {
"description": "The sequence number of the message in the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"data": {
"type": "string",
"description": "The base64 encoded payload of the message body",
"minLength": 0
},
"time": {
"type": "string",
"description": "The time the message was received"
},
"hdrs": {
"type": "string",
"description": "Base64 encoded headers for the message"
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_msg_get_response"
}
}
}Direct get stream message
Get a specific message in the stream by sequence or the latest by subject.
Subject
$JS.API.DIRECT.GET.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_msg_get_request.json",
"description": "A request to the JetStream $JS.API.STREAM.MSG.GET API",
"title": "io.nats.jetstream.api.v1.stream_msg_get_request",
"type": "object",
"properties": {
"seq": {
"type": "integer",
"description": "Stream sequence number of the message to retrieve, cannot be combined with last_by_subj"
},
"last_by_subj": {
"type": "string",
"description": "Retrieves the last message for a given subject, cannot be combined with seq"
},
"next_by_subj": {
"type": "string",
"description": "Combined with sequence gets the next message for a subject with the given sequence or higher"
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_msg_get_response.json",
"description": "A response from the JetStream $JS.API.STREAM.MSG.GET API",
"title": "io.nats.jetstream.api.v1.stream_msg_get_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "object",
"additionalProperties": false,
"required": [
"subject",
"seq",
"time"
],
"properties": {
"subject": {
"type": "string",
"description": "The subject the message was originally received on",
"minLength": 1
},
"seq": {
"description": "The sequence number of the message in the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"data": {
"type": "string",
"description": "The base64 encoded payload of the message body",
"minLength": 0
},
"time": {
"type": "string",
"description": "The time the message was received"
},
"hdrs": {
"type": "string",
"description": "Base64 encoded headers for the message"
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_msg_get_response"
}
}
}Get stream info
Get the current configuration and state of the stream.
Subject
$JS.API.STREAM.INFO.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_info_request.json",
"description": "A request to the JetStream $JS.API.STREAM.INFO API",
"title": "io.nats.jetstream.api.v1.stream_info_request",
"type": "object",
"properties": {
"deleted_details": {
"type": "boolean",
"description": "When true will result in a full list of deleted message IDs being returned in the info response"
},
"subjects_filter": {
"type": "string",
"description": "When set will return a list of subjects and how many messages they hold for all matching subjects. Filter is a standard NATS subject wildcard pattern."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Paging offset when retrieving pages of subjet details"
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_info_response.json",
"description": "A response from the JetStream $JS.API.STREAM.INFO API",
"title": "io.nats.jetstream.api.v1.stream_info_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"config",
"state",
"created"
],
"properties": {
"config": {
"type": "object",
"description": "The active configuration for the Stream",
"allOf": [
{
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
]
},
"state": {
"type": "object",
"description": "Detail about the current State of the Stream",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"messages",
"bytes",
"first_seq",
"last_seq",
"consumer_count"
],
"properties": {
"messages": {
"description": "Number of messages stored in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"bytes": {
"description": "Combined size of all messages in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_seq": {
"description": "Sequence number of the first message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_ts": {
"type": "string",
"description": "The timestamp of the first message in the Stream"
},
"last_seq": {
"description": "Sequence number of the last message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"last_ts": {
"type": "string",
"description": "The timestamp of the last message in the Stream"
},
"deleted": {
"description": "IDs of messages that were deleted using the Message Delete API or Interest based streams removing messages out of order",
"type": "array",
"minLength": 0,
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"subjects": {
"description": "Subjects and their message counts when a subjects_filter was set",
"type": "object",
"additionalProperties": {
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
},
"num_subjects": {
"description": "The number of unique subjects held in the stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_deleted": {
"description": "The number of deleted messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"lost": {
"type": "object",
"description": "Records messages that were damaged and unrecoverable",
"properties": {
"msgs": {
"type": [
"array",
"null"
],
"description": "The messages that were lost",
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"bytes": {
"description": "The number of bytes that were lost",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
}
},
"consumer_count": {
"description": "Number of Consumers attached to the Stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
}
}
}
]
},
"created": {
"description": "Timestamp when the stream was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"ts": {
"description": "The server time the stream info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"mirror": {
"required": [
"name",
"lag",
"active"
],
"type": "object",
"description": "Information about an upstream stream source in a mirror",
"properties": {
"name": {
"type": "string",
"description": "The name of the Stream being replicated"
},
"filter_subject": {
"type": "string",
"description": "The subject filter to apply to the messages"
},
"subject_transform_dest": {
"type": "string",
"description": "The subject transform destination to apply to the messages"
},
"lag": {
"description": "How many messages behind the mirror operation is",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"active": {
"description": "When last the mirror had activity, in nanoseconds. Value will be -1 when there has been no activity.",
"minimum": -1,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
"sources": {
"type": "array",
"description": "Streams being sourced into this Stream",
"items": {
"required": [
"name",
"lag",
"active"
],
"type": "object",
"description": "Information about an upstream stream source in a mirror",
"properties": {
"name": {
"type": "string",
"description": "The name of the Stream being replicated"
},
"filter_subject": {
"type": "string",
"description": "The subject filter to apply to the messages"
},
"subject_transform_dest": {
"type": "string",
"description": "The subject transform destination to apply to the messages"
},
"lag": {
"description": "How many messages behind the mirror operation is",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"active": {
"description": "When last the mirror had activity, in nanoseconds. Value will be -1 when there has been no activity.",
"minimum": -1,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
},
"alternates": {
"type": "array",
"description": "List of mirrors sorted by priority",
"items": {
"type": "object",
"description": "An alternate location to read mirrored data",
"required": [
"name",
"cluster"
],
"properties": {
"name": {
"type": "string",
"description": "The mirror stream name"
},
"cluster": {
"type": "string",
"description": "The name of the cluster holding the stream"
},
"domain": {
"type": "string",
"description": "The domain holding the string"
}
}
}
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_info_response"
},
"total": {
"type": "integer",
"minimum": 0
},
"offset": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"minimum": 0
}
}
}Initiate stream backup
Initiates a backup of a stream.
Subject
$JS.API.STREAM.SNAPSHOT.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_snapshot_request.json",
"description": "A request to the JetStream $JS.API.STREAM.SNAPSHOT API",
"title": "io.nats.jetstream.api.v1.stream_snapshot_request",
"type": "object",
"required": [
"deliver_subject"
],
"additionalProperties": false,
"properties": {
"deliver_subject": {
"type": "string",
"description": "The NATS subject where the snapshot will be delivered",
"minLength": 1
},
"no_consumers": {
"type": "boolean",
"description": "When true consumer states and configurations will not be present in the snapshot"
},
"chunk_size": {
"type": "integer",
"description": "The size of data chunks to send to deliver_subject",
"minimum": 1024,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"maximum": 9223372036854776000
},
"jsck": {
"type": "boolean",
"description": "Check all message's checksums prior to snapshot",
"default": false
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_snapshot_response.json",
"description": "A response from the JetStream $JS.API.STREAM.SNAPSHOT API",
"title": "io.nats.jetstream.api.v1.stream_snapshot_response",
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"config",
"state"
],
"type": "object",
"properties": {
"config": {
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"state": {
"type": "object",
"additionalProperties": false,
"required": [
"messages",
"bytes",
"first_seq",
"last_seq",
"consumer_count"
],
"properties": {
"messages": {
"description": "Number of messages stored in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"bytes": {
"description": "Combined size of all messages in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_seq": {
"description": "Sequence number of the first message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_ts": {
"type": "string",
"description": "The timestamp of the first message in the Stream"
},
"last_seq": {
"description": "Sequence number of the last message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"last_ts": {
"type": "string",
"description": "The timestamp of the last message in the Stream"
},
"deleted": {
"description": "IDs of messages that were deleted using the Message Delete API or Interest based streams removing messages out of order",
"type": "array",
"minLength": 0,
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"subjects": {
"description": "Subjects and their message counts when a subjects_filter was set",
"type": "object",
"additionalProperties": {
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
},
"num_subjects": {
"description": "The number of unique subjects held in the stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_deleted": {
"description": "The number of deleted messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"lost": {
"type": "object",
"description": "Records messages that were damaged and unrecoverable",
"properties": {
"msgs": {
"type": [
"array",
"null"
],
"description": "The messages that were lost",
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"bytes": {
"description": "The number of bytes that were lost",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
}
},
"consumer_count": {
"description": "Number of Consumers attached to the Stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_snapshot_response"
}
}
}Initiate stream restore
Initiates a restore of a stream.
Subject
$JS.API.STREAM.RESTORE.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_restore_request.json",
"description": "A response from the JetStream $JS.API.STREAM.RESTORE API",
"title": "io.nats.jetstream.api.v1.stream_restore_request",
"type": "object",
"required": [
"config",
"state"
],
"properties": {
"config": {
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"state": {
"type": "object",
"additionalProperties": false,
"required": [
"messages",
"bytes",
"first_seq",
"last_seq",
"consumer_count"
],
"properties": {
"messages": {
"description": "Number of messages stored in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"bytes": {
"description": "Combined size of all messages in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_seq": {
"description": "Sequence number of the first message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"first_ts": {
"type": "string",
"description": "The timestamp of the first message in the Stream"
},
"last_seq": {
"description": "Sequence number of the last message in the Stream",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"last_ts": {
"type": "string",
"description": "The timestamp of the last message in the Stream"
},
"deleted": {
"description": "IDs of messages that were deleted using the Message Delete API or Interest based streams removing messages out of order",
"type": "array",
"minLength": 0,
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"subjects": {
"description": "Subjects and their message counts when a subjects_filter was set",
"type": "object",
"additionalProperties": {
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
},
"num_subjects": {
"description": "The number of unique subjects held in the stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_deleted": {
"description": "The number of deleted messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"lost": {
"type": "object",
"description": "Records messages that were damaged and unrecoverable",
"properties": {
"msgs": {
"type": [
"array",
"null"
],
"description": "The messages that were lost",
"items": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
},
"bytes": {
"description": "The number of bytes that were lost",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
}
}
},
"consumer_count": {
"description": "Number of Consumers attached to the Stream",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
}
}
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_restore_response.json",
"description": "A response from the JetStream $JS.API.STREAM.RESTORE API",
"title": "io.nats.jetstream.api.v1.stream_restore_response",
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"deliver_subject"
],
"type": "object",
"properties": {
"deliver_subject": {
"type": "string",
"description": "The Subject to send restore chunks to",
"minLength": 1
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_restore_response"
}
}
}Create stream template
Templates are no longer recommended.
Create a stream template.
Subject
$JS.API.STREAM.TEMPLATE.CREATE.{name}
Params:
name- name
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_template_create_request.json",
"description": "A request to the JetStream $JS.API.STREAM.TEMPLATE.CREATE API",
"title": "io.nats.jetstream.api.v1.stream_template_create_request",
"type": "object",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"name",
"config",
"max_streams"
],
"properties": {
"name": {
"type": "string",
"description": "A unique name for the Template"
},
"config": {
"description": "The template configuration to create Streams with",
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"max_streams": {
"type": "integer",
"description": "The maximum number of streams to allow using this Template",
"minimum": -1
}
}
}
]
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_template_create_response.json",
"description": "A response from the JetStream $JS.API.STREAM.TEMPLATE.CREATE API",
"title": "io.nats.jetstream.api.v1.stream_template_create_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"config",
"streams"
],
"properties": {
"config": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"config",
"max_streams"
],
"properties": {
"name": {
"type": "string",
"description": "A unique name for the Template"
},
"config": {
"description": "The template configuration to create Streams with",
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"max_streams": {
"type": "integer",
"description": "The maximum number of streams to allow using this Template",
"minimum": -1
}
}
},
"streams": {
"description": "List of Streams managed by this Template",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_template_create_response"
}
}
}Delete stream template
Templates are no longer recommended.
Delete a stream template.
Subject
$JS.API.STREAM.TEMPLATE.DELETE.{name}
Params:
name- name
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_template_delete_response.json",
"description": "A response from the JetStream $JS.API.STREAM.TEMPLATE.DELETE API",
"title": "io.nats.jetstream.api.v1.stream_template_delete_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"success"
],
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_template_delete_response"
}
}
}Stream template info
Templates are no longer recommended.
Info about a stream template.
Subject
$JS.API.STREAM.TEMPLATE.INFO.{name}
Params:
name- name
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_template_info_response.json",
"description": "A response from the JetStream $JS.API.STREAM.TEMPLATE.INFO API",
"title": "io.nats.jetstream.api.v1.stream_template_info_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"config",
"streams"
],
"properties": {
"config": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"config",
"max_streams"
],
"properties": {
"name": {
"type": "string",
"description": "A unique name for the Template"
},
"config": {
"description": "The template configuration to create Streams with",
"type": "object",
"required": [
"retention",
"max_consumers",
"max_msgs",
"max_bytes",
"max_age",
"storage",
"num_replicas"
],
"additionalProperties": false,
"properties": {
"name": {
"description": "A unique name for the Stream, empty for Stream Templates.",
"type": "string",
"pattern": "^[^.*>]*$",
"minLength": 0
},
"description": {
"description": "A short description of the purpose of this stream",
"type": "string",
"maxLength": 4096
},
"subjects": {
"description": "A list of subjects to consume, supports wildcards. Must be empty when a mirror is configured. May be empty when sources are configured.",
"type": "array",
"minLength": 0,
"items": {
"type": "string"
}
},
"subject_transform": {
"description": "Subject transform to apply to matching messages",
"type": "object",
"required": [
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The subject transform source"
},
"dest": {
"type": "string",
"description": "The subject transform destination"
}
}
},
"retention": {
"description": "How messages are retained in the Stream, once this is exceeded old messages are removed.",
"type": "string",
"enum": [
"limits",
"interest",
"workqueue"
],
"default": "limits"
},
"max_consumers": {
"description": "How many Consumers can be defined for a given Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs": {
"description": "How many messages may be in a Stream, oldest messages will be removed if the Stream exceeds this size. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msgs_per_subject": {
"description": "For wildcard streams ensure that for every unique subject this many messages are kept - a per subject retention limit",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_bytes": {
"description": "How big the Stream may be, when the combined stream size exceeds this old messages are removed. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_age": {
"description": "Maximum age of any message in the stream, expressed in nanoseconds. 0 for unlimited.",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_msg_size": {
"description": "The largest message that will be accepted by the Stream. -1 for unlimited.",
"minimum": -1,
"default": -1,
"$comment": "signed 32 bit integer",
"type": "integer",
"maximum": 2147483647
},
"storage": {
"description": "The storage backend to use for the Stream.",
"type": "string",
"enum": [
"file",
"memory"
],
"default": "file"
},
"compression": {
"description": "Optional compression algorithm used for the Stream.",
"type": "string",
"enum": [
"none",
"s2"
],
"default": "none"
},
"num_replicas": {
"description": "How many replicas to keep for each message.",
"minimum": 1,
"default": 1,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"no_ack": {
"description": "Disables acknowledging messages that are received by the Stream.",
"type": "boolean",
"default": false
},
"template_owner": {
"description": "When the Stream is managed by a Stream Template this identifies the template that manages the Stream.",
"type": "string"
},
"discard": {
"description": "When a Stream reach it's limits either old messages are deleted or new ones are denied",
"type": "string",
"enum": [
"old",
"new"
],
"default": "old"
},
"duplicate_window": {
"description": "The time window to track duplicate messages for, expressed in nanoseconds. 0 for default",
"minimum": 0,
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"placement": {
"description": "Placement directives to consider when placing replicas of this stream, random placement when unset",
"type": "object",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"mirror": {
"description": "Maintains a 1:1 mirror of another stream with name matching this property. When a mirror is configured subjects and sources must be empty.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
},
"sources": {
"type": "array",
"description": "List of Stream names to replicate into this Stream",
"items": {
"type": "object",
"description": "Defines a source where streams should be replicated from",
"required": [
"name"
],
"properties": {
"name": {
"description": "Stream name",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"opt_start_seq": {
"description": "Sequence to start replicating from",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"opt_start_time": {
"description": "Time stamp to start replicating from",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"filter_subject": {
"description": "Replicate only a subset of messages based on filter",
"type": "string"
},
"subject_transform_dest": {
"description": "Map matching subjects according to this transform destination",
"type": "string"
},
"external": {
"required": [
"api"
],
"type": "object",
"description": "Configuration referencing a stream source in another account or JetStream domain",
"properties": {
"api": {
"type": "string",
"description": "The subject prefix that imports the other account/domain $JS.API.CONSUMER.> subjects"
},
"deliver": {
"type": "string",
"description": "The delivery subject to use for the push consumer"
}
}
}
}
}
},
"sealed": {
"type": "boolean",
"default": false,
"description": "Sealed streams do not allow messages to be deleted via limits or API, sealed streams can not be unsealed via configuration update. Can only be set on already created streams via the Update API"
},
"deny_delete": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to delete messages from a stream via the API. Cannot be changed once set to true"
},
"deny_purge": {
"type": "boolean",
"default": false,
"description": "Restricts the ability to purge messages from a stream via the API. Cannot be change once set to true"
},
"allow_rollup_hdrs": {
"type": "boolean",
"default": false,
"description": "Allows the use of the Nats-Rollup header to replace all contents of a stream, or subject in a stream, with a single new message"
},
"allow_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access to get individual messages"
},
"mirror_direct": {
"type": "boolean",
"default": false,
"description": "Allow higher performance, direct access for mirrors as well"
},
"republish": {
"type": "object",
"description": "Rules for republishing messages from a stream with subject mapping onto new subjects for partitioning and more",
"required": [
"src",
"dest"
],
"properties": {
"src": {
"type": "string",
"description": "The source subject to republish"
},
"dest": {
"type": "string",
"description": "The destination to publish to"
},
"headers_only": {
"type": "boolean",
"description": "Only send message headers, no bodies",
"default": false
}
}
},
"discard_new_per_subject": {
"type": "boolean",
"description": "When discard policy is new and the stream is one with max messages per subject set, this will apply the new behavior to every subject. Essentially turning discard new from maximum number of subjects into maximum number of messages in a subject.",
"default": false
},
"metadata": {
"description": "Additional metadata for the Stream",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"max_streams": {
"type": "integer",
"description": "The maximum number of streams to allow using this Template",
"minimum": -1
}
}
},
"streams": {
"description": "List of Streams managed by this Template",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_template_info_response"
}
}
}List stream template names
Templates are no longer recommended.
Paginated list of stream template names.
Subject
$JS.API.STREAM.TEMPLATE.NAMES
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_template_names_request.json",
"description": "A request to the JetStream $JS.API.CONSUMER.LIST API",
"title": "io.nats.jetstream.api.v1.stream_template_names_request",
"type": "object",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"offset"
],
"properties": {
"offset": {
"type": "integer",
"minimum": 0
}
}
}
]
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_template_names_response.json",
"description": "A response from the JetStream $JS.API.STREAM.TEMPLATE.NAMES API",
"title": "io.nats.jetstream.api.v1.stream_template_names_response",
"type": "object",
"required": [
"type"
],
"allOf": [
{
"type": "object",
"required": [
"total",
"offset",
"limit"
],
"properties": {
"total": {
"type": "integer",
"minimum": 0
},
"offset": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"minimum": 0
}
}
}
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"streams"
],
"properties": {
"consumers": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_template_names_response"
}
}
}Remove peer from clustered stream
Remove a server from a clustered stream and its consumers.
Subject
$JS.API.STREAM.PEER.REMOVE.{stream}
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_remove_peer_request.json",
"description": "A request to the JetStream $JS.API.STREAM.PEER.REMOVE API",
"title": "io.nats.jetstream.api.v1.stream_remove_peer_request",
"type": "object",
"required": [
"peer"
],
"additionalProperties": false,
"properties": {
"peer": {
"type": "string",
"description": "Server name of the peer to remove",
"minLength": 1
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_remove_peer_response.json",
"description": "A response from the JetStream $JS.API.STREAM.PEER.REMOVE API",
"title": "io.nats.jetstream.api.v1.stream_remove_peer_response",
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"success"
],
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "If the peer was successfully removed",
"default": false
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_remove_peer_response"
}
}
}Stepdown leader for a clustered stream
Force the current stream Raft leader to stepdown for another peer to take over.
Subject
$JS.API.STREAM.LEADER.STEPDOWN.{stream}
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/stream_leader_stepdown_response.json",
"description": "A response from the JetStream $JS.API.STREAM.LEADER.STEPDOWN API",
"title": "io.nats.jetstream.api.v1.stream_leader_stepdown_response",
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"success"
],
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "If the leader successfully stood down",
"default": false
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.stream_leader_stepdown_response"
}
}
}Move stream
Moves a stream off the current set of servers.
Subject
$JS.API.ACCOUNT.STREAM.MOVE.{stream}.{??}
Cancel move stream
Cancels moving of a stream.
Subject
$JS.API.ACCOUNT.STREAM.CANCEL_MOVE.{stream}.{??}
Publish Ack
The acknowledgement returned to the client publisher when a stream successfully stores a message.
Subject
_INBOX.*.*.*
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/pub_ack_response.json",
"description": "A response received when publishing a message",
"title": "io.nats.jetstream.api.v1.pub_ack_response",
"type": "object",
"required": [
"stream"
],
"additionalProperties": false,
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
},
"stream": {
"type": "string",
"description": "The name of the stream that received the message",
"minLength": 1
},
"seq": {
"type": "integer",
"description": "If successful this will be the sequence the message is stored at",
"$comment": "unsigned 64 bit integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"duplicate": {
"type": "boolean",
"description": "Indicates that the message was not stored due to the Nats-Msg-Id header and duplicate tracking",
"default": false
},
"domain": {
"type": "string",
"description": "If the Stream accepting the message is in a JetStream server configured for a domain this would be that domain"
}
}
}Consumer API
| Name | Subject | System Account |
|---|---|---|
| List consumers | $JS.API.CONSUMER.LIST.{stream} | false |
| List consumer names | $JS.API.CONSUMER.NAMES.{stream} | false |
| Create ephemeral consumer | $JS.API.CONSUMER.CREATE.{stream} | false |
| Create consumer | $JS.API.CONSUMER.DURABLE.CREATE.{stream}.{consumer} | false |
| Create consumer (v2) | $JS.API.CONSUMER.CREATE.{stream}.{consumer}.{filter} | false |
| Delete consumer | $JS.API.CONSUMER.DELETE.{stream}.{consumer} | false |
| Get consumer info | $JS.API.CONSUMER.INFO.{stream}.{consumer} | false |
| Pull next messages | $JS.API.CONSUMER.MSG.NEXT.{stream}.{consumer} | false |
| Stepdown leader for a clustered consumer | $JS.API.CONSUMER.LEADER.STEPDOWN.{stream}.{consumer} | false |
| Push consumer flow control | $JS.FC.> | false |
| Message ack | $JS.ACK.{} | false |
List consumers
Paginated list of consumers including their current configuration and state.
Subject
$JS.API.CONSUMER.LIST.{stream}
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_list_request.json",
"description": "A request to the JetStream $JS.API.CONSUMER.LIST API",
"title": "io.nats.jetstream.api.v1.consumer_list_request",
"type": "object",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"offset"
],
"properties": {
"offset": {
"type": "integer",
"minimum": 0
}
}
}
]
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_list_response.json",
"description": "A response from the JetStream $JS.API.CONSUMER.LIST API",
"title": "io.nats.jetstream.api.v1.consumer_list_response",
"type": "object",
"required": [
"type"
],
"allOf": [
{
"type": "object",
"required": [
"total",
"offset",
"limit"
],
"properties": {
"total": {
"type": "integer",
"minimum": 0
},
"offset": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"minimum": 0
}
}
}
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"consumers"
],
"properties": {
"consumers": {
"description": "Full Consumer information for each known Consumer",
"type": "array",
"items": {
"required": [
"stream_name",
"name",
"config",
"created",
"delivered",
"ack_floor",
"num_ack_pending",
"num_redelivered",
"num_waiting",
"num_pending"
],
"type": "object",
"properties": {
"stream_name": {
"type": "string",
"description": "The Stream the consumer belongs to"
},
"name": {
"type": "string",
"description": "A unique name for the consumer, either machine generated or the durable name"
},
"ts": {
"description": "The server time the consumer info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"config": {
"required": [
"deliver_policy",
"ack_policy",
"replay_policy"
],
"allOf": [
{
"oneOf": [
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"all"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"new"
]
}
}
},
{
"required": [
"deliver_policy",
"opt_start_seq"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_sequence"
]
},
"opt_start_seq": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
}
},
{
"required": [
"deliver_policy",
"opt_start_time"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_time"
]
},
"opt_start_time": {
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last_per_subject"
]
}
}
}
]
}
],
"properties": {
"durable_name": {
"description": "A unique name for a durable consumer",
"deprecationMessage": "Durable is deprecated. All consumers will have names. picked by clients.",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"name": {
"description": "A unique name for a consumer",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"description": {
"description": "A short description of the purpose of this consumer",
"type": "string",
"maxLength": 4096
},
"deliver_subject": {
"type": "string",
"minLength": 1
},
"ack_policy": {
"type": "string",
"enum": [
"none",
"all",
"explicit"
],
"default": "none"
},
"ack_wait": {
"description": "How long (in nanoseconds) to allow messages to remain un-acknowledged before attempting redelivery",
"minimum": 1,
"default": "30000000000",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_deliver": {
"description": "The number of times a message will be redelivered to consumers if not acknowledged in time",
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"filter_subject": {
"description": "Filter the stream by a single subjects",
"type": "string"
},
"filter_subjects": {
"description": "Filter the stream by multiple subjects",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"replay_policy": {
"type": "string",
"enum": [
"instant",
"original"
],
"default": "instant"
},
"sample_freq": {
"type": "string"
},
"rate_limit_bps": {
"description": "The rate at which messages will be delivered to clients, expressed in bit per second",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"max_ack_pending": {
"description": "The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended",
"default": 1000,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"idle_heartbeat": {
"minimum": 0,
"description": "If the Consumer is idle for more than this many nano seconds a empty message with Status header 100 will be sent indicating the consumer is still alive",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"flow_control": {
"type": "boolean",
"description": "For push consumers this will regularly send an empty mess with Status header 100 and a reply subject, consumers must reply to these messages to control the rate of message delivery"
},
"max_waiting": {
"description": "The number of pulls that can be outstanding on a pull consumer, pulls received after this is reached are ignored",
"minimum": 0,
"default": 512,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"direct": {
"type": "boolean",
"description": "Creates a special consumer that does not touch the Raft layers, not for general use by clients, internal use only",
"default": false
},
"headers_only": {
"type": "boolean",
"default": false,
"description": "Delivers only the headers of messages in the stream and not the bodies. Additionally adds Nats-Msg-Size header to indicate the size of the removed payload"
},
"max_batch": {
"type": "integer",
"description": "The largest batch property that may be specified when doing a pull on a Pull Consumer",
"default": 0
},
"max_expires": {
"description": "The maximum expires value that may be set when doing a pull on a Pull Consumer",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"max_bytes": {
"description": "The maximum bytes value that maybe set when dong a pull on a Pull Consumer",
"minimum": 0,
"default": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"inactive_threshold": {
"description": "Duration that instructs the server to cleanup ephemeral consumers that are inactive for that long",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"backoff": {
"description": "List of durations in Go format that represents a retry time scale for NaK'd messages",
"type": "array",
"items": {
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
},
"num_replicas": {
"description": "When set do not inherit the replica count from the stream but specifically set it to this amount",
"type": "integer",
"minimum": 0,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit"
},
"mem_storage": {
"description": "Force the consumer state to be kept in memory rather than inherit the setting from the stream",
"type": "boolean",
"default": false
},
"metadata": {
"description": "Additional metadata for the Consumer",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"created": {
"description": "The time the Consumer was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"delivered": {
"description": "The last message delivered from this Consumer",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"ack_floor": {
"description": "The highest contiguous acknowledged message",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"num_ack_pending": {
"description": "The number of messages pending acknowledgement",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_redelivered": {
"description": "The number of redeliveries that have been performed",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_waiting": {
"description": "The number of pull consumers waiting for messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_pending": {
"description": "The number of messages left unconsumed in this Consumer",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"push_bound": {
"description": "Indicates if any client is connected and receiving messages from a push consumer",
"type": "boolean"
}
}
},
"missing": {
"description": "In clustered environments gathering Consumer info might time out, this list would be a list of Consumers for which information was not obtainable",
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.consumer_list_response"
}
}
}List consumer names
Paginated list of consumer consumers.
Subject
$JS.API.CONSUMER.NAMES.{stream}
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_names_request.json",
"description": "A request to the JetStream $JS.API.CONSUMER.NAMES API",
"title": "io.nats.jetstream.api.v1.consumer_names_request",
"type": "object",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"offset"
],
"properties": {
"offset": {
"type": "integer",
"minimum": 0
}
}
}
],
"properties": {
"subject": {
"type": "string",
"description": "Filter the names to those consuming messages matching this subject or wildcard"
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_names_response.json",
"description": "A response from the JetStream $JS.API.CONSUMER.NAMES API",
"title": "io.nats.jetstream.api.v1.consumer_names_response",
"type": "object",
"required": [
"type"
],
"allOf": [
{
"type": "object",
"required": [
"total",
"offset",
"limit"
],
"properties": {
"total": {
"type": "integer",
"minimum": 0
},
"offset": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"minimum": 0
}
}
}
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"consumers"
],
"properties": {
"consumers": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.consumer_names_response"
}
}
}Create ephemeral consumer
This service is deprecated in favor of the DURABLE form since the only distinction between an ephemeral and durable consumer is the default activity threshold.
Create an ephemeral consumer.
Subject
$JS.API.CONSUMER.CREATE.{stream}
Params:
stream- stream
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_create_request.json",
"description": "A request to the JetStream $JS.API.CONSUMER.CREATE and $JS.API.CONSUMER.DURABLE.CREATE APIs",
"title": "io.nats.jetstream.api.v1.consumer_create_request",
"type": "object",
"required": [
"stream_name",
"config"
],
"properties": {
"stream_name": {
"type": "string",
"description": "The name of the stream to create the consumer in"
},
"config": {
"type": "object",
"description": "The consumer configuration",
"required": [
"deliver_policy",
"ack_policy",
"replay_policy"
],
"allOf": [
{
"oneOf": [
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"all"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"new"
]
}
}
},
{
"required": [
"deliver_policy",
"opt_start_seq"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_sequence"
]
},
"opt_start_seq": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
}
},
{
"required": [
"deliver_policy",
"opt_start_time"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_time"
]
},
"opt_start_time": {
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last_per_subject"
]
}
}
}
]
}
],
"properties": {
"durable_name": {
"description": "A unique name for a durable consumer",
"deprecationMessage": "Durable is deprecated. All consumers will have names. picked by clients.",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"name": {
"description": "A unique name for a consumer",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"description": {
"description": "A short description of the purpose of this consumer",
"type": "string",
"maxLength": 4096
},
"deliver_subject": {
"type": "string",
"minLength": 1
},
"ack_policy": {
"type": "string",
"enum": [
"none",
"all",
"explicit"
],
"default": "none"
},
"ack_wait": {
"description": "How long (in nanoseconds) to allow messages to remain un-acknowledged before attempting redelivery",
"minimum": 1,
"default": "30000000000",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_deliver": {
"description": "The number of times a message will be redelivered to consumers if not acknowledged in time",
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"filter_subject": {
"description": "Filter the stream by a single subjects",
"type": "string"
},
"filter_subjects": {
"description": "Filter the stream by multiple subjects",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"replay_policy": {
"type": "string",
"enum": [
"instant",
"original"
],
"default": "instant"
},
"sample_freq": {
"type": "string"
},
"rate_limit_bps": {
"description": "The rate at which messages will be delivered to clients, expressed in bit per second",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"max_ack_pending": {
"description": "The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended",
"default": 1000,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"idle_heartbeat": {
"minimum": 0,
"description": "If the Consumer is idle for more than this many nano seconds a empty message with Status header 100 will be sent indicating the consumer is still alive",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"flow_control": {
"type": "boolean",
"description": "For push consumers this will regularly send an empty mess with Status header 100 and a reply subject, consumers must reply to these messages to control the rate of message delivery"
},
"max_waiting": {
"description": "The number of pulls that can be outstanding on a pull consumer, pulls received after this is reached are ignored",
"minimum": 0,
"default": 512,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"direct": {
"type": "boolean",
"description": "Creates a special consumer that does not touch the Raft layers, not for general use by clients, internal use only",
"default": false
},
"headers_only": {
"type": "boolean",
"default": false,
"description": "Delivers only the headers of messages in the stream and not the bodies. Additionally adds Nats-Msg-Size header to indicate the size of the removed payload"
},
"max_batch": {
"type": "integer",
"description": "The largest batch property that may be specified when doing a pull on a Pull Consumer",
"default": 0
},
"max_expires": {
"description": "The maximum expires value that may be set when doing a pull on a Pull Consumer",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"max_bytes": {
"description": "The maximum bytes value that maybe set when dong a pull on a Pull Consumer",
"minimum": 0,
"default": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"inactive_threshold": {
"description": "Duration that instructs the server to cleanup ephemeral consumers that are inactive for that long",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"backoff": {
"description": "List of durations in Go format that represents a retry time scale for NaK'd messages",
"type": "array",
"items": {
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
},
"num_replicas": {
"description": "When set do not inherit the replica count from the stream but specifically set it to this amount",
"type": "integer",
"minimum": 0,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit"
},
"mem_storage": {
"description": "Force the consumer state to be kept in memory rather than inherit the setting from the stream",
"type": "boolean",
"default": false
},
"metadata": {
"description": "Additional metadata for the Consumer",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_create_response.json",
"description": "A response from the JetStream $JS.API.CONSUMER.CREATE API",
"title": "io.nats.jetstream.api.v1.consumer_create_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"required": [
"stream_name",
"name",
"config",
"created",
"delivered",
"ack_floor",
"num_ack_pending",
"num_redelivered",
"num_waiting",
"num_pending"
],
"type": "object",
"properties": {
"stream_name": {
"type": "string",
"description": "The Stream the consumer belongs to"
},
"name": {
"type": "string",
"description": "A unique name for the consumer, either machine generated or the durable name"
},
"ts": {
"description": "The server time the consumer info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"config": {
"required": [
"deliver_policy",
"ack_policy",
"replay_policy"
],
"allOf": [
{
"oneOf": [
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"all"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"new"
]
}
}
},
{
"required": [
"deliver_policy",
"opt_start_seq"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_sequence"
]
},
"opt_start_seq": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
}
},
{
"required": [
"deliver_policy",
"opt_start_time"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_time"
]
},
"opt_start_time": {
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last_per_subject"
]
}
}
}
]
}
],
"properties": {
"durable_name": {
"description": "A unique name for a durable consumer",
"deprecationMessage": "Durable is deprecated. All consumers will have names. picked by clients.",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"name": {
"description": "A unique name for a consumer",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"description": {
"description": "A short description of the purpose of this consumer",
"type": "string",
"maxLength": 4096
},
"deliver_subject": {
"type": "string",
"minLength": 1
},
"ack_policy": {
"type": "string",
"enum": [
"none",
"all",
"explicit"
],
"default": "none"
},
"ack_wait": {
"description": "How long (in nanoseconds) to allow messages to remain un-acknowledged before attempting redelivery",
"minimum": 1,
"default": "30000000000",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_deliver": {
"description": "The number of times a message will be redelivered to consumers if not acknowledged in time",
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"filter_subject": {
"description": "Filter the stream by a single subjects",
"type": "string"
},
"filter_subjects": {
"description": "Filter the stream by multiple subjects",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"replay_policy": {
"type": "string",
"enum": [
"instant",
"original"
],
"default": "instant"
},
"sample_freq": {
"type": "string"
},
"rate_limit_bps": {
"description": "The rate at which messages will be delivered to clients, expressed in bit per second",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"max_ack_pending": {
"description": "The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended",
"default": 1000,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"idle_heartbeat": {
"minimum": 0,
"description": "If the Consumer is idle for more than this many nano seconds a empty message with Status header 100 will be sent indicating the consumer is still alive",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"flow_control": {
"type": "boolean",
"description": "For push consumers this will regularly send an empty mess with Status header 100 and a reply subject, consumers must reply to these messages to control the rate of message delivery"
},
"max_waiting": {
"description": "The number of pulls that can be outstanding on a pull consumer, pulls received after this is reached are ignored",
"minimum": 0,
"default": 512,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"direct": {
"type": "boolean",
"description": "Creates a special consumer that does not touch the Raft layers, not for general use by clients, internal use only",
"default": false
},
"headers_only": {
"type": "boolean",
"default": false,
"description": "Delivers only the headers of messages in the stream and not the bodies. Additionally adds Nats-Msg-Size header to indicate the size of the removed payload"
},
"max_batch": {
"type": "integer",
"description": "The largest batch property that may be specified when doing a pull on a Pull Consumer",
"default": 0
},
"max_expires": {
"description": "The maximum expires value that may be set when doing a pull on a Pull Consumer",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"max_bytes": {
"description": "The maximum bytes value that maybe set when dong a pull on a Pull Consumer",
"minimum": 0,
"default": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"inactive_threshold": {
"description": "Duration that instructs the server to cleanup ephemeral consumers that are inactive for that long",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"backoff": {
"description": "List of durations in Go format that represents a retry time scale for NaK'd messages",
"type": "array",
"items": {
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
},
"num_replicas": {
"description": "When set do not inherit the replica count from the stream but specifically set it to this amount",
"type": "integer",
"minimum": 0,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit"
},
"mem_storage": {
"description": "Force the consumer state to be kept in memory rather than inherit the setting from the stream",
"type": "boolean",
"default": false
},
"metadata": {
"description": "Additional metadata for the Consumer",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"created": {
"description": "The time the Consumer was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"delivered": {
"description": "The last message delivered from this Consumer",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"ack_floor": {
"description": "The highest contiguous acknowledged message",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"num_ack_pending": {
"description": "The number of messages pending acknowledgement",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_redelivered": {
"description": "The number of redeliveries that have been performed",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_waiting": {
"description": "The number of pull consumers waiting for messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_pending": {
"description": "The number of messages left unconsumed in this Consumer",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"push_bound": {
"description": "Indicates if any client is connected and receiving messages from a push consumer",
"type": "boolean"
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.consumer_create_response"
}
}
}Create consumer
Create a durable consumer.
Subject
$JS.API.CONSUMER.DURABLE.CREATE.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_create_request.json",
"description": "A request to the JetStream $JS.API.CONSUMER.CREATE and $JS.API.CONSUMER.DURABLE.CREATE APIs",
"title": "io.nats.jetstream.api.v1.consumer_create_request",
"type": "object",
"required": [
"stream_name",
"config"
],
"properties": {
"stream_name": {
"type": "string",
"description": "The name of the stream to create the consumer in"
},
"config": {
"type": "object",
"description": "The consumer configuration",
"required": [
"deliver_policy",
"ack_policy",
"replay_policy"
],
"allOf": [
{
"oneOf": [
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"all"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"new"
]
}
}
},
{
"required": [
"deliver_policy",
"opt_start_seq"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_sequence"
]
},
"opt_start_seq": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
}
},
{
"required": [
"deliver_policy",
"opt_start_time"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_time"
]
},
"opt_start_time": {
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last_per_subject"
]
}
}
}
]
}
],
"properties": {
"durable_name": {
"description": "A unique name for a durable consumer",
"deprecationMessage": "Durable is deprecated. All consumers will have names. picked by clients.",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"name": {
"description": "A unique name for a consumer",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"description": {
"description": "A short description of the purpose of this consumer",
"type": "string",
"maxLength": 4096
},
"deliver_subject": {
"type": "string",
"minLength": 1
},
"ack_policy": {
"type": "string",
"enum": [
"none",
"all",
"explicit"
],
"default": "none"
},
"ack_wait": {
"description": "How long (in nanoseconds) to allow messages to remain un-acknowledged before attempting redelivery",
"minimum": 1,
"default": "30000000000",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_deliver": {
"description": "The number of times a message will be redelivered to consumers if not acknowledged in time",
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"filter_subject": {
"description": "Filter the stream by a single subjects",
"type": "string"
},
"filter_subjects": {
"description": "Filter the stream by multiple subjects",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"replay_policy": {
"type": "string",
"enum": [
"instant",
"original"
],
"default": "instant"
},
"sample_freq": {
"type": "string"
},
"rate_limit_bps": {
"description": "The rate at which messages will be delivered to clients, expressed in bit per second",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"max_ack_pending": {
"description": "The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended",
"default": 1000,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"idle_heartbeat": {
"minimum": 0,
"description": "If the Consumer is idle for more than this many nano seconds a empty message with Status header 100 will be sent indicating the consumer is still alive",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"flow_control": {
"type": "boolean",
"description": "For push consumers this will regularly send an empty mess with Status header 100 and a reply subject, consumers must reply to these messages to control the rate of message delivery"
},
"max_waiting": {
"description": "The number of pulls that can be outstanding on a pull consumer, pulls received after this is reached are ignored",
"minimum": 0,
"default": 512,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"direct": {
"type": "boolean",
"description": "Creates a special consumer that does not touch the Raft layers, not for general use by clients, internal use only",
"default": false
},
"headers_only": {
"type": "boolean",
"default": false,
"description": "Delivers only the headers of messages in the stream and not the bodies. Additionally adds Nats-Msg-Size header to indicate the size of the removed payload"
},
"max_batch": {
"type": "integer",
"description": "The largest batch property that may be specified when doing a pull on a Pull Consumer",
"default": 0
},
"max_expires": {
"description": "The maximum expires value that may be set when doing a pull on a Pull Consumer",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"max_bytes": {
"description": "The maximum bytes value that maybe set when dong a pull on a Pull Consumer",
"minimum": 0,
"default": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"inactive_threshold": {
"description": "Duration that instructs the server to cleanup ephemeral consumers that are inactive for that long",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"backoff": {
"description": "List of durations in Go format that represents a retry time scale for NaK'd messages",
"type": "array",
"items": {
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
},
"num_replicas": {
"description": "When set do not inherit the replica count from the stream but specifically set it to this amount",
"type": "integer",
"minimum": 0,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit"
},
"mem_storage": {
"description": "Force the consumer state to be kept in memory rather than inherit the setting from the stream",
"type": "boolean",
"default": false
},
"metadata": {
"description": "Additional metadata for the Consumer",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_create_response.json",
"description": "A response from the JetStream $JS.API.CONSUMER.CREATE API",
"title": "io.nats.jetstream.api.v1.consumer_create_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"required": [
"stream_name",
"name",
"config",
"created",
"delivered",
"ack_floor",
"num_ack_pending",
"num_redelivered",
"num_waiting",
"num_pending"
],
"type": "object",
"properties": {
"stream_name": {
"type": "string",
"description": "The Stream the consumer belongs to"
},
"name": {
"type": "string",
"description": "A unique name for the consumer, either machine generated or the durable name"
},
"ts": {
"description": "The server time the consumer info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"config": {
"required": [
"deliver_policy",
"ack_policy",
"replay_policy"
],
"allOf": [
{
"oneOf": [
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"all"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"new"
]
}
}
},
{
"required": [
"deliver_policy",
"opt_start_seq"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_sequence"
]
},
"opt_start_seq": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
}
},
{
"required": [
"deliver_policy",
"opt_start_time"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_time"
]
},
"opt_start_time": {
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last_per_subject"
]
}
}
}
]
}
],
"properties": {
"durable_name": {
"description": "A unique name for a durable consumer",
"deprecationMessage": "Durable is deprecated. All consumers will have names. picked by clients.",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"name": {
"description": "A unique name for a consumer",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"description": {
"description": "A short description of the purpose of this consumer",
"type": "string",
"maxLength": 4096
},
"deliver_subject": {
"type": "string",
"minLength": 1
},
"ack_policy": {
"type": "string",
"enum": [
"none",
"all",
"explicit"
],
"default": "none"
},
"ack_wait": {
"description": "How long (in nanoseconds) to allow messages to remain un-acknowledged before attempting redelivery",
"minimum": 1,
"default": "30000000000",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_deliver": {
"description": "The number of times a message will be redelivered to consumers if not acknowledged in time",
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"filter_subject": {
"description": "Filter the stream by a single subjects",
"type": "string"
},
"filter_subjects": {
"description": "Filter the stream by multiple subjects",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"replay_policy": {
"type": "string",
"enum": [
"instant",
"original"
],
"default": "instant"
},
"sample_freq": {
"type": "string"
},
"rate_limit_bps": {
"description": "The rate at which messages will be delivered to clients, expressed in bit per second",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"max_ack_pending": {
"description": "The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended",
"default": 1000,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"idle_heartbeat": {
"minimum": 0,
"description": "If the Consumer is idle for more than this many nano seconds a empty message with Status header 100 will be sent indicating the consumer is still alive",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"flow_control": {
"type": "boolean",
"description": "For push consumers this will regularly send an empty mess with Status header 100 and a reply subject, consumers must reply to these messages to control the rate of message delivery"
},
"max_waiting": {
"description": "The number of pulls that can be outstanding on a pull consumer, pulls received after this is reached are ignored",
"minimum": 0,
"default": 512,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"direct": {
"type": "boolean",
"description": "Creates a special consumer that does not touch the Raft layers, not for general use by clients, internal use only",
"default": false
},
"headers_only": {
"type": "boolean",
"default": false,
"description": "Delivers only the headers of messages in the stream and not the bodies. Additionally adds Nats-Msg-Size header to indicate the size of the removed payload"
},
"max_batch": {
"type": "integer",
"description": "The largest batch property that may be specified when doing a pull on a Pull Consumer",
"default": 0
},
"max_expires": {
"description": "The maximum expires value that may be set when doing a pull on a Pull Consumer",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"max_bytes": {
"description": "The maximum bytes value that maybe set when dong a pull on a Pull Consumer",
"minimum": 0,
"default": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"inactive_threshold": {
"description": "Duration that instructs the server to cleanup ephemeral consumers that are inactive for that long",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"backoff": {
"description": "List of durations in Go format that represents a retry time scale for NaK'd messages",
"type": "array",
"items": {
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
},
"num_replicas": {
"description": "When set do not inherit the replica count from the stream but specifically set it to this amount",
"type": "integer",
"minimum": 0,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit"
},
"mem_storage": {
"description": "Force the consumer state to be kept in memory rather than inherit the setting from the stream",
"type": "boolean",
"default": false
},
"metadata": {
"description": "Additional metadata for the Consumer",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"created": {
"description": "The time the Consumer was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"delivered": {
"description": "The last message delivered from this Consumer",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"ack_floor": {
"description": "The highest contiguous acknowledged message",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"num_ack_pending": {
"description": "The number of messages pending acknowledgement",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_redelivered": {
"description": "The number of redeliveries that have been performed",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_waiting": {
"description": "The number of pull consumers waiting for messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_pending": {
"description": "The number of messages left unconsumed in this Consumer",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"push_bound": {
"description": "Indicates if any client is connected and receiving messages from a push consumer",
"type": "boolean"
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.consumer_create_response"
}
}
}Create consumer (v2)
Create a durable consumer.
Subject
$JS.API.CONSUMER.CREATE.{stream}.{consumer}.{filter}
Params:
stream- streamconsumer- consumerfilter- filter
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_create_request.json",
"description": "A request to the JetStream $JS.API.CONSUMER.CREATE and $JS.API.CONSUMER.DURABLE.CREATE APIs",
"title": "io.nats.jetstream.api.v1.consumer_create_request",
"type": "object",
"required": [
"stream_name",
"config"
],
"properties": {
"stream_name": {
"type": "string",
"description": "The name of the stream to create the consumer in"
},
"config": {
"type": "object",
"description": "The consumer configuration",
"required": [
"deliver_policy",
"ack_policy",
"replay_policy"
],
"allOf": [
{
"oneOf": [
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"all"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"new"
]
}
}
},
{
"required": [
"deliver_policy",
"opt_start_seq"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_sequence"
]
},
"opt_start_seq": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
}
},
{
"required": [
"deliver_policy",
"opt_start_time"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_time"
]
},
"opt_start_time": {
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last_per_subject"
]
}
}
}
]
}
],
"properties": {
"durable_name": {
"description": "A unique name for a durable consumer",
"deprecationMessage": "Durable is deprecated. All consumers will have names. picked by clients.",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"name": {
"description": "A unique name for a consumer",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"description": {
"description": "A short description of the purpose of this consumer",
"type": "string",
"maxLength": 4096
},
"deliver_subject": {
"type": "string",
"minLength": 1
},
"ack_policy": {
"type": "string",
"enum": [
"none",
"all",
"explicit"
],
"default": "none"
},
"ack_wait": {
"description": "How long (in nanoseconds) to allow messages to remain un-acknowledged before attempting redelivery",
"minimum": 1,
"default": "30000000000",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_deliver": {
"description": "The number of times a message will be redelivered to consumers if not acknowledged in time",
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"filter_subject": {
"description": "Filter the stream by a single subjects",
"type": "string"
},
"filter_subjects": {
"description": "Filter the stream by multiple subjects",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"replay_policy": {
"type": "string",
"enum": [
"instant",
"original"
],
"default": "instant"
},
"sample_freq": {
"type": "string"
},
"rate_limit_bps": {
"description": "The rate at which messages will be delivered to clients, expressed in bit per second",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"max_ack_pending": {
"description": "The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended",
"default": 1000,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"idle_heartbeat": {
"minimum": 0,
"description": "If the Consumer is idle for more than this many nano seconds a empty message with Status header 100 will be sent indicating the consumer is still alive",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"flow_control": {
"type": "boolean",
"description": "For push consumers this will regularly send an empty mess with Status header 100 and a reply subject, consumers must reply to these messages to control the rate of message delivery"
},
"max_waiting": {
"description": "The number of pulls that can be outstanding on a pull consumer, pulls received after this is reached are ignored",
"minimum": 0,
"default": 512,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"direct": {
"type": "boolean",
"description": "Creates a special consumer that does not touch the Raft layers, not for general use by clients, internal use only",
"default": false
},
"headers_only": {
"type": "boolean",
"default": false,
"description": "Delivers only the headers of messages in the stream and not the bodies. Additionally adds Nats-Msg-Size header to indicate the size of the removed payload"
},
"max_batch": {
"type": "integer",
"description": "The largest batch property that may be specified when doing a pull on a Pull Consumer",
"default": 0
},
"max_expires": {
"description": "The maximum expires value that may be set when doing a pull on a Pull Consumer",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"max_bytes": {
"description": "The maximum bytes value that maybe set when dong a pull on a Pull Consumer",
"minimum": 0,
"default": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"inactive_threshold": {
"description": "Duration that instructs the server to cleanup ephemeral consumers that are inactive for that long",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"backoff": {
"description": "List of durations in Go format that represents a retry time scale for NaK'd messages",
"type": "array",
"items": {
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
},
"num_replicas": {
"description": "When set do not inherit the replica count from the stream but specifically set it to this amount",
"type": "integer",
"minimum": 0,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit"
},
"mem_storage": {
"description": "Force the consumer state to be kept in memory rather than inherit the setting from the stream",
"type": "boolean",
"default": false
},
"metadata": {
"description": "Additional metadata for the Consumer",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_create_response.json",
"description": "A response from the JetStream $JS.API.CONSUMER.CREATE API",
"title": "io.nats.jetstream.api.v1.consumer_create_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"required": [
"stream_name",
"name",
"config",
"created",
"delivered",
"ack_floor",
"num_ack_pending",
"num_redelivered",
"num_waiting",
"num_pending"
],
"type": "object",
"properties": {
"stream_name": {
"type": "string",
"description": "The Stream the consumer belongs to"
},
"name": {
"type": "string",
"description": "A unique name for the consumer, either machine generated or the durable name"
},
"ts": {
"description": "The server time the consumer info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"config": {
"required": [
"deliver_policy",
"ack_policy",
"replay_policy"
],
"allOf": [
{
"oneOf": [
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"all"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"new"
]
}
}
},
{
"required": [
"deliver_policy",
"opt_start_seq"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_sequence"
]
},
"opt_start_seq": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
}
},
{
"required": [
"deliver_policy",
"opt_start_time"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_time"
]
},
"opt_start_time": {
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last_per_subject"
]
}
}
}
]
}
],
"properties": {
"durable_name": {
"description": "A unique name for a durable consumer",
"deprecationMessage": "Durable is deprecated. All consumers will have names. picked by clients.",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"name": {
"description": "A unique name for a consumer",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"description": {
"description": "A short description of the purpose of this consumer",
"type": "string",
"maxLength": 4096
},
"deliver_subject": {
"type": "string",
"minLength": 1
},
"ack_policy": {
"type": "string",
"enum": [
"none",
"all",
"explicit"
],
"default": "none"
},
"ack_wait": {
"description": "How long (in nanoseconds) to allow messages to remain un-acknowledged before attempting redelivery",
"minimum": 1,
"default": "30000000000",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_deliver": {
"description": "The number of times a message will be redelivered to consumers if not acknowledged in time",
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"filter_subject": {
"description": "Filter the stream by a single subjects",
"type": "string"
},
"filter_subjects": {
"description": "Filter the stream by multiple subjects",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"replay_policy": {
"type": "string",
"enum": [
"instant",
"original"
],
"default": "instant"
},
"sample_freq": {
"type": "string"
},
"rate_limit_bps": {
"description": "The rate at which messages will be delivered to clients, expressed in bit per second",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"max_ack_pending": {
"description": "The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended",
"default": 1000,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"idle_heartbeat": {
"minimum": 0,
"description": "If the Consumer is idle for more than this many nano seconds a empty message with Status header 100 will be sent indicating the consumer is still alive",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"flow_control": {
"type": "boolean",
"description": "For push consumers this will regularly send an empty mess with Status header 100 and a reply subject, consumers must reply to these messages to control the rate of message delivery"
},
"max_waiting": {
"description": "The number of pulls that can be outstanding on a pull consumer, pulls received after this is reached are ignored",
"minimum": 0,
"default": 512,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"direct": {
"type": "boolean",
"description": "Creates a special consumer that does not touch the Raft layers, not for general use by clients, internal use only",
"default": false
},
"headers_only": {
"type": "boolean",
"default": false,
"description": "Delivers only the headers of messages in the stream and not the bodies. Additionally adds Nats-Msg-Size header to indicate the size of the removed payload"
},
"max_batch": {
"type": "integer",
"description": "The largest batch property that may be specified when doing a pull on a Pull Consumer",
"default": 0
},
"max_expires": {
"description": "The maximum expires value that may be set when doing a pull on a Pull Consumer",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"max_bytes": {
"description": "The maximum bytes value that maybe set when dong a pull on a Pull Consumer",
"minimum": 0,
"default": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"inactive_threshold": {
"description": "Duration that instructs the server to cleanup ephemeral consumers that are inactive for that long",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"backoff": {
"description": "List of durations in Go format that represents a retry time scale for NaK'd messages",
"type": "array",
"items": {
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
},
"num_replicas": {
"description": "When set do not inherit the replica count from the stream but specifically set it to this amount",
"type": "integer",
"minimum": 0,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit"
},
"mem_storage": {
"description": "Force the consumer state to be kept in memory rather than inherit the setting from the stream",
"type": "boolean",
"default": false
},
"metadata": {
"description": "Additional metadata for the Consumer",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"created": {
"description": "The time the Consumer was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"delivered": {
"description": "The last message delivered from this Consumer",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"ack_floor": {
"description": "The highest contiguous acknowledged message",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"num_ack_pending": {
"description": "The number of messages pending acknowledgement",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_redelivered": {
"description": "The number of redeliveries that have been performed",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_waiting": {
"description": "The number of pull consumers waiting for messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_pending": {
"description": "The number of messages left unconsumed in this Consumer",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"push_bound": {
"description": "Indicates if any client is connected and receiving messages from a push consumer",
"type": "boolean"
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.consumer_create_response"
}
}
}Delete consumer
Delete a consumer.
Subject
$JS.API.CONSUMER.DELETE.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_delete_response.json",
"description": "A response from the JetStream $JS.API.CONSUMER.DELETE API",
"title": "io.nats.jetstream.api.v1.consumer_delete_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"type": "object",
"required": [
"success"
],
"properties": {
"success": {
"type": "boolean"
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.consumer_delete_response"
}
}
}Get consumer info
Get the current configuration and state of a consumer.
Subject
$JS.API.CONSUMER.INFO.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_info_response.json",
"description": "A response from the JetStream $JS.API.CONSUMER.INFO API",
"title": "io.nats.jetstream.api.v1.consumer_info_response",
"type": "object",
"required": [
"type"
],
"oneOf": [
{
"required": [
"stream_name",
"name",
"config",
"created",
"delivered",
"ack_floor",
"num_ack_pending",
"num_redelivered",
"num_waiting",
"num_pending"
],
"type": "object",
"properties": {
"stream_name": {
"type": "string",
"description": "The Stream the consumer belongs to"
},
"name": {
"type": "string",
"description": "A unique name for the consumer, either machine generated or the durable name"
},
"ts": {
"description": "The server time the consumer info was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"config": {
"required": [
"deliver_policy",
"ack_policy",
"replay_policy"
],
"allOf": [
{
"oneOf": [
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"all"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last"
]
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"new"
]
}
}
},
{
"required": [
"deliver_policy",
"opt_start_seq"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_sequence"
]
},
"opt_start_seq": {
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
}
}
},
{
"required": [
"deliver_policy",
"opt_start_time"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"by_start_time"
]
},
"opt_start_time": {
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
{
"required": [
"deliver_policy"
],
"properties": {
"deliver_policy": {
"type": "string",
"enum": [
"last_per_subject"
]
}
}
}
]
}
],
"properties": {
"durable_name": {
"description": "A unique name for a durable consumer",
"deprecationMessage": "Durable is deprecated. All consumers will have names. picked by clients.",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"name": {
"description": "A unique name for a consumer",
"type": "string",
"pattern": "^[^.*>]+$",
"minLength": 1
},
"description": {
"description": "A short description of the purpose of this consumer",
"type": "string",
"maxLength": 4096
},
"deliver_subject": {
"type": "string",
"minLength": 1
},
"ack_policy": {
"type": "string",
"enum": [
"none",
"all",
"explicit"
],
"default": "none"
},
"ack_wait": {
"description": "How long (in nanoseconds) to allow messages to remain un-acknowledged before attempting redelivery",
"minimum": 1,
"default": "30000000000",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"max_deliver": {
"description": "The number of times a message will be redelivered to consumers if not acknowledged in time",
"default": -1,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"filter_subject": {
"description": "Filter the stream by a single subjects",
"type": "string"
},
"filter_subjects": {
"description": "Filter the stream by multiple subjects",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"replay_policy": {
"type": "string",
"enum": [
"instant",
"original"
],
"default": "instant"
},
"sample_freq": {
"type": "string"
},
"rate_limit_bps": {
"description": "The rate at which messages will be delivered to clients, expressed in bit per second",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"max_ack_pending": {
"description": "The maximum number of messages without acknowledgement that can be outstanding, once this limit is reached message delivery will be suspended",
"default": 1000,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"idle_heartbeat": {
"minimum": 0,
"description": "If the Consumer is idle for more than this many nano seconds a empty message with Status header 100 will be sent indicating the consumer is still alive",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000
},
"flow_control": {
"type": "boolean",
"description": "For push consumers this will regularly send an empty mess with Status header 100 and a reply subject, consumers must reply to these messages to control the rate of message delivery"
},
"max_waiting": {
"description": "The number of pulls that can be outstanding on a pull consumer, pulls received after this is reached are ignored",
"minimum": 0,
"default": 512,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"direct": {
"type": "boolean",
"description": "Creates a special consumer that does not touch the Raft layers, not for general use by clients, internal use only",
"default": false
},
"headers_only": {
"type": "boolean",
"default": false,
"description": "Delivers only the headers of messages in the stream and not the bodies. Additionally adds Nats-Msg-Size header to indicate the size of the removed payload"
},
"max_batch": {
"type": "integer",
"description": "The largest batch property that may be specified when doing a pull on a Pull Consumer",
"default": 0
},
"max_expires": {
"description": "The maximum expires value that may be set when doing a pull on a Pull Consumer",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"max_bytes": {
"description": "The maximum bytes value that maybe set when dong a pull on a Pull Consumer",
"minimum": 0,
"default": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"inactive_threshold": {
"description": "Duration that instructs the server to cleanup ephemeral consumers that are inactive for that long",
"default": 0,
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"backoff": {
"description": "List of durations in Go format that represents a retry time scale for NaK'd messages",
"type": "array",
"items": {
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
},
"num_replicas": {
"description": "When set do not inherit the replica count from the stream but specifically set it to this amount",
"type": "integer",
"minimum": 0,
"maximum": 5,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit"
},
"mem_storage": {
"description": "Force the consumer state to be kept in memory rather than inherit the setting from the stream",
"type": "boolean",
"default": false
},
"metadata": {
"description": "Additional metadata for the Consumer",
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"created": {
"description": "The time the Consumer was created",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
},
"delivered": {
"description": "The last message delivered from this Consumer",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"ack_floor": {
"description": "The highest contiguous acknowledged message",
"type": "object",
"additionalProperties": false,
"required": [
"consumer_seq",
"stream_seq"
],
"properties": {
"consumer_seq": {
"description": "The sequence number of the Consumer",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"stream_seq": {
"description": "The sequence number of the Stream",
"$comment": "unsigned 64 bit integer",
"type": "integer",
"minimum": 0,
"maximum": 18446744073709552000
},
"last_active": {
"description": "The last time a message was delivered or acknowledged (for ack_floor)",
"$comment": "A point in time in RFC3339 format including timezone, though typically in UTC",
"type": "string",
"format": "date-time"
}
}
},
"num_ack_pending": {
"description": "The number of messages pending acknowledgement",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_redelivered": {
"description": "The number of redeliveries that have been performed",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_waiting": {
"description": "The number of pull consumers waiting for messages",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"num_pending": {
"description": "The number of messages left unconsumed in this Consumer",
"minimum": 0,
"$comment": "unsigned 64 bit integer",
"type": "integer",
"maximum": 18446744073709552000
},
"cluster": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The cluster name"
},
"leader": {
"type": "string",
"description": "The server name of the RAFT leader"
},
"replicas": {
"type": "array",
"description": "The members of the RAFT cluster",
"items": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}
},
"push_bound": {
"description": "Indicates if any client is connected and receiving messages from a push consumer",
"type": "boolean"
}
}
},
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.consumer_info_response"
}
}
}Pull next messages
Get the next batch of messages from a pull consumer.
Subject
$JS.API.CONSUMER.MSG.NEXT.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_getnext_request.json",
"description": "A request to the JetStream $JS.API.CONSUMER.MSG.NEXT API",
"title": "io.nats.jetstream.api.v1.consumer_getnext_request",
"type": "object",
"properties": {
"expires": {
"description": "A duration from now when the pull should expire, stated in nanoseconds, 0 for no expiry",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
},
"batch": {
"description": "How many messages the server should deliver to the requestor",
"minimum": 0,
"maximum": 256,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer"
},
"max_bytes": {
"description": "Sends at most this many bytes to the requestor, limited by consumer configuration max_bytes",
"minimum": 0,
"$comment": "integer with a dynamic bit size depending on the platform the cluster runs on, can be up to 64bit",
"type": "integer",
"maximum": 9223372036854776000
},
"no_wait": {
"type": "boolean",
"description": "When true a response with a 404 status header will be returned when no messages are available"
},
"idle_heartbeat": {
"description": "When not 0 idle heartbeats will be sent on this interval",
"$comment": "nanoseconds depicting a duration in time, signed 64 bit integer",
"type": "integer",
"maximum": 9223372036854776000,
"minimum": -9223372036854776000
}
}
}Stepdown leader for a clustered consumer
Force the current consumer Raft leader to stepdown for another peer to take over.
Subject
$JS.API.CONSUMER.LEADER.STEPDOWN.{stream}.{consumer}
Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/consumer_leader_stepdown_response.json",
"description": "A response from the JetStream $JS.API.CONSUMER.LEADER.STEPDOWN API",
"title": "io.nats.jetstream.api.v1.consumer_leader_stepdown_response",
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"success"
],
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "If the leader successfully stood down",
"default": false
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.consumer_leader_stepdown_response"
}
}
}Push consumer flow control
Subject
$JS.FC.>
Message ack
The subject for a client to acknowledge receipt of a message.
Subject
$JS.ACK.{}
Meta API
| Name | Subject | System Account |
|---|---|---|
| Leader stepdown | $JS.API.META.LEADER.STEPDOWN | true |
| Remove server | $JS.API.SERVER.REMOVE | true |
Leader stepdown
Force the current meta Raft leader to stepdown for another peer to take over.
Subject
$JS.API.META.LEADER.STEPDOWN
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/meta_leader_stepdown_request.json",
"description": "A request to the JetStream $JS.API.META.LEADER.STEPDOWN API",
"title": "io.nats.jetstream.api.v1.meta_leader_stepdown_request",
"type": "object",
"properties": {
"placement": {
"type": "object",
"description": "Placement requirements for a stream",
"required": [
"cluster"
],
"properties": {
"cluster": {
"type": "string",
"description": "The desired cluster name to place the stream"
},
"tags": {
"description": "Tags required on servers hosting this stream",
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/meta_leader_stepdown_response.json",
"description": "A response from the JetStream $JS.API.META.LEADER.STEPDOWN API",
"title": "io.nats.jetstream.api.v1.meta_leader_stepdown_response",
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"success"
],
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "If the leader successfully stood down",
"default": false
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.meta_leader_stepdown_response"
}
}
}Remove server
Remove a server as a peer in the JetStream meta group.
Subject
$JS.API.SERVER.REMOVE
Request Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/meta_server_remove_request.json",
"description": "A request to the JetStream $JS.API.SERVER.REMOVE API",
"title": "io.nats.jetstream.api.v1.meta_server_remove_request",
"type": "object",
"properties": {
"peer": {
"type": "string",
"description": "The Name of the server to remove from the meta group"
},
"peer_id": {
"type": "string",
"description": "Peer ID of the peer to be removed. If specified this is used instead of the server name"
}
}
}Response Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/api/v1/meta_server_remove_response.json",
"description": "A response from the JetStream $JS.API.SERVER.REMOVE API",
"title": "io.nats.jetstream.api.v1.meta_server_remove_response",
"oneOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "integer",
"description": "HTTP like error code in the 300 to 500 range",
"minimum": 300,
"maximum": 699
},
"description": {
"type": "string",
"description": "A human friendly description of the error"
},
"err_code": {
"type": "integer",
"description": "The NATS error code unique to each kind of error",
"minimum": 0,
"maximum": 65535
}
}
}
}
},
{
"required": [
"success"
],
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "If the peer was successfully removed",
"default": false
}
}
}
],
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.api.v1.meta_server_remove_response"
}
}
}Advisory events
| Name | Subject | System Account |
|---|---|---|
| API Access | $JS.EVENT.ADVISORY.API | false |
| Message reached max deliveries | $JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.{stream}.{consumer} | false |
| Message negatively acknowledged (NAK) | $JS.EVENT.ADVISORY.CONSUMER.MSG_NAKED.{stream}.{consumer} | false |
| Message terminated (TERM) | $JS.EVENT.ADVISORY.CONSUMER.MSG_TERMINATED.{stream}.{consumer} | false |
| Stream created | $JS.EVENT.ADVISORY.STREAM.CREATED.{stream} | false |
| Stream deleted | $JS.EVENT.ADVISORY.STREAM.DELETED.{stream} | false |
| Stream updated | $JS.EVENT.ADVISORY.STREAM.UPDATED.{stream} | false |
| Consumer created | $JS.EVENT.ADVISORY.CONSUMER.CREATED.{stream}.{consumer} | false |
| Consumer deleted | $JS.EVENT.ADVISORY.CONSUMER.DELETED.{stream}.{consumer} | false |
| Stream snapshot created | $JS.EVENT.ADVISORY.STREAM.SNAPSHOT_CREATE.{stream} | false |
| Stream snapshot completed | $JS.EVENT.ADVISORY.STREAM.SNAPSHOT_COMPLETE.{stream} | false |
| Stream restore created | $JS.EVENT.ADVISORY.STREAM.RESTORE_CREATE.{stream} | false |
| Stream restore completed | $JS.EVENT.ADVISORY.STREAM.RESTORE_COMPLETE.{stream} | false |
| Stream leader elected | $JS.EVENT.ADVISORY.STREAM.LEADER_ELECTED.{stream} | false |
| Stream quorum lost | $JS.EVENT.ADVISORY.STREAM.QUORUM_LOST.{stream} | false |
| Consumer leader elected | $JS.EVENT.ADVISORY.CONSUMER.LEADER_ELECTED.{stream}.{consumer} | false |
| Consumer quorum lost | $JS.EVENT.ADVISORY.CONSUMER.QUORUM_LOST.{stream}.{consumer} | false |
| Server out of storage | $JS.EVENT.ADVISORY.SERVER.OUT_OF_STORAGE | false |
| Server removed | $JS.EVENT.ADVISORY.SERVER.REMOVED | false |
API Access
A notification when the JetStream API is accessed.
Subject
$JS.EVENT.ADVISORY.API
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/api_audit.json",
"description": "Advisory published when the JetStream API is accessed across the network",
"title": "io.nats.jetstream.advisory.v1.api_audit",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"server",
"client",
"subject",
"response"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.api_audit"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"server": {
"type": "string",
"description": "The server this event originates from, either a generated ID or the configured name",
"minLength": 1
},
"subject": {
"type": "string",
"description": "The subject the admin API request was received on",
"minLength": 1
},
"response": {
"type": "string",
"description": "The full unparsed body of the response sent to the caller"
},
"request": {
"type": "string",
"description": "The full unparsed body of the request received from the client"
},
"client": {
"type": "object",
"additionalProperties": false,
"description": "Details about the client that connected to the server",
"required": [
"acc"
],
"properties": {
"start": {
"type": "string",
"description": "Timestamp when the client connected"
},
"stop": {
"type": "string",
"description": "Timestamp when the client disconnected"
},
"host": {
"type": "string",
"description": "The remote host the client is connected from"
},
"id": {
"type": "string",
"description": "The internally assigned client ID for this connection"
},
"acc": {
"type": "string",
"description": "The account this user logged in to"
},
"user": {
"type": "string",
"description": "The clients username"
},
"name": {
"type": "string",
"description": "The name presented by the client during connection"
},
"lang": {
"type": "string",
"description": "The programming language library in use by the client"
},
"ver": {
"type": "string",
"description": "The version of the client library in use"
},
"rtt": {
"type": "number",
"description": "The last known latency between the NATS Server and the Client in nanoseconds"
},
"server": {
"type": "string",
"description": "The server that the client was connected to"
},
"cluster": {
"type": "string",
"description": "The cluster name the server is connected to"
},
"alts": {
"type": "array",
"items": {
"description": "List of alternative clusters that can be used as overflow for resource placement, in RTT order",
"type": "string"
}
},
"jwt": {
"type": "string",
"description": "The JWT presented in the connection"
},
"issuer_key": {
"type": "string",
"description": "The public signing key or account identity key used to issue the user"
},
"name_tag": {
"type": "string",
"description": "The name extracted from the user JWT claim"
},
"kind": {
"type": "string",
"description": "The kind of client. Can be Client/Leafnode/Router/Gateway/JetStream/Account/System"
},
"client_type": {
"type": "string",
"description": "The type of client. When kind is Client, this contains the type: mqtt/websocket/nats"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags extracted from the JWT"
}
}
}
}
}Message reached max deliveries
A notification when a message exceeds its delivery threshold for a given consumer.
Subject
$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/max_deliver.json",
"description": "Advisory published when a message have reached its maximum delivery attempts",
"title": "io.nats.jetstream.advisory.v1.max_deliver",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"consumer",
"stream_seq",
"deliveries"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.max_deliver"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the stream where the message is stored"
},
"consumer": {
"type": "string",
"description": "The name of the consumer where the message reached its limit"
},
"stream_seq": {
"type": "string",
"minimum": 1,
"description": "The sequence of the message in the stream that failed"
},
"deliveries": {
"type": "integer",
"minimum": 1,
"description": "The number of deliveries that were attempted"
}
}
}Message negatively acknowledged (NAK)
A notification published when a message has been negatively acknowledged for a given consumer.
Subject
$JS.EVENT.ADVISORY.CONSUMER.MSG_NAKED.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/nak.json",
"description": "Advisory published when a message was naked using a AckNak acknowledgement",
"title": "io.nats.jetstream.advisory.v1.nak",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"consumer",
"consumer_seq",
"stream_seq",
"deliveries"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.nak"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the stream where the message is stored"
},
"consumer": {
"type": "string",
"description": "The name of the consumer where the message was naked"
},
"consumer_seq": {
"type": "string",
"minimum": 1,
"description": "The sequence of the message in the consumer that was naked"
},
"stream_seq": {
"type": "string",
"minimum": 1,
"description": "The sequence of the message in the stream that was naked"
},
"deliveries": {
"type": "integer",
"minimum": 1,
"description": "The number of deliveries that were attempted"
},
"domain": {
"type": "string",
"minimum": 1,
"description": "The domain of the JetStreamServer"
}
}
}Message terminated (TERM)
A notification published when a message has been terminated for a given consumer.
Subject
$JS.EVENT.ADVISORY.CONSUMER.MSG_TERMINATED.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/terminated.json",
"description": "Advisory published when a message was terminated using a AckTerm acknowledgement",
"title": "io.nats.jetstream.advisory.v1.terminated",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"consumer",
"consumer_seq",
"stream_seq",
"deliveries"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.terminated"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the stream where the message is stored"
},
"consumer": {
"type": "string",
"description": "The name of the consumer where the message was terminated"
},
"stream_seq": {
"type": "string",
"minimum": 1,
"description": "The sequence of the message in the stream that was terminated"
},
"consumer_seq": {
"type": "string",
"minimum": 1,
"description": "The sequence of the message in the consumer that was terminated"
},
"deliveries": {
"type": "integer",
"minimum": 1,
"description": "The number of deliveries that were attempted"
}
}
}Stream created
A notification when a stream is created.
Subject
$JS.EVENT.ADVISORY.STREAM.CREATED.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/stream_action.json",
"description": "An Advisory sent when a Stream is created, modified or deleted",
"title": "io.nats.jetstream.advisory.v1.stream_action",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"action"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.stream_action"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"action": {
"type": "string",
"description": "The action that the event describes",
"enum": [
"create",
"delete",
"modify"
]
},
"stream": {
"type": "string",
"description": "The name of the Stream that's acted on"
},
"template": {
"type": "string",
"description": "The Stream Template that manages the Stream"
}
}
}Stream deleted
A notification when a stream is deleted.
Subject
$JS.EVENT.ADVISORY.STREAM.DELETED.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/stream_action.json",
"description": "An Advisory sent when a Stream is created, modified or deleted",
"title": "io.nats.jetstream.advisory.v1.stream_action",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"action"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.stream_action"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"action": {
"type": "string",
"description": "The action that the event describes",
"enum": [
"create",
"delete",
"modify"
]
},
"stream": {
"type": "string",
"description": "The name of the Stream that's acted on"
},
"template": {
"type": "string",
"description": "The Stream Template that manages the Stream"
}
}
}Stream updated
A notification when a stream is updated.
Subject
$JS.EVENT.ADVISORY.STREAM.UPDATED.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/stream_action.json",
"description": "An Advisory sent when a Stream is created, modified or deleted",
"title": "io.nats.jetstream.advisory.v1.stream_action",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"action"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.stream_action"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"action": {
"type": "string",
"description": "The action that the event describes",
"enum": [
"create",
"delete",
"modify"
]
},
"stream": {
"type": "string",
"description": "The name of the Stream that's acted on"
},
"template": {
"type": "string",
"description": "The Stream Template that manages the Stream"
}
}
}Consumer created
A notification when a consumer is created.
Subject
$JS.EVENT.ADVISORY.CONSUMER.CREATED.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/consumer_action.json",
"description": "An Advisory sent when a Consumer is created or deleted",
"title": "io.nats.jetstream.advisory.v1.consumer_action",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"action"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.consumer_action"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"action": {
"type": "string",
"description": "The action that the event describes",
"enum": [
"create",
"delete"
]
},
"stream": {
"type": "string",
"description": "The name of the Stream that the Consumer belongs to"
},
"consumer": {
"type": "string",
"description": "The name of the Consumer that's acted on"
}
}
}Consumer deleted
A notification when a consumer is deleted.
Subject
$JS.EVENT.ADVISORY.CONSUMER.DELETED.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/consumer_action.json",
"description": "An Advisory sent when a Consumer is created or deleted",
"title": "io.nats.jetstream.advisory.v1.consumer_action",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"action"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.consumer_action"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"action": {
"type": "string",
"description": "The action that the event describes",
"enum": [
"create",
"delete"
]
},
"stream": {
"type": "string",
"description": "The name of the Stream that the Consumer belongs to"
},
"consumer": {
"type": "string",
"description": "The name of the Consumer that's acted on"
}
}
}Stream snapshot created
A notification when a stream snapshot has been created. Note, the snapshot process is asynchronous, so the see the SNAPSHOT_COMPLETE advisory.
Subject
$JS.EVENT.ADVISORY.STREAM.SNAPSHOT_CREATE.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/snapshot_create.json",
"description": "An Advisory sent when a Stream snapshot is created",
"title": "io.nats.jetstream.advisory.v1.snapshot_create",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"blocks",
"block_size",
"client"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.snapshot_create"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the Stream being snapshotted"
},
"blocks": {
"type": "integer",
"description": "Approximate number of blocks in the snapshot",
"minimum": 0
},
"block_size": {
"type": "integer",
"description": "The size, in bytes, of every block",
"minimum": 1
},
"client": {
"type": "object",
"additionalProperties": false,
"description": "Details about the client that connected to the server",
"required": [
"acc"
],
"properties": {
"start": {
"type": "string",
"description": "Timestamp when the client connected"
},
"stop": {
"type": "string",
"description": "Timestamp when the client disconnected"
},
"host": {
"type": "string",
"description": "The remote host the client is connected from"
},
"id": {
"type": "string",
"description": "The internally assigned client ID for this connection"
},
"acc": {
"type": "string",
"description": "The account this user logged in to"
},
"user": {
"type": "string",
"description": "The clients username"
},
"name": {
"type": "string",
"description": "The name presented by the client during connection"
},
"lang": {
"type": "string",
"description": "The programming language library in use by the client"
},
"ver": {
"type": "string",
"description": "The version of the client library in use"
},
"rtt": {
"type": "number",
"description": "The last known latency between the NATS Server and the Client in nanoseconds"
},
"server": {
"type": "string",
"description": "The server that the client was connected to"
},
"cluster": {
"type": "string",
"description": "The cluster name the server is connected to"
},
"alts": {
"type": "array",
"items": {
"description": "List of alternative clusters that can be used as overflow for resource placement, in RTT order",
"type": "string"
}
},
"jwt": {
"type": "string",
"description": "The JWT presented in the connection"
},
"issuer_key": {
"type": "string",
"description": "The public signing key or account identity key used to issue the user"
},
"name_tag": {
"type": "string",
"description": "The name extracted from the user JWT claim"
},
"kind": {
"type": "string",
"description": "The kind of client. Can be Client/Leafnode/Router/Gateway/JetStream/Account/System"
},
"client_type": {
"type": "string",
"description": "The type of client. When kind is Client, this contains the type: mqtt/websocket/nats"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags extracted from the JWT"
}
}
}
}
}Stream snapshot completed
A notification when a stream snapshot has been completed.
Subject
$JS.EVENT.ADVISORY.STREAM.SNAPSHOT_COMPLETE.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/snapshot_complete.json",
"description": "An Advisory sent when a Stream snapshot is completed",
"title": "io.nats.jetstream.advisory.v1.snapshot_complete",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"start",
"end",
"client"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.snapshot_complete"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The Stream that had the snapshot"
},
"start": {
"type": "string",
"description": "The time the snapshot was created"
},
"end": {
"type": "string",
"description": "The time the snapshot was completed"
},
"client": {
"type": "object",
"additionalProperties": false,
"description": "Details about the client that connected to the server",
"required": [
"acc"
],
"properties": {
"start": {
"type": "string",
"description": "Timestamp when the client connected"
},
"stop": {
"type": "string",
"description": "Timestamp when the client disconnected"
},
"host": {
"type": "string",
"description": "The remote host the client is connected from"
},
"id": {
"type": "string",
"description": "The internally assigned client ID for this connection"
},
"acc": {
"type": "string",
"description": "The account this user logged in to"
},
"user": {
"type": "string",
"description": "The clients username"
},
"name": {
"type": "string",
"description": "The name presented by the client during connection"
},
"lang": {
"type": "string",
"description": "The programming language library in use by the client"
},
"ver": {
"type": "string",
"description": "The version of the client library in use"
},
"rtt": {
"type": "number",
"description": "The last known latency between the NATS Server and the Client in nanoseconds"
},
"server": {
"type": "string",
"description": "The server that the client was connected to"
},
"cluster": {
"type": "string",
"description": "The cluster name the server is connected to"
},
"alts": {
"type": "array",
"items": {
"description": "List of alternative clusters that can be used as overflow for resource placement, in RTT order",
"type": "string"
}
},
"jwt": {
"type": "string",
"description": "The JWT presented in the connection"
},
"issuer_key": {
"type": "string",
"description": "The public signing key or account identity key used to issue the user"
},
"name_tag": {
"type": "string",
"description": "The name extracted from the user JWT claim"
},
"kind": {
"type": "string",
"description": "The kind of client. Can be Client/Leafnode/Router/Gateway/JetStream/Account/System"
},
"client_type": {
"type": "string",
"description": "The type of client. When kind is Client, this contains the type: mqtt/websocket/nats"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags extracted from the JWT"
}
}
}
}
}Stream restore created
A notification when a stream restore has been created. Note, the restore process is asynchronous, so the see the RESTORE_COMPLETE advisory.
Subject
$JS.EVENT.ADVISORY.STREAM.RESTORE_CREATE.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/restore_create.json",
"description": "An Advisory sent when a Stream restore is started",
"title": "io.nats.jetstream.advisory.v1.restore_create",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"client"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.restore_create"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The Stream being restored"
},
"client": {
"type": "object",
"additionalProperties": false,
"description": "Details about the client that connected to the server",
"required": [
"acc"
],
"properties": {
"start": {
"type": "string",
"description": "Timestamp when the client connected"
},
"stop": {
"type": "string",
"description": "Timestamp when the client disconnected"
},
"host": {
"type": "string",
"description": "The remote host the client is connected from"
},
"id": {
"type": "string",
"description": "The internally assigned client ID for this connection"
},
"acc": {
"type": "string",
"description": "The account this user logged in to"
},
"user": {
"type": "string",
"description": "The clients username"
},
"name": {
"type": "string",
"description": "The name presented by the client during connection"
},
"lang": {
"type": "string",
"description": "The programming language library in use by the client"
},
"ver": {
"type": "string",
"description": "The version of the client library in use"
},
"rtt": {
"type": "number",
"description": "The last known latency between the NATS Server and the Client in nanoseconds"
},
"server": {
"type": "string",
"description": "The server that the client was connected to"
},
"cluster": {
"type": "string",
"description": "The cluster name the server is connected to"
},
"alts": {
"type": "array",
"items": {
"description": "List of alternative clusters that can be used as overflow for resource placement, in RTT order",
"type": "string"
}
},
"jwt": {
"type": "string",
"description": "The JWT presented in the connection"
},
"issuer_key": {
"type": "string",
"description": "The public signing key or account identity key used to issue the user"
},
"name_tag": {
"type": "string",
"description": "The name extracted from the user JWT claim"
},
"kind": {
"type": "string",
"description": "The kind of client. Can be Client/Leafnode/Router/Gateway/JetStream/Account/System"
},
"client_type": {
"type": "string",
"description": "The type of client. When kind is Client, this contains the type: mqtt/websocket/nats"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags extracted from the JWT"
}
}
}
}
}Stream restore completed
A notification when a stream restore has been completed.
Subject
$JS.EVENT.ADVISORY.STREAM.RESTORE_COMPLETE.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/restore_complete.json",
"description": "An Advisory sent when a Stream restore is completed",
"title": "io.nats.jetstream.advisory.v1.restore_complete",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"start",
"end",
"bytes",
"client"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.restore_complete"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The Stream being restored"
},
"start": {
"type": "string",
"description": "The time the Restore process started"
},
"end": {
"type": "string",
"description": "The time the Restore was completed"
},
"bytes": {
"type": "integer",
"description": "The number of bytes that was received",
"minimum": 0
},
"client": {
"type": "object",
"additionalProperties": false,
"description": "Details about the client that connected to the server",
"required": [
"acc"
],
"properties": {
"start": {
"type": "string",
"description": "Timestamp when the client connected"
},
"stop": {
"type": "string",
"description": "Timestamp when the client disconnected"
},
"host": {
"type": "string",
"description": "The remote host the client is connected from"
},
"id": {
"type": "string",
"description": "The internally assigned client ID for this connection"
},
"acc": {
"type": "string",
"description": "The account this user logged in to"
},
"user": {
"type": "string",
"description": "The clients username"
},
"name": {
"type": "string",
"description": "The name presented by the client during connection"
},
"lang": {
"type": "string",
"description": "The programming language library in use by the client"
},
"ver": {
"type": "string",
"description": "The version of the client library in use"
},
"rtt": {
"type": "number",
"description": "The last known latency between the NATS Server and the Client in nanoseconds"
},
"server": {
"type": "string",
"description": "The server that the client was connected to"
},
"cluster": {
"type": "string",
"description": "The cluster name the server is connected to"
},
"alts": {
"type": "array",
"items": {
"description": "List of alternative clusters that can be used as overflow for resource placement, in RTT order",
"type": "string"
}
},
"jwt": {
"type": "string",
"description": "The JWT presented in the connection"
},
"issuer_key": {
"type": "string",
"description": "The public signing key or account identity key used to issue the user"
},
"name_tag": {
"type": "string",
"description": "The name extracted from the user JWT claim"
},
"kind": {
"type": "string",
"description": "The kind of client. Can be Client/Leafnode/Router/Gateway/JetStream/Account/System"
},
"client_type": {
"type": "string",
"description": "The type of client. When kind is Client, this contains the type: mqtt/websocket/nats"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags extracted from the JWT"
}
}
}
}
}Stream leader elected
A notification when a leader is elected for a replicated stream.
Subject
$JS.EVENT.ADVISORY.STREAM.LEADER_ELECTED.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/stream_leader_elected.json",
"description": "An Advisory sent when a clustered Stream elected a new leader",
"title": "io.nats.jetstream.advisory.v1.stream_leader_elected",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"leader",
"replicas"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.stream_leader_elected"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the Stream that elected a leader"
},
"leader": {
"type": "string",
"description": "The server name of the elected leader"
},
"replicas": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}Stream quorum lost
A notification when qourum is lost for a replicated stream.
Subject
$JS.EVENT.ADVISORY.STREAM.QUORUM_LOST.{stream}
Params:
stream- stream
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/stream_quorum_lost.json",
"description": "An Advisory sent when a clustered Stream lost quorum",
"title": "io.nats.jetstream.advisory.v1.stream_quorum_lost",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"replicas"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.stream_quorum_lost"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the Stream that lost quorum"
},
"replicas": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}Consumer leader elected
A notification when a leader is elected for a replicated consumer.
Subject
$JS.EVENT.ADVISORY.CONSUMER.LEADER_ELECTED.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/consumer_leader_elected.json",
"description": "An Advisory sent when a clustered Consumer elected a new leader",
"title": "io.nats.jetstream.advisory.v1.consumer_leader_elected",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"consumer",
"leader",
"replicas"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.consumer_leader_elected"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the Stream the Consumer belongs to"
},
"consumer": {
"type": "string",
"description": "The name of the Consumer that elected a new leader"
},
"leader": {
"type": "string",
"description": "The server name of the elected leader"
},
"replicas": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}Consumer quorum lost
A notification when qourum is lost for a replicated consumer.
Subject
$JS.EVENT.ADVISORY.CONSUMER.QUORUM_LOST.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/consumer_quorum_lost.json",
"description": "An Advisory sent when a clustered Consumer lost quorum",
"title": "io.nats.jetstream.advisory.v1.consumer_quorum_lost",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"consumer",
"replicas"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.consumer_quorum_lost"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the Stream the Consumer belongs to"
},
"consumer": {
"type": "string",
"description": "The name of the Consumer that lost quorum"
},
"replicas": {
"type": "object",
"required": [
"name",
"current",
"active"
],
"properties": {
"name": {
"description": "The server name of the peer",
"type": "string",
"minimum": 1
},
"current": {
"description": "Indicates if the server is up to date and synchronised",
"type": "boolean",
"default": false
},
"active": {
"description": "Nanoseconds since this peer was last seen",
"type": "number"
},
"offline": {
"description": "Indicates the node is considered offline by the group",
"type": "boolean",
"default": false
},
"lag": {
"description": "How many uncommitted operations this peer is behind the leader",
"type": "integer",
"minimum": 0
}
}
}
}
}Server out of storage
A notification that a server has no more storage available.
Subject
$JS.EVENT.ADVISORY.SERVER.OUT_OF_STORAGE
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/server_out_of_space.json",
"description": "An Advisory sent when a Server has run out of disk space",
"title": "io.nats.jetstream.advisory.v1.server_out_of_space",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"server",
"server_id"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.server_out_of_space"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The Stream that triggered the out of space event"
},
"server": {
"type": "string",
"description": "The server name that ran out of space"
},
"server_id": {
"type": "string",
"description": "The server ID that ran out of space"
},
"cluster": {
"type": "string",
"description": "The cluster the server is in"
}
}
}Server removed
A notification that a server has been removed from the system.
Subject
$JS.EVENT.ADVISORY.SERVER.REMOVED
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/advisory/v1/server_removed.json",
"description": "An Advisory sent when a Server has been removed from the cluster",
"title": "io.nats.jetstream.advisory.v1.server_removed",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"server",
"server_id",
"cluster"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.advisory.v1.server_removed"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"server": {
"type": "string",
"description": "The server name that was remove"
},
"server_id": {
"type": "string",
"description": "The server ID that was remove"
},
"cluster": {
"type": "string",
"description": "The cluster the server was in"
},
"domain": {
"type": "string",
"description": "The domain the server was in"
}
}
}Metrics
| Name | Subject | System Account |
|---|---|---|
| Consumer ack info | $JS.EVENT.METRIC.CONSUMER.ACK.{stream}.{consumer} | false |
Consumer ack info
A published metric when a message was acknowledged to a consumer with Ack Sampling enabled.
Subject
$JS.EVENT.METRIC.CONSUMER.ACK.{stream}.{consumer}
Params:
stream- streamconsumer- consumer
Schema
Expand/Collapse
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://nats.io/schemas/jetstream/metric/v1/consumer_ack.json",
"description": "Metric published when a message was acknowledged to a consumer with Ack Sampling enabled",
"title": "io.nats.jetstream.metric.v1.consumer_ack",
"type": "object",
"required": [
"type",
"id",
"timestamp",
"stream",
"consumer",
"stream_seq",
"consumer_seq",
"ack_time",
"deliveries"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "io.nats.jetstream.metric.v1.consumer_ack"
},
"id": {
"type": "string",
"description": "Unique correlation ID for this event"
},
"timestamp": {
"type": "string",
"description": "The time this event was created in RFC3339 format"
},
"stream": {
"type": "string",
"description": "The name of the stream where the message is stored"
},
"consumer": {
"type": "string",
"description": "The name of the consumer where the message is held"
},
"stream_seq": {
"type": "integer",
"minimum": 1,
"description": "The sequence of the message in the stream that were acknowledged"
},
"consumer_seq": {
"type": "integer",
"minimum": 1,
"description": "The sequence of the message in the consumer that were acknowledged"
},
"ack_time": {
"type": "integer",
"minimum": 1,
"description": "The time it took on the final delivery for the message to be acknowledged in nanoseconds"
},
"deliveries": {
"type": "integer",
"minimum": 1,
"description": "The number of deliveries that were attempted before being acknowledged"
}
}
}Errors
| NATS Code | HTTP Error Code | Message | Comment |
|---|---|---|---|
| 10040 | 400 | peer not a member | |
| 10019 | 400 | consumer expected to be ephemeral but detected a durable name set in subject | |
| 10022 | 400 | stream external delivery prefix {prefix} overlaps with stream subject {subject} | |
| 10002 | 400 | resource limits exceeded for account | |
| 10008 | 503 | JetStream system temporarily unavailable | |
| 10065 | 400 | subjects overlap with an existing stream | |
| 10071 | 400 | wrong last sequence: {seq} | |
| 10073 | 400 | template name in subject does not match request | |
| 10005 | 400 | {err} | Error causing no peers to be available |
| 10020 | 400 | consumer expected to be ephemeral but a durable name was set in request | |
| 10023 | 503 | insufficient resources | |
| 10030 | 400 | stream mirror must have max message size >= source | |
| 10067 | 500 | {err} | Generic stream template deletion failed error string |
| 10003 | 400 | bad request | |
| 10036 | 503 | not currently supported in clustered mode | |
| 10014 | 404 | consumer not found | |
| 10046 | 400 | stream source must have max message size >= target | |
| 10048 | 500 | {err} | Generic stream assignment error string |
| 10054 | 400 | message size exceeds maximum allowed | |
| 10066 | 500 | {err} | Generic template creation failed string |
| 10025 | 400 | invalid JSON | |
| 10024 | 400 | stream external delivery prefix {prefix} must not contain wildcards | |
| 10062 | 500 | restore failed: {err} | |
| 10004 | 503 | incomplete results | |
| 10035 | 503 | account not found | |
| 10041 | 500 | {err} | General RAFT error string |
| 10042 | 500 | JetStream unable to subscribe to restore snapshot {subject}: {err} | |
| 10050 | 500 | {err} | General stream deletion error string |
| 10021 | 400 | stream external api prefix {prefix} must not overlap with {subject} | |
| 10034 | 400 | stream mirrors can not contain subjects | |
| 10076 | 503 | JetStream not enabled | |
| 10039 | 503 | JetStream not enabled for account | |
| 10043 | 400 | sequence {seq} not found | |
| 10055 | 400 | stream mirror configuration can not be updated | |
| 10063 | 503 | expected stream sequence does not match | |
| 10070 | 400 | wrong last msg ID: {id} | |
| 10072 | 500 | JetStream unable to open temp storage for restore | |
| 10047 | 500 | insufficient storage resources available | |
| 10056 | 400 | stream name in subject does not match request | |
| 10060 | 400 | expected stream does not match | |
| 10029 | 500 | {err} | generic mirror consumer setup failure string |
| 10038 | 400 | expected an empty request payload | |
| 10058 | 400 | stream name already in use with a different configuration | |
| 10011 | 400 | tags placement not supported for operation | |
| 10026 | 400 | maximum consumers limit reached | |
| 10045 | 500 | {err} | General source consumer setup failure string |
| 10012 | 500 | {err} | General consumer creation failure string |
| 10016 | 400 | consumer expected to be durable but no durable name set in subject | |
| 10053 | 500 | {err} | General stream limits exceeded error string |
| 10061 | 400 | Replicas configuration can not be updated | |
| 10068 | 404 | template not found | |
| 10007 | 500 | JetStream cluster not assigned to this server | |
| 10009 | 500 | JetStream cluster can not handle request | |
| 10013 | 400 | consumer name already in use | |
| 10031 | 400 | stream mirrors can not also contain other sources | |
| 10059 | 404 | stream not found | |
| 10010 | 503 | JetStream clustering support required | |
| 10018 | 400 | consumer expected to be durable but a durable name was not set | |
| 10027 | 400 | maximum number of streams reached | |
| 10032 | 400 | stream mirrors can not have both start seq and start time configured | |
| 10064 | 500 | snapshot failed: {err} | |
| 10069 | 500 | {err} | Generic stream update error string |
| 10006 | 500 | JetStream not in clustered mode | |
| 10017 | 400 | consumer name in subject does not match durable name in request | |
| 10028 | 500 | insufficient memory resources available | |
| 10033 | 400 | stream mirrors can not contain filtered subjects | |
| 10049 | 500 | {err} | Generic stream creation error string |
| 10044 | 400 | server is not a member of the cluster | |
| 10037 | 404 | no message found | |
| 10015 | 400 | deliver subject not valid | |
| 10051 | 500 | {err} | General stream failure string |
| 10052 | 500 | {err} | Stream configuration validation error string |
| 10074 | 500 | replicas > 1 not supported in non-clustered mode | |
| 10057 | 500 | {err} | Generic message deletion failure error string |
| 10075 | 503 | peer remap failed | |
| 10077 | 503 | {err} | Generic error when storing a message failed |
| 10078 | 400 | consumer config required | |
| 10079 | 400 | consumer deliver subject has wildcards | |
| 10080 | 400 | consumer in push mode can not set max waiting | |
| 10081 | 400 | consumer deliver subject forms a cycle | |
| 10082 | 400 | consumer requires ack policy for max ack pending | |
| 10083 | 400 | consumer idle heartbeat needs to be >= 100ms | |
| 10084 | 400 | consumer in pull mode requires ack policy | |
| 10085 | 400 | consumer in pull mode requires a durable name | |
| 10086 | 400 | consumer in pull mode can not have rate limit set | |
| 10087 | 400 | consumer max waiting needs to be positive | |
| 10088 | 400 | consumer idle heartbeat requires a push based consumer | |
| 10089 | 400 | consumer flow control requires a push based consumer | |
| 10090 | 400 | consumer direct requires a push based consumer | |
| 10091 | 400 | consumer direct requires an ephemeral consumer | |
| 10092 | 400 | consumer direct on a mapped consumer | |
| 10093 | 400 | consumer filter subject is not a valid subset of the interest subjects | |
| 10094 | 400 | {err} | Generic delivery policy error |
| 10095 | 400 | failed to parse consumer sampling configuration: {err} | |
| 10096 | 500 | stream not valid | |
| 10098 | 400 | workqueue stream requires explicit ack | |
| 10099 | 400 | multiple non-filtered consumers not allowed on workqueue stream | |
| 10100 | 400 | filtered consumer not unique on workqueue stream | |
| 10101 | 400 | consumer must be deliver all on workqueue stream | |
| 10102 | 400 | consumer name is too long, maximum allowed is {max} | |
| 10103 | 400 | durable name can not contain '.', '*', '>' | |
| 10104 | 500 | error creating store for consumer: {err} | |
| 10105 | 400 | consumer already exists and is still active | |
| 10106 | 400 | consumer replacement durable config not the same | |
| 10107 | 400 | consumer description is too long, maximum allowed is {max} | |
| 10097 | 400 | header size exceeds maximum allowed of 64k | |
| 10108 | 400 | consumer with flow control also needs heartbeats | |
| 10109 | 400 | invalid operation on sealed stream | |
| 10110 | 500 | {err} | Generic stream purge failure error string |
| 10111 | 500 | {err} | Generic stream rollup failure error string |
| 10112 | 400 | invalid push consumer deliver subject | |
| 10113 | 400 | account requires a stream config to have max bytes set | |
| 10114 | 400 | consumer max request batch needs to be > 0 | |
| 10115 | 400 | consumer max request expires needs to be >= 1ms | |
| 10116 | 400 | max deliver is required to be > length of backoff values | |
| 10117 | 500 | subject details would exceed maximum allowed | |
| 10118 | 500 | stream is offline | |
| 10119 | 500 | consumer is offline | |
| 10120 | 400 | no JetStream default or applicable tiered limit present | |
| 10121 | 400 | consumer max ack pending exceeds system limit of {limit} | |
| 10122 | 400 | stream max bytes exceeds account limit max stream bytes | |
| 10123 | 400 | can not move and scale a stream in a single update | |
| 10124 | 400 | stream move already in progress: {msg} | |
| 10125 | 400 | consumer max request batch exceeds server limit of {limit} | |
| 10126 | 400 | consumer config replica count exceeds parent stream | |
| 10127 | 400 | Consumer name can not contain path separators | |
| 10128 | 400 | Stream name can not contain path separators | |
| 10129 | 400 | stream move not in progress | |
| 10130 | 400 | stream name already in use, cannot restore | |
| 10131 | 400 | Consumer create request did not match filtered subject from create subject | |
| 10132 | 400 | Consumer Durable and Name have to be equal if both are provided | |
| 10133 | 400 | replicas count cannot be negative | |
| 10134 | 400 | consumer config replicas must match interest retention stream's replicas |