Introduction

Last published : Sep 09, 2026
NetScaler Next-Gen API is a powerful modern RESTful API that allows you to programmatically configure NetScaler in a simple and intuitive way. It is based on a declarative, desired state and application-centric interface, and aims to abstract away and simplify many of the low-level complexity of traditional NetScaler configurations, making it more suitable to application developers even those who are not networking or ADC experts.
The core concept in the Next-Gen API is the application. All the configuration elements pertaining to the same application are grouped together, making it easy and safe to apply changes atomically.
To illustrate the new API, let's start with a simple configuration use case of creating a NetScaler load-balancing configuration with a VIP and a couple of backend servers
POST /mgmt/api/nextgen/v1/applications

{
  "application": {
    "name": "app1",
    "virtual_ip": "70.122.23.11",
    "default_certificate_ref": "app1_cert",
    "servers": [
      "192.168.10.11",
      "192.168.10.14"
    ]
  }
}
With this one API call, we have fully configured this load-balancing use case. We'll cover how we got a certificate reference later in the document.
Let's say we want to update the configuration to add more servers or make other changes. We can simply issue another API call to add more servers as follows:
PUT /mgmt/api/nextgen/v1/applications/app1

{
  "application": {
    "name": "app1",
    "virtual_ip": "70.122.23.11",
    "default_certificate_ref": "app1_cert",
    "servers": [
      "192.168.10.11",
      "192.168.10.14",
      "192.168.10.15",
      "192.168.10.16"
    ]
  }
}
Notice that we have provided the new "desired state" of the application in the update API, which now contains 4 servers rather than 2.
Subsequent sections of this documentation cover advanced use case scenarios, which includes content switching, configurations involving multiple VIP addresses, and diverse port setups.

Comparison to Nitro API

While the NetScaler traditional Nitro API has been very successful in providing a REST API for interfacing programmatically with NetScaler and unlocking all its features, it ultimately is an API that mirrors the internal NetScaler processing constructs, the NetScaler CLI structure, and reflects the low-level complexity and idiosyncrasies of the NetScaler configuration model making its usage intimidating to many new users.
The Next-Gen API takes a new approach of a user-centric design, starting from the common use cases and patterns that customers often try to realize on NetScaler, and making these use cases explicit and very simple to create. It also aims to be developer-friendly by adopting consistency in behavior and conventions, a logical structure, with modern desired state semantics.
Using the Nitro API, the simple load-balancing configuration shown above, would require 6 API calls, and assumes acquaintance with concepts and APIs for creating vservers, servicegroups, services and bindings between these entities. Slightly more complex use cases can require tens of API calls, with the user or the calling application responsible for understanding the proper order of calling these APIs and handling any mid-workflow errors.
The other difference with the Nitro API has to do with the processing infrastructure. The Next-Gen API uses a new modern config infrastructure on NetScaler that segregates the config validation and commit stage from applying the config to the data plane. What this means for users is faster API processing. The config is considered "committed" once it's validated and stored on a persistent DB. In the background and asynchronously, the Next-Gen config infrastructure will translate and apply the latest config changes from the DB to the NetScaler data plane (packet engines).

Configuration Views

Both the Next-Gen API and Nitro API are supported on NetScaler, and configurations can be created using both. Configurations created with Next-Gen API can only be modified using Next-Gen API. However, these configurations can be viewed in read-only mode through the CLI or Nitro API. To switch to the Next-Gen API config view, use the following CLI command:
switch ns configview NEXTGENAPI
In this view, you can only see configurations created through Next-Gen API. By default, the config view is set to ALL, which provides a read-only view of Next-Gen API configurations along with an unrestricted view of configurations created using NetScaler CLI, GUI, or Nitro API. Additionally, there is the CLASSIC config view, where you can view and modify configurations created using the NetScaler CLI, GUI, or Nitro API.
Note:
Configview is a session-level setting that applies only to the current user session (CLI or Nitro session) and does not affect all users globally.
Configuration created through Next-Gen API is not saved in ns.conf when you run the save ns config command. Next-Gen API configuration is persistent and remains intact after a reboot.
The following behavior is observed for different levels of the clear ns config <level> command:
Level Description
basic Configuration created through Next-Gen API is not cleared.
extended Configuration created through Next-Gen API is not cleared.
full Configuration created through Next-Gen API is cleared.
To delete all Next-Gen API resources at once, use the following CLI command:
clear ns nextgenapi
To delete individual resources like applications or certificates, use the respective Next-Gen DELETE APIs.

System Requirements

