NGINX

NGINX Stream Keyvals API

The Stream Keyvals API from NGINX — 2 operation(s) for stream keyvals.

GitHub OpenAPI

Operations 5

GET /stream/keyvals/ NGINX Return Key-Value Pairs from All Stream Keyval Zones #
GET /stream/keyvals/{streamKeyvalZoneName} NGINX Return Key-Value Pairs from a Stream Keyval Zone #
POST /stream/keyvals/{streamKeyvalZoneName} NGINX Add a Key-Value Pair to the Stream Keyval Zone #
PATCH /stream/keyvals/{streamKeyvalZoneName} NGINX Modify a Key-Value or Delete a Key #
DELETE /stream/keyvals/{streamKeyvalZoneName} NGINX Empty the Stream Keyval Zone #

Documentation

📖
Documentation
https://nginx.org/en/docs/http/ngx_http_api_module.html
📖
APIReference
https://nginx.org/en/docs/http/ngx_http_api_module.html#api
📖
Documentation
https://nginx.org/en/docs/http/ngx_http_stub_status_module.html
📖
Documentation
https://nginx.org/en/docs/njs/
📖
APIReference
https://nginx.org/en/docs/njs/reference.html
📖
GettingStarted
https://nginx.org/en/docs/njs/install.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/nginx/refs/heads/main/openapi/nginx-stream-keyvals-api-openapi.yml

SDKs

📦
GitHubRepository
https://github.com/nginx/njs

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/nginx/refs/heads/main/json-ld/nginx-plus-http-api-context.jsonld
🔗
SDKs
https://github.com/nginx/nginx-plus-go-client
🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/nginx/refs/heads/main/json-ld/nginx-context.jsonld

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/nginx-stream-keyvals-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

nginx-stream-keyvals-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  version: '9.0'
  title: NGINX Plus REST Stream Keyvals API
  description: NGINX Plus REST [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) provides access to NGINX Plus status information, on-the-fly configuration of upstream servers and key-value pairs management for [http](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) and [stream](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html).
