Citrix ADC (NetScaler) NITRO API

openapi: 3.1.0
info:
  title: Citrix NetScaler NITRO REST API
  description: >-
    The NITRO (NetScaler Interface Through RESTful Operations) API provides
    programmatic access to configure, monitor, and manage Citrix NetScaler
    (ADC) appliances. Built on REST architecture using HTTP/HTTPS, the API
    supports comprehensive management of application delivery controller
    features including load balancing virtual servers, content switching
    virtual servers, system configuration, and appliance-level settings.
    All NITRO operations are logged to /var/nitro.log on the appliance.
  version: '14.1'
  contact:
    name: NetScaler Support
    url: https://support.citrix.com/
  license:
    name: Proprietary
    url: https://www.cloud.com/legal
  termsOfService: https://www.cloud.com/legal
externalDocs:
  description: Citrix ADC NITRO API Reference Documentation
  url: https://developer-docs.netscaler.com/en-us/adc-nitro-api/current-release.html
servers:
- url: https://{nsip}/nitro/v1
  description: NetScaler NITRO API endpoint
  variables:
    nsip:
      default: netscaler.example.com
      description: >-
        The IP address or hostname of the NetScaler appliance (NSIP).
tags:
- name: Authentication
  description: >-
    Session-based authentication for the NITRO API. Obtain an
    authentication token via login, then include it as a cookie in
    subsequent requests.
- name: CS Virtual Server
  description: >-
    Content switching virtual servers direct client requests to different
    load balancing virtual servers based on content switching policies
    that evaluate HTTP request attributes.
- name: LB Virtual Server
  description: >-
    Load balancing virtual servers accept incoming traffic and distribute
    it across backend services using configurable load balancing methods
    such as round robin, least connections, and more.
- name: NS Config
  description: >-
    NetScaler appliance configuration including IP address, network
    settings, HTTP ports, and system-level parameters. Supports save,
    clear, and diff operations.
- name: Statistics
  description: >-
    Real-time performance and health statistics for configured resources
    including virtual servers, services, and system metrics.
- name: System
  description: >-
    System-level resources for managing the NetScaler appliance including
    system information, files, users, groups, and global settings.