Next-Gen API is available on NetScaler release 14.1 12.30.
If you are using NetScaler VPX, please ensure you have at least 4GB RAM.
Note:
Currently, NetScaler standalone and HA deployment is supported on MPX and VPX. Cluster is not yet supported.

Enabling Next-Gen API on NetScaler

Before using Next-Gen API, you need to enable it first on NetScaler using the CLI:
> enable ns nextgenapi

ERROR: Operation not permitted [To use nextgenapi you need to enable SSL defaultprofile. CLI CMD: set ssl parameter -defaultProfile ENABLED]
This will fail if you don't already have defaultProfile enabled for SSL as Next-Gen API requires this. Once you configure the default profile for SSL, retry this command.
You can verify the status of Next-Gen API using this command:
> show ns nextgenapi

Next-Gen API State: STARTED

>
Now, you can start exploring its new APIs.

API reference

Next-Gen API reference documentation is specified using the OpenAPI specification. The same specification used for documentation is used to generate API server stubs to ensure that the documentation always reflects the actual specification.
You will also find multiple examples of each API endpoint in the reference documentation to illustrate usage. You can browse the API documentation on the NetScaler GUI under the Documentation tab, and download a copy of the YAML OpenAPI specification from the Downloads tab.

Authentication

Next-Gen API requires users to first authenticate using a valid user account on NetScaler in order to obtain a session token. Once authenticated, the returned cookie needs to be included in all subsequent API calls in the form of a cookie.
Use the following API for authentication and obtaining a session token.
POST /mgmt/api/nextgen/v1/login

{
  "login": {
    "username": "user1",
    "password": "verysecret"
  }
}
If authentication is successful, the returned status code is 200, and the response will include a Set-Cookie header that will set a cookie named sessionid which contains a valid session token to be used for subsequent API calls.
200 OK
Set-Cookie: sessionid=%23%23B2A100C6D1F36AAE2......A50FA2C576171;
Path=/mgmt/api/nextgen/v1
You can also specify the duration of the created session, by adding a timeout attribute to the login request as shown below:
POST /mgmt/api/nextgen/v1/login

{
  "login": {
    "username": "user1",
    "password": "verysecret",
    "timeout": "5min"
  }
}
In the above example, we are requesting a session that will timeout after 5 minutes of inactivity.
Note:
In Next-Gen API, all values that represent time duration, will always have the unit of time as part of the value. For example, a 5 minutes value, can be given as 5m, 5min, 300s or 300sec.
After a successful login, subsequent API requests should include the sessionid cookie header. For example, to list all applications, the following API call with the sessionid cookie is made:
GET /mgmt/api/nextgen/v1/applications

Cookie: sessionid=%23%23B2A100C6D1F36AAE2......A50FA2C576171
Next-Gen API also provides an explicit call to logout from the session, which invalidates the session token.
POST /mgmt/api/nextgen/v1/logout

Cookie: sessionid=%23%23B2A100C6D1F36AAE2......A50FA2C576171
The following is a successful response to the logout API call:
200 OK

Set-Cookie: sessionid=deleted; expires=Thu, 01-Jan-1970 00:00:01 GMT; Max-Age=0; Path=/mgmt/api/nextgen/v1
The response doesn't contain a body payload. Once successfully logged out, the session cookie is no longer valid.
Note:
Next-Gen API and Nitro API share the same system users. You can configure users who can access the appliance using regular NetScaler CLI or GUI.

Role-Based Access

Next-Gen API allows you to define the set of API endpoints that a user can call through the ability of defining roles, and associating allowed operations and API endpoints with each role. You can then assign these roles to user groups.
The following API creates a role called app-admins that allows users all operations on the applications resources.
POST mgmt/api/nextgen/v1/roles/apps-admin-role

{
  "role": {
    "name": "apps-admin-role",
    "permissions": [
      {
        "method": "ALL",
        "resources": "/applications/.+"
      }
    ]
  }
}
The role has a name and a set of permissions. Each permission specifies the resource URLs allowed (using a regular expression) along with the HTTP methods on these resources. In the example above, the role allows all HTTP methods (GET, POST, PUT, DELETE) on any application by specifying the regular expression "/applications/.+".
Once the role is defined, it can be assigned to one or multiple user groups. The following API assigns the role "apps-admin-role" to the user group "apps-admin-grp".
POST mgmt/api/nextgen/v1/groups/apps-admin-grp/roles

