NGINX njs Scripting API

openapi: 3.0.3
info:
  title: NGINX njs Scripting API
  version: "0.8"
  description: >-
    The NGINX njs module provides a JavaScript runtime embedded inside NGINX.
    It does not expose HTTP endpoints itself. Instead, it offers scripting
    objects (HTTP request, stream session, Fetch API, etc.) that are available
    within njs handler functions configured in the NGINX configuration file.
    This specification documents the key njs objects as OpenAPI schemas only;
    the paths object is intentionally empty because there are no REST
    endpoints to describe.
  x-generated-from: documentation
  contact:
    name: NGINX
    url: https://nginx.org/en/docs/njs/reference.html
  license:
    name: BSD-2-Clause
    url: https://nginx.org/LICENSE

externalDocs:
  description: NGINX njs Reference
  url: https://nginx.org/en/docs/njs/reference.html

paths: {}

components:
  schemas:

    HttpRequest:
      type: object
      description: >-
        The HTTP request object (r) available in ngx_http_js_module handlers.
        Provides access to client request data and methods to produce a response.
      properties:
        args:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: array
              items:
                type: string
          readOnly: true
          description: Request arguments object parsed from the query string. Duplicate keys are returned as arrays.
          example: {}
        headersIn:
          type: object
          additionalProperties:
            type: string
          readOnly: true
          description: Incoming request headers object.
          example: {}
        headersOut:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Outgoing response headers object (writable before headers are sent).
          example: {}
        httpVersion:
          type: string
          readOnly: true
          description: HTTP version of the request.
          example: '1.1'
        internal:
          type: boolean
          readOnly: true
          description: True if the request is to an internal location.
          example: false
        method:
          type: string
          readOnly: true
          description: HTTP method (GET, POST, etc.).
          example: GET
        remoteAddress:
          type: string
          readOnly: true
          description: Client IP address.
          example: 192.168.1.100
        requestBuffer:
          type: string
          format: binary
          readOnly: true
          description: Client request body as a Buffer (since 0.5.0).
          example: AQID
        requestText:
          type: string
          readOnly: true
          description: Client request body as a string.
          example: '{"action":"process"}'
        responseBuffer:
          type: string
          format: binary
          readOnly: true
          description: Subrequest response body as a Buffer.
          example: AQID
        responseText:
          type: string
          readOnly: true
          description: Subrequest response body as a string.
          example: '{"result":"success"}'
        rawHeadersIn:
          type: array
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
          readOnly: true
          description: Raw incoming headers as an array of [name, value] pairs.
          example: []
        rawHeadersOut:
          type: array
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
          readOnly: true
          description: Raw outgoing headers as an array of [name, value] pairs.
          example: []
        status:
          type: integer
          description: HTTP response status code (writable).
          example: 200
        uri:
          type: string
          readOnly: true
          description: Current URI of the request.
          example: /api/v1/resource
        variables:
          type: object
          additionalProperties:
            type: string
          description: NGINX variables object (writable for variables declared in config).
          example: {}
        rawVariables:
          type: object
          additionalProperties:
            type: string
            format: binary
          description: NGINX variables as Buffers (writable, since 0.5.0).
          example: {}
        parent:
          description: Reference to the parent request object (for subrequests).
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/HttpRequest'

    StreamSession:
      type: object
      description: >-
        The stream session object (s) available in ngx_stream_js_module handlers.
        Provides access to the TCP/UDP session and methods to control data flow.
      properties:
        remoteAddress:
          type: string
          readOnly: true
          description: Client IP address.
          example: 192.168.1.100
        status:
          type: integer
          readOnly: true
          description: Session status code (alias to $status variable, since 0.5.2).
          example: 200
        variables:
          type: object
          additionalProperties:
            type: string
          description: NGINX variables object (writable, since 0.2.8).
          example: {}
        rawVariables:
          type: object
          additionalProperties:
            type: string
            format: binary
          description: NGINX variables as Buffers (writable, since 0.5.0).

          example: {}
    PeriodicSession:
      type: object
      description: >-
        Object provided as the first argument to js_periodic handlers
        for both http and stream (since 0.8.1).
      properties:
        variables:
          type: object
          additionalProperties:
            type: string
          description: NGINX variables object (writable).
          example: {}
        rawVariables:
          type: object
          additionalProperties:
            type: string
            format: binary
          description: NGINX variables as Buffers (writable).

          example: {}
    Headers:
      type: object
      description: >-
        The Headers interface of the Fetch API (since 0.5.1).
        Represents HTTP headers and provides methods to manipulate them.
      properties:
        # Headers is primarily accessed via methods (get, set, append, delete, has, forEach, getAll).
        # Modeled here as a generic map for schema purposes.
      additionalProperties:
        type: string

    Request:
      type: object
      description: >-
        The Request interface of the Fetch API (since 0.7.10).
        Used to construct requests for ngx.fetch().
      properties:
        url:
          type: string
          readOnly: true
          description: The URL of the request.
          example: http://upstream.example.com/api
        method:
          type: string
          description: The HTTP method (default GET).
          example: GET
        headers:
          $ref: '#/components/schemas/Headers'
        body:
          type: string
          description: The request body (default empty).
          example: '{"key":"value"}'
        bodyUsed:
          type: boolean
          readOnly: true
          description: True if the body has already been consumed.
          example: false
        cache:
          type: string
          readOnly: true
          description: Cache mode of the request.
          example: no-cache
        credentials:
          type: string
          readOnly: true
          description: Credentials mode (default same-origin).
          example: same-origin
        mode:
          type: string
          readOnly: true
          description: Mode of the request.

          example: cors
    Response:
      type: object
      description: >-
        The Response interface of the Fetch API (since 0.5.1).
        Returned by ngx.fetch() as a resolved Promise.
      properties:
        ok:
          type: boolean
          readOnly: true
          description: True if the response status is 200-299.
          example: true
        redirected:
          type: boolean
          readOnly: true
          description: True if the response is the result of a redirect.
          example: false
        status:
          type: integer
          readOnly: true
          description: HTTP status code of the response.
          example: 200
        statusText:
          type: string
          readOnly: true
          description: Status message corresponding to the status code.
          example: OK
        headers:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/Headers'
        bodyUsed:
          type: boolean
          readOnly: true
          description: True if the body has already been read.
          example: false
        type:
          type: string
          readOnly: true
          description: Type of the response.
          example: string
        url:
          type: string
          readOnly: true
          description: URL of the response.

          example: http://upstream.example.com/api
    Ngx:
      type: object
      description: >-
        The ngx global object (since 0.5.0). Provides NGINX runtime
        information and the fetch() method.
      properties:
        build:
          type: string
          readOnly: true
          description: Optional NGINX build name (since 0.8.0).
          example: nginx-plus-r32
        conf_file_path:
          type: string
          readOnly: true
          description: File path to the current NGINX configuration file (since 0.8.0).
          example: /etc/nginx/nginx.conf
        conf_prefix:
          type: string
          readOnly: true
          description: NGINX configuration prefix directory (since 0.7.8).
          example: /etc/nginx/
        error_log_path:
          type: string
          readOnly: true
          description: File path to the current error log file (since 0.8.0).
          example: /var/log/nginx/error.log
        prefix:
          type: string
          readOnly: true
          description: NGINX installation prefix.
          example: /usr/local/nginx
        version:
          type: string
          readOnly: true
          description: NGINX version string.
          example: 1.25.3
        version_number:
          type: integer
          readOnly: true
          description: NGINX version as a number.
          example: 1025003
        worker_id:
          type: integer
          readOnly: true
          description: Current worker process ID.

          example: 0
    NgxShared:
      type: object
      description: >-
        The ngx.shared object provides access to shared memory zones
        declared with js_shared_dict_zone.
      additionalProperties:
        $ref: '#/components/schemas/SharedDict'

    SharedDict:
      type: object
      description: >-
        A shared dictionary zone that can be used to share data
        between worker processes.
      properties:
        name:
          type: string
          readOnly: true
          description: Name of the shared dictionary zone.
          example: my_shared_zone
        type:
          type: string
          readOnly: true
          description: Type of the shared dictionary (string or number).
          example: string