servers:
- url: /api/9
tags:
- name: Stream Keyvals
paths:
  /stream/keyvals/:
    get:
      tags:
      - Stream Keyvals
      summary: NGINX Return Key-Value Pairs from All Stream Keyval Zones
      description: Returns key-value pairs for each stream keyval shared memory [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone).
      operationId: getStreamKeyvalZones
      parameters:
      - name: fields
        in: query
        description: If the “<literal>fields</literal>” value is empty, then only stream keyval zone names will be output.
        x-example: ''
        schema:
          type: string
      responses:
        '200':
          description: Success
          x-microcks-refs:
          - name: getStreamKeyvalZones200Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxStreamKeyvalZonesMap'
              example:
                keyval_zone:
                  key1: value1
                  key2: value2
                  key3: value3
                one:
                  arg1: value1
                  arg2: value2
                  arg3: value3
        '404':
          description: Unknown version (*UnknownVersion*)
          x-microcks-refs:
          - name: getStreamKeyvalZones404Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /stream/keyvals/{streamKeyvalZoneName}:
    parameters:
    - name: streamKeyvalZoneName
      in: path
      description: The name of a stream keyval shared memory zone.
      required: true
      x-example: example_streamKeyvalZoneName
      schema:
        type: string
    get:
      tags:
      - Stream Keyvals
      summary: NGINX Return Key-Value Pairs from a Stream Keyval Zone
      description: Returns key-value pairs stored in a particular stream keyval shared memory [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone).
      operationId: getStreamKeyvalZoneKeysValues
      parameters:
      - name: key
        in: query
        description: Get a particular key-value pair from the stream keyval zone.
        x-example: ''
        schema:
          type: string
      responses:
        '200':
          description: Success
          x-microcks-refs:
          - name: getStreamKeyvalZoneKeysValues200Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxStreamKeyvalZone'
              example:
                key1: value1
                key2: value2
                key3: value3
        '404':
          description: 'Keyval not found (*KeyvalNotFound*),

            keyval key not found (*KeyvalKeyNotFound*),

            unknown version (*UnknownVersion*)

            '
          x-microcks-refs:
          - name: getStreamKeyvalZoneKeysValues404Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Stream Keyvals
      summary: NGINX Add a Key-Value Pair to the Stream Keyval Zone
      description: Adds a new key-value pair to the stream keyval shared memory [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). Several key-value pairs can be entered if the stream keyval shared memory zone is empty.
      operationId: postStreamKeyvalZoneData
      responses:
        '201':
          description: Created
        '400':
          description: 'Invalid JSON (*KeyvalFormatError*),

            invalid key format (*KeyvalFormatError*),

            key required (*KeyvalFormatError*),

            keyval timeout is not enabled (*KeyvalFormatError*),

            only one key can be added (*KeyvalFormatError*),

            reading request body failed *BodyReadError*)

            '
          x-microcks-refs:
          - name: postStreamKeyvalZoneData400Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '404':
          description: 'Keyval not found (*KeyvalNotFound*),

            unknown version (*UnknownVersion*)

            '
          x-microcks-refs:
          - name: postStreamKeyvalZoneData404Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '405':
          description: Method disabled (*MethodDisabled*)
          x-microcks-refs:
          - name: postStreamKeyvalZoneData405Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '409':
          description: 'Entry exists (*EntryExists*),

            key already exists (*KeyvalKeyExists*)

            '
          x-microcks-refs:
          - name: postStreamKeyvalZoneData409Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '413':
          description: Request Entity Too Large
          x-microcks-refs:
          - name: postStreamKeyvalZoneData413Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '415':
          description: JSON error (*JsonError*)
          x-microcks-refs:
          - name: postStreamKeyvalZoneData415Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NginxStreamKeyvalZonePostPatch'
        description: A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the stream keyval shared memory zone is empty. Expiration time in milliseconds can be specified for a key-value pair with the *expire* parameter which overrides the [*timeout*](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout) parameter of the <a href="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</a> directive.
        required: true
    patch:
      tags:
      - Stream Keyvals
      summary: NGINX Modify a Key-Value or Delete a Key
      description: Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time is specified in milliseconds with the *expire* parameter which overrides the [*timeout*](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout) parameter of the <a href="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</a> directive.
      operationId: patchStreamKeyvalZoneKeyValue
      responses:
        '204':
          description: Success
        '400':
          description: 'Invalid JSON (*KeyvalFormatError*),

            key required (*KeyvalFormatError*),

            keyval timeout is not enabled (*KeyvalFormatError*),

            only one key can be updated (*KeyvalFormatError*),

            reading request body failed *BodyReadError*)

            '
          x-microcks-refs:
          - name: patchStreamKeyvalZoneKeyValue400Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '404':
          description: 'Keyval not found (*KeyvalNotFound*),

            keyval key not found (*KeyvalKeyNotFound*),

            unknown version (*UnknownVersion*)

            '
          x-microcks-refs:
          - name: patchStreamKeyvalZoneKeyValue404Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '405':
          description: Method disabled (*MethodDisabled*)
          x-microcks-refs:
          - name: patchStreamKeyvalZoneKeyValue405Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '413':
          description: Request Entity Too Large
          x-microcks-refs:
          - name: patchStreamKeyvalZoneKeyValue413Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '415':
          description: JSON error (*JsonError*)
          x-microcks-refs:
          - name: patchStreamKeyvalZoneKeyValue415Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NginxStreamKeyvalZonePostPatch'
        description: A new value for the key is specified in the JSON format.
        required: true
    delete:
      tags:
      - Stream Keyvals
      summary: NGINX Empty the Stream Keyval Zone
      description: Deletes all key-value pairs from the stream keyval shared memory [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). If <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> of keyval zones in a cluster is enabled, empties the keyval zone only on a target cluster node.
      operationId: deleteStreamKeyvalZoneData
      responses:
        '204':
          description: Success
        '404':
          description: 'Keyval not found (*KeyvalNotFound*),

            unknown version (*UnknownVersion*)

            '
          x-microcks-refs:
          - name: deleteStreamKeyvalZoneData404Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
        '405':
          description: Method disabled (*MethodDisabled*)
          x-microcks-refs:
          - name: deleteStreamKeyvalZoneData405Example
            x-microcks-default: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NginxError'
              example:
                error: {}
                request_id: example-request_id
                href: example-href
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    NginxStreamKeyvalZone:
      title: Stream Keyval Shared Memory Zone
      description: 'Contents of a stream keyval shared memory zone when using the GET method.

        '
      type: object
      example:
        key1: value1
        key2: value2
        key3: value3
    NginxStreamKeyvalZonePostPatch:
      title: Stream Keyval Shared Memory Zone
      description: 'Contents of a stream keyval shared memory zone

        when using the POST or PATCH methods.

        '
      type: object
      example:
        key1: value1
        key2: value2
        key3:
          value: value3
          expire: 30000
    NginxStreamKeyvalZonesMap:
      title: Stream Keyval Shared Memory Zones
      description: 'Contents of all stream keyval shared memory zones.

        '
      type: object
      additionalProperties:
        $ref: '#/components/schemas/NginxStreamKeyvalZone'
      example:
        keyval_zone:
          key1: value1
          key2: value2
          key3: value3
        one:
          arg1: value1
          arg2: value2
          arg3: value3
    NginxError:
      title: Error
      description: 'nginx error object.

        '
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: integer
              description: HTTP error code.
              example: 200
            text:
              type: string
              description: Error description.
              example: example-text
            code:
              type: string
              description: Internal nginx error code.
              example: 200
          example: {}
        request_id:
          type: string
          description: The ID of the request, equals the value of the <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_id">$request_id</a> variable.
          example: example-request_id
        href:
          type: string
          description: Link to reference documentation.
          example: example-href