{
  "role": "apps-admin-role"
}
Once a role is assigned to a group, it cannot be deleted until it is dissociated from any user groups where it is being used. You can remove the association between a user group and a role using the following API
DELETE mgmt/api/nextgen/v1/groups/apps-admin-grp/roles/apps-admin-role
Now, when a user logs in through Next-Gen API, their user groups are retrieved, and based on the roles for these groups, the logged in user will be restricted to the API endpoints allowed by these roles.
If a user tries to access an API endpoint for which they are not authorized, they will receive a 401 Not Authorized error.
Note:
Configuring user accounts, user groups and managing user authentication on NetScaler, including configuring external authentication such as LDAP or RADIUS can continue to be managed using NetScaler CLI, GUI, or Nitro API. Please refer to NetScaler documentation for these topics.

Configuration Paradigms

NetScaler Next-Gen API supports two complementary configuration paradigms designed to address different use cases and user requirements:
  • Application-Centric Model: The application-centric approach groups all configuration elements related to an application together, making it easy to manage complete application configurations atomically. This model is ideal for common use cases and provides a simplified, high-level abstraction.
For detailed API reference information about the Application-Centric model, including resource types, API structure, and semantics, see the Application-Centric API Reference.
  • Entity-Centric Model (Config Sets): For scenarios requiring full access to NetScaler's feature set or granular control over individual Nitro entities, Config Sets provide a declarative mechanism to define any NetScaler configuration. This bridges the gap between the power of Nitro and the simplicity of Next-Gen API's desired-state model.
For detailed information about Config Sets, including use cases, examples, and best practices, see the Config Sets Guide.

API Calls Structure

Next-Gen API resources and calls all follow a consistent format.
<http_verb> /mgmt/api/nextgen/v1/<resource_type>/<resource_name>
For example to retrieve the details of an application called my_app:
GET /mgmt/api/nextgen/v1/applications/my_app
If you want to retrieve all applications, you omit the resource_name part:
GET /mgmt/api/nextgen/v1/applications
Some resources are sub-resources of existing resources, in which case, the URL follows this format:
<http_verb> /mgmt/api/nextgen/v1/<resource_type>/<resource_name>/<subresource_type>/<subresource_name>
For example to retrieve the backends of an application called my_app, you use the following API call:
GET /mgmt/api/nextgen/v1/applications/my_app/backends
To retrieve a specific backend named metadata_servers, you use the following call:
GET /mgmt/api/nextgen/v1/applications/my_app/backends/metadata_servers
The supported HTTP verbs are the following:
Verb description
GET This verb is used to retrieve a specific resource by name or a list of resources for a certain type.
POST This verb is used to create or update the "desired state" of a resource. If a resource is successfully created, the returned status code is 201. If an existing resource was updated, the returned status code is 200.
PUT This verb is used to update the "desired state" of an existing resource.
DELETE This verb is used to delete an existing resource.
The request and response payloads are expressed in JSON format.

Resource Types and Resources

Next-Gen API config model is made up of a set of resource types. The following are the resource types currently supported:
  • Application
    • Backend
      • Server
    • Frontend
      • Listener
    • Route
  • Certificate
  • Filter Value Set
  • Responder HTMLPage
  • HTTP Callouts
  • Config Sets
Resource types are organized in a hierarchy: some resource types are subtypes of others as indicated by the indentation above. For example, frontends and backends are subtypes of the application resource type. And servers is a subtype of a backend. This hierarchy is reflected in the URL representation of a resource.
/mgmt/api/nextgen/v1/applications/{application_name}/backends/{backend_name}/servers
Here the URL reflects that servers is a subresource of a specific backend, which is a subresource of a specific application.
The following table describes the role of each resource supported in the API:
Resource Parent Resource Description
Application N/A The application resource is the top resource that represents a complete configuration.
Frontend Application An application can have multiple frontends. Each frontend represents a virtual IP. For example, an application can have an internal virtual IP and an external virtual IP. Most applications have only one virtual IP, in which case the frontend is implicit.
Listener Frontend A Listener represents a port on the virtual IP. Some applications can listen on multiple ports (for example, HTTP/80 and HTTPS/443) and therefore need multiple listeners. Often, applications listen only on one port, in which case the listener is implicit.
Backend Application A Backend represent a set of servers that serve the same traffic and for which incoming client requests can be load-balanced between them.
Servers Backend The list of server IPs/Ports that make up a backend.
Certificate N/A A certificate is a top resource. A certificate represents a public/private key pair and any certificate chain (intermediate and root certificates).

Listeners