security:
- nitroAuthToken: []
- nitroBasicAuth: []
paths:
  /config/login:
    post:
      operationId: login
      summary: Citrix Netscaler Log in to the Netscaler Appliance
      description: >-
        Authenticates the user and returns a session token (NITRO_AUTH_TOKEN)
        as a cookie. This token must be included in subsequent API requests.
        The default session timeout is 30 minutes, or a user-configured
        value when restricted timeout is enabled (default 15 minutes).
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - login
              properties:
                login:
                  type: object
                  required:
                  - username
                  - password
                  properties:
                    username:
                      type: string
                      description: The administrator username.
                      examples:
                      - nsroot
                    password:
                      type: string
                      description: The administrator password.
                      format: password
            example:
              login:
                username: nsroot
                password: nsroot
      responses:
        '201':
          description: Login successful. Session token returned as a Set-Cookie header.
          headers:
            Set-Cookie:
              description: >-
                NITRO_AUTH_TOKEN cookie for authenticating subsequent
                requests.
              schema:
                type: string
                examples:
                - NITRO_AUTH_TOKEN=abc123xyz; path=/nitro/v1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'
              examples:
                Login201Example:
                  summary: Default login 201 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
        '401':
          description: Authentication failed due to invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroErrorResponse'

              examples:
                Login401Example:
                  summary: Default login 401 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: ERROR
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /config/logout:
    post:
      operationId: logout
      summary: Citrix Netscaler Log Out From the Netscaler Appliance
      description: >-
        Terminates the current session and invalidates the
        NITRO_AUTH_TOKEN cookie.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - logout
              properties:
                logout:
                  type: object
            example:
              logout: {}
      responses:
        '201':
          description: Logout successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'

              examples:
                Logout201Example:
                  summary: Default logout 201 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /config/nsconfig:
    get:
      operationId: getNsConfig
      summary: Citrix Netscaler Get Netscaler Configuration
      description: >-
        Retrieves the current NetScaler appliance configuration including
        IP address, network settings, HTTP ports, and system parameters.
      tags:
      - NS Config
      parameters:
      - $ref: '#/components/parameters/Attrs'
      responses:
        '200':
          description: Successful retrieval of NS configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  nsconfig:
                    $ref: '#/components/schemas/NsConfig'
              examples:
                Getnsconfig200Example:
                  summary: Default getNsConfig 200 response
                  x-microcks-default: true
                  value:
                    nsconfig:
                      ipaddress: example_value
                      netmask: example_value
                      nsvlan: 10
                      ifnum: example_value
                      tagged: 'YES'
                      httpport:
                      - 10
                      maxconn: 10
                      maxreq: 10
                      cip: ENABLED
                      cipheader: example_value
                      cookieversion: '0'
                      securecookie: ENABLED
                      pmtumin: 10
                      pmtutimeout: 10
                      ftpportrange: example_value
                      timezone: example_value
                      grantquotamaxclient: 10
                      grantquotaspillover: 10
                      crportrange: example_value
                      systemtype: Stand-alone
                      primaryip: example_value
                      primaryip6: example_value
                      flags: 10
                      lastconfigchangedtime: example_value
                      lastconfigsavetime: example_value
                      currentsytemtime: example_value
                      systemtime: 10
                      configchanged: true
                      mappedip: example_value
                      range: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateNsConfig
      summary: Citrix Netscaler Update Netscaler Configuration
      description: >-
        Modifies NetScaler appliance configuration parameters such as
        IP address, network settings, and system-level options.
      tags:
      - NS Config
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - nsconfig
              properties:
                nsconfig:
                  $ref: '#/components/schemas/NsConfig'
            examples:
              UpdatensconfigRequestExample:
                summary: Default updateNsConfig request
                x-microcks-default: true
                value:
                  nsconfig:
                    ipaddress: example_value
                    netmask: example_value
                    nsvlan: 10
                    ifnum: example_value
                    tagged: 'YES'
                    httpport:
                    - 10
                    maxconn: 10
                    maxreq: 10
                    cip: ENABLED
                    cipheader: example_value
                    cookieversion: '0'
                    securecookie: ENABLED
                    pmtumin: 10
                    pmtutimeout: 10
                    ftpportrange: example_value
                    timezone: example_value
                    grantquotamaxclient: 10
                    grantquotaspillover: 10
                    crportrange: example_value
                    systemtype: Stand-alone
                    primaryip: example_value
                    primaryip6: example_value
                    flags: 10
                    lastconfigchangedtime: example_value
                    lastconfigsavetime: example_value
                    currentsytemtime: example_value
                    systemtime: 10
                    configchanged: true
                    mappedip: example_value
                    range: 10
      responses:
        '200':
          description: Configuration updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'
              examples:
                Updatensconfig200Example:
                  summary: Default updateNsConfig 200 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
        '401':
          $ref: '#/components/responses/Unauthorized'
        '400':
          $ref: '#/components/responses/BadRequest'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /config/nsconfig?action=save:
    post:
      operationId: saveNsConfig
      summary: Citrix Netscaler Save Netscaler Configuration
      description: >-
        Saves the running configuration to the appliance persistent
        storage (ns.conf). This ensures configuration changes persist
        across reboots.
      tags:
      - NS Config
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - nsconfig
              properties:
                nsconfig:
                  type: object
            example:
              nsconfig: {}
      responses:
        '200':
          description: Configuration saved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'
              examples:
                Savensconfig200Example:
                  summary: Default saveNsConfig 200 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
        '401':
          $ref: '#/components/responses/Unauthorized'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /config/nsconfig?action=clear:
    post:
      operationId: clearNsConfig
      summary: Citrix Netscaler Clear Netscaler Configuration
      description: >-
        Clears the NetScaler configuration. The level parameter controls
        what is cleared - basic, extended, or full.
      tags:
      - NS Config
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - nsconfig
              properties:
                nsconfig:
                  type: object
                  required:
                  - level
                  properties:
                    level:
                      type: string
                      description: >-
                        Level of configuration to clear.
                      enum:
                      - basic
                      - extended
                      - full
            examples:
              ClearnsconfigRequestExample:
                summary: Default clearNsConfig request
                x-microcks-default: true
                value:
                  nsconfig:
                    level: basic
      responses:
        '200':
          description: Configuration cleared successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'
              examples:
                Clearnsconfig200Example:
                  summary: Default clearNsConfig 200 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
        '401':
          $ref: '#/components/responses/Unauthorized'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /config/systemfile:
    get:
      operationId: listSystemFiles
      summary: Citrix Netscaler List System Files
      description: >-
        Retrieves system files from a specified location on the NetScaler
        appliance.
      tags:
      - System
      parameters:
      - name: args
        in: query
        description: >-
          File location argument in the format
          filelocation:%2Fnsconfig%2Fssl (URL-encoded path).
        required: true
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successful retrieval of system files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  systemfile:
                    type: array
                    items:
                      $ref: '#/components/schemas/SystemFile'
              examples:
                Listsystemfiles200Example:
                  summary: Default listSystemFiles 200 response
                  x-microcks-default: true
                  value:
                    systemfile:
                    - filename: example_value
                      filelocation: example_value
                      filecontent: example_value
                      fileencoding: BASE64
                      fileaccesstime: example_value
                      filemodifiedtime: example_value
                      filemode: example_value
                      filesize: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: uploadSystemFile
      summary: Citrix Netscaler Upload a System File
      description: >-
        Uploads a file to the NetScaler appliance. The file content must
        be Base64-encoded.
      tags:
      - System
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - systemfile
              properties:
                systemfile:
                  $ref: '#/components/schemas/SystemFile'
            example:
              systemfile:
                filename: cert1.crt
                filelocation: /nsconfig/ssl
                filecontent: BASE64_ENCODED_CONTENT
                fileencoding: BASE64
      responses:
        '201':
          description: File uploaded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'
              examples:
                Uploadsystemfile201Example:
                  summary: Default uploadSystemFile 201 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
        '401':
          $ref: '#/components/responses/Unauthorized'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /config/systemfile/{filename}:
    delete:
      operationId: deleteSystemFile
      summary: Citrix Netscaler Delete a System File
      description: >-
        Deletes a file from the NetScaler appliance at the specified
        location.
      tags:
      - System
      parameters:
      - name: filename
        in: path
        required: true
        description: The name of the file to delete.
        schema:
          type: string
        example: example_value
      - name: args
        in: query
        required: true
        description: >-
          File location argument in the format
          filelocation:%2Fnsconfig%2Fssl (URL-encoded path).
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: File deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'
              examples:
                Deletesystemfile200Example:
                  summary: Default deleteSystemFile 200 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: File not found.

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /config/lbvserver:
    get:
      operationId: listLbVservers
      summary: Citrix Netscaler List Load Balancing Virtual Servers
      description: >-
        Retrieves all load balancing virtual server configurations. Supports
        filtering, pagination, attribute selection, and summary/detail views.
      tags:
      - LB Virtual Server
      parameters:
      - $ref: '#/components/parameters/Attrs'
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/View'
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageNo'
      responses:
        '200':
          description: Successful retrieval of load balancing virtual servers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  lbvserver:
                    type: array
                    items:
                      $ref: '#/components/schemas/LbVserver'
              examples:
                Listlbvservers200Example:
                  summary: Default listLbVservers 200 response
                  x-microcks-default: true
                  value:
                    lbvserver:
                    - name: Example Title
                      servicetype: HTTP
                      ipv46: example_value
                      port: 10
                      ipset: example_value
                      range: 10
                      ippattern: example_value
                      ipmask: example_value
                      td: 10
                      lbmethod: ROUNDROBIN
                      hashlength: 10
                      netmask: example_value
                      v6netmasklen: 10
                      backuplbmethod: ROUNDROBIN
                      persistencetype: SOURCEIP
                      persistmask: example_value
                      v6persistmasklen: 10
                      persistencebackup: SOURCEIP
                      timeout: 10
                      persistavpno:
                      - {}
                      cookiename: example_value
                      rule: example_value
                      listenpolicy: example_value
                      listenpriority: 10
                      resrule: example_value
                      push: ENABLED
                      pushlabel: example_value
                      pushmulticlients: 'YES'
                      comment: example_value
                      clttimeout: 10
                      somethod: CONNECTION
                      sopersistence: ENABLED
                      sopersistencetimeout: 10
                      sothreshold: 10
                      healththreshold: 10
                      redirecturl: https://www.example.com
                      downstateflush: ENABLED
                      disableprimaryondown: ENABLED
                      insertvserveripport: 'OFF'
                      vipheader: example_value
                      authenticationhost: example_value
                      authentication: 'ON'
                      authn401: 'ON'
                      authnvsname: example_value
                      icmpvsrresponse: PASSIVE
                      rhistate: PASSIVE
                      newservicerequest: 10
                      newservicerequestunit: PER_SECOND
                      newservicerequestincrementinterval: 10
                      minautoscalemembers: 10
                      maxautoscalemembers: 10
                      skippersistency: Bypass
                      appflowlog: ENABLED
                      state: ENABLED
                      connfailover: DISABLED
                      redirurl: https://www.example.com
                      curstate: UP
                      effectivestate: UP
                      status: 10
                      lbrrreason: 10
                      totalservices: 10
                      activeservices: 10
                      statechangetimesec: example_value
                      tickssincelaststatechange: 10
                      health: 10
                      isgslb: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createLbVserver
      summary: Citrix Netscaler Create a Load Balancing Virtual Server
      description: >-
        Creates a new load balancing virtual server with the specified
        configuration. The name and servicetype properties are required.
        Supports bulk creation by passing an array.
      tags:
      - LB Virtual Server
      parameters:
      - $ref: '#/components/parameters/BulkErrorHandling'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - lbvserver
              properties:
                lbvserver:
                  oneOf:
                  - $ref: '#/components/schemas/LbVserver'
                  - type: array
                    items:
                      $ref: '#/components/schemas/LbVserver'
            example:
              lbvserver:
                name: MyFirstLbVServer
                servicetype: HTTP
                ipv46: 10.102.29.88
                port: 80
                lbmethod: ROUNDROBIN
      responses:
        '201':
          description: Load balancing virtual server created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'
              examples:
                Createlbvserver201Example:
                  summary: Default createLbVserver 201 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
        '207':
          description: >-
            Multi-status response for bulk operations where some items
            may have succeeded and others failed.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: >-
            Resource already exists. A virtual server with the specified
            name is already configured.

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /config/lbvserver/{name}:
    get:
      operationId: getLbVserver
      summary: Citrix Netscaler Get a Specific Load Balancing Virtual Server
      description: >-
        Retrieves the configuration of a specific load balancing virtual
        server identified by name.
      tags:
      - LB Virtual Server
      parameters:
      - name: name
        in: path
        required: true
        description: >-
          Name of the load balancing virtual server.
        schema:
          type: string
          minLength: 1
        example: Example Title
      - $ref: '#/components/parameters/Attrs'
      responses:
        '200':
          description: Successful retrieval of the virtual server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  lbvserver:
                    type: array
                    items:
                      $ref: '#/components/schemas/LbVserver'
                    minItems: 1
                    maxItems: 1
              examples:
                Getlbvserver200Example:
                  summary: Default getLbVserver 200 response
                  x-microcks-default: true
                  value:
                    lbvserver:
                    - name: Example Title
                      servicetype: HTTP
                      ipv46: example_value
                      port: 10
                      ipset: example_value
                      range: 10
                      ippattern: example_value
                      ipmask: example_value
                      td: 10
                      lbmethod: ROUNDROBIN
                      hashlength: 10
                      netmask: example_value
                      v6netmasklen: 10
                      backuplbmethod: ROUNDROBIN
                      persistencetype: SOURCEIP
                      persistmask: example_value
                      v6persistmasklen: 10
                      persistencebackup: SOURCEIP
                      timeout: 10
                      persistavpno:
                      - {}
                      cookiename: example_value
                      rule: example_value
                      listenpolicy: example_value
                      listenpriority: 10
                      resrule: example_value
                      push: ENABLED
                      pushlabel: example_value
                      pushmulticlients: 'YES'
                      comment: example_value
                      clttimeout: 10
                      somethod: CONNECTION
                      sopersistence: ENABLED
                      sopersistencetimeout: 10
                      sothreshold: 10
                      healththreshold: 10
                      redirecturl: https://www.example.com
                      downstateflush: ENABLED
                      disableprimaryondown: ENABLED
                      insertvserveripport: 'OFF'
                      vipheader: example_value
                      authenticationhost: example_value
                      authentication: 'ON'
                      authn401: 'ON'
                      authnvsname: example_value
                      icmpvsrresponse: PASSIVE
                      rhistate: PASSIVE
                      newservicerequest: 10
                      newservicerequestunit: PER_SECOND
                      newservicerequestincrementinterval: 10
                      minautoscalemembers: 10
                      maxautoscalemembers: 10
                      skippersistency: Bypass
                      appflowlog: ENABLED
                      state: ENABLED
                      connfailover: DISABLED
                      redirurl: https://www.example.com
                      curstate: UP
                      effectivestate: UP
                      status: 10
                      lbrrreason: 10
                      totalservices: 10
                      activeservices: 10
                      statechangetimesec: example_value
                      tickssincelaststatechange: 10
                      health: 10
                      isgslb: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Virtual server not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateLbVserver
      summary: Citrix Netscaler Update a Load Balancing Virtual Server
      description: >-
        Updates the configuration of an existing load balancing virtual
        server. Retrieve the current state, modify properties locally,
        and upload the complete updated state.
      tags:
      - LB Virtual Server
      parameters:
      - name: name
        in: path
        required: true
        description: >-
          Name of the load balancing virtual server to update.
        schema:
          type: string
          minLength: 1
        example: Example Title
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - lbvserver
              properties:
                lbvserver:
                  $ref: '#/components/schemas/LbVserver'
            example:
              lbvserver:
                name: MyFirstLbVServer
                lbmethod: LEASTCONNECTION
                comment: Updated via NITRO API
      responses:
        '200':
          description: Virtual server updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NitroResponse'
              examples:
                Updatelbvserver200Example:
                  summary: Default updateLbVserver 200 response
                  x-microcks-default: true
                  value:
                    errorcode: 10
                    message: example_value
                    severity: NONE
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Virtual server not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteLbVserver
      summary: Citrix Netscaler Delete a Load Balancing Virtual Server
      description: >-
        Deletes a load balancing virtual server identified by name.
      tags:
      - LB Virtual Server
      parameters:
      - name: name
        in: path
        required: true
        description: >-
          Name of the load balancing virtual server to delete.
        schema:
          type: string
          minLength: 1
        example: Example Title
      responses:
        '200':
          description: Virtual server deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/

# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/citrix-netscaler/refs/heads/main/openapi/citrix-netscaler-nitro-openapi.yml