The listener has the following attributes:
Attribute Name Attribute Type Description Required?
name name The name of the listener. Yes
port port The port number of the listener Yes
protocol protocol Protocol for this port. If not specified, defaults to HTTP No
default_certificate_ref reference The name of a server certificate to be used on this port. Depends. If protocol is HTTPS, a certificate must be specified.
certificate_refs List of references The names of a server SNI certificates to be used on this port. If protocol is HTTPS. Can be used with default_certificate_ref.

Applications

In summary, a simple LB application can have the following attributes:
Attribute Name Attribute Type Description Required?
virtual_ip ipaddress The VIP of the application Yes
port port The port number of this VIP. Defaults to either 443 or 80 based on the protocol. No
protocol protocol The protocol of the VIP. Defaults to HTTPS if not specified No
default_certificate_ref reference The name of a server certificate to be used on this port. Depends. If protocol is HTTPS, a certificate must be specified.
certificate_refs List of references The names of a server SNI certificates to be used on this port. If protocol is HTTPS. Can be used with default_certificate_ref.
servers_port port The port number for the backend servers. Defaults to 80 No
servers_protocol protocol The protocol of the servers. Defaults to HTTP if protocol is HTTP or HTTPS. No
servers server list A list of backend servers that will server requests of this application Yes

References between resources

The resource's name specified during creation can be used to refer to it from other resources. We used this already to refer to a certificate from an application payload.
Next-Gen API uses the naming convention <resource_type>_ref for attribute names that carry a reference to an existing resource. For plural references, the naming convention is <resource_type>_refs. For example, the attribute certificate_refs of an application resource.

Desired State Semantics

Next-Gen API allows users to specify the "desired state" of a resource, and let the system figure out how to bring the configuration from its "current state" to that "desired state".
For example, when the user wants to ensure that an application called "app1" with a certain configuration is present on NetScaler, they can simply issue the following API call:
POST /mgmt/api/nextgen/v1/applications/app1

{
  "application": {
    "name": "app1",
    "virtual_ip": "70.122.23.11",
    "protocol": "HTTP",
    "servers": [
      "192.168.10.11",
      "192.168.10.14"
    ]
  }
}
It doesn't matter whether application "app1" already exists or whether it's newly created. Next-Gen API will ensure to create it if it doesn't exit or to update it with the specified configuration if it already exists.
Another example would be configuring the backend servers of an application.
PUT /mgmt/api/nextgen/v1/applications/app1/backends/tier1/servers

{
  "servers": [
    "192.168.10.11",
    "192.168.10.14",
    "192.168.10.15",
    "192.168.10.16",
    "192.168.10.17"
  ]
}
It doesn't matter whether there are servers already in the backend called "tier1" or not. This API will ensure that after it's executed the backend "tier1" will have the specified servers in the request. If some of these servers are already present, then only the missing servers are added. If there are servers that are not specified in the request, then these servers will be removed from the backend.
The "desired state" semantics frees the user from having to track the current state of resources, and having to imperatively specify the steps required to bring the resource to the user's desired state.

Incremental Change Semantics

While "desired state" is very useful for simplifying the API client, it is also desirable in some cases to avoid specifying the whole resource state on each API call, and only specify what needs to be changed (added or removed). Taking the previous example, if the backend "tier1" has a 1,000 servers currently, and we want to add 1 extra server, it's bulky to specify 1,001 servers in the request, and would be more efficient to simply specify the new server to be added. Next-Gen API also accomodates this usage pattern by providing an explicit API call to change a resource's state explicitly.
For example, to add a new server to the backend "tier1" (without respecifying all the servers that are already part of this backend), we can use the following API call:
POST /mgmt/api/nextgen/v1/applications/app1/backends/tier1/servers

{
   "server": "192.168.10.17"
}
Similarly, if we want to create a new application called "app1", and we want the operation to fail if "app1" already exists, we can use the following POST API:
POST /mgmt/api/nextgen/v1/applications

{
 "application": {
    "name": "app1",
    "virtual_ip": "70.122.23.11",
    "protocol": "HTTP",
    "servers": [
      "192.168.10.11",
      "192.168.10.14"
    ]
  }
}
The difference with the "desired state" API described in the previous section is a subtle one: we ommitted the application name "app1" from the URL.
POST /mgmt/api/nextgen/v1/applications/app1

Application actions

The following actions are supported for the application:

Disable/Enable Application

To disable the application so it doesn't serve any traffic, use the following API call:
POST /mgmt/api/nextgen/v1/applications/{application-name}/actions/disable
To enable the application so it can serve traffic, use the following API call:
POST /mgmt/api/nextgen/v1/applications/{application-name}/actions/enable
The enable/disable application APIs are reflected in the configured_state parameter in the application health response.
Note:
Disable/Enable APIs are also supported for application subcomponents such as frontends, listeners, backends, and servers. For more information, see API Exploration section of the document.

Uninstall/Install Application

To uninstall the application, meaning the application config is removed from NetScaler data plane(packet engines) but remains on Next-Gen. , use the following API call:
POST /mgmt/api/nextgen/v1/applications/{application-name}/actions/uninstall
This operation is typically useful when there are discrepancies observed in data plane behavior due to config inconsistencies, and you want to clear the config from the data plane and reinstall it later.
To install the uninstalled application, use the following API call:
POST /mgmt/api/nextgen/v1/applications/{application-name}/actions/install

Error Handling

Next-Gen API uses HTTP Status Codes to signal success or failure. Successful API responses are identified by the HTTP status codes 200 or 201.
Below are the list of HTTP Status codes that can be returned by the API and their meaning:
HTTP Status Code Description
200 This status code indicates that the operation is successful. This can be returned for GET, POST and PUT API calls.
201 This status code indicates that the resource creation is successful. This can be returned for POST API calls.
400 This status code indicates an error in the request. The response body will contain details about the type of the error.
401 This status code indicates a failure in authenticating the user. This could also be because of the existing user session has expired and the user needs to logon again. The response contains details about the error.
403 This status code indicates that the user does not have permission to make this API call on the resource referred to in the URL.
404 This status code indicates the referred resource in the GET, POST, PUT or DELETE URL doesn't exist.
409 This status code indicates a failure because of a conflict. For example, if a user tries to create a resource which already exists on NetScaler, this status code is used to indicate the conflict. The response body will contain details of the error.
500 This status code indicates an internal error on NetScaler. The response body contains details onto the nature of the error. User needs to troubleshoot further and return NetScaler to a working condition.
When the HTTP status code indicates an error (400-500 range), the response body contains the details of the error. For example, below is the response body for a 400 error returned, indicating the request payload is missing a required attribute (certificate reference).
{
    "errorcode": 400,
    "errormessage": "Validation Error",
    "details": [
        {
            "instance": "{'name': 'color_app', 'virtual_ip': '10.102.201.171', 'protocol': 'HTTPS', 'service_port': 8010, 'servers': ['10.102.201.166', '10.102.201.167']}",
            "message": "'certificate_ref' is a required property for 'protocol':'HTTPS'"
        }
    ]
}
The following table enumerates the mapping between HTTP Status codes and the internal error codes and error messages:
HTTP Status Code Internal Error Code Internal Error Message
400 1000 Bad Request
400 1001 Invalid JSON data
400 1002 Resource name is different in URL and payload
400 1003 Missing query parameters
401 1100 Unauthorized Request
401 1101 Session expired or killed. Please login again
401 1102 User not authorized for this operation
401 1103 Authentication failed - Please provide sessionid in the cookie
401 1104 Invalid username or password
401 1105 Operation not permitted on HA secondary node
404 1200 Resource not found
404 1201 Application not found
404 1202 Frontend not found
404 1203 Listener not found
404 1204 Backend not found
404 1205 Server not found
404 1206 Route not found
404 1207 Certificate not found
404 1208 Role not found
404 1209 Roles not found
404 1210 No Role associations found for group
404 1211 Value set not found
404 1212 Application not installed
404 1213 Responder HTML page not found
404 1214 HTTP callout not found
406 1300 We only support sending responses in JSON format
409 1400 Resource already exists
409 1401 Delete of resource already in progress
409 1402 Delete of this resource is not possible as it is being referenced by other resources
409 1403 Uninstall of this resource is not possible as it is being referenced by other resources
409 1410 Application already exists
409 1411 Frontend already exists
409 1412 Listener already exists
409 1413 Backend already exists
409 1414 Server already exists
409 1415 Route already exists
409 1416 Certificate already exists
409 1417 Role already exists
409 1418 Group Role association already exists
409 1419 Value set already exists
409 1420 Blocking operation is in Progress, please try after sometime
409 1421 Responder HTML page already exists
409 1422 HTTP callout already exists
415 1500 We only support requests in JSON format
422 2000 Validation Failed
422 3001 The resource cannot be deleted because it is the last remaining resource of its kind
500 1600 Internal Server Error
Note:
Please refer to the OpenAPI spec for an up-to-date information on all the valid errorcode values that can be returned by the API.