openapi: 3.1.0
info:
title: Cisco NX-API REST
description: >-
RESTful API for programmatic access to Cisco Nexus 3000 and 9000 Series
switches. NX-API REST exposes the NX-OS Data Management Engine (DME) object
model over HTTP/HTTPS, enabling configuration management, operational state
retrieval, and real-time event subscriptions using managed objects (MOs)
organized in a hierarchical Management Information Tree (MIT). All objects
are addressed by Distinguished Names (DNs) and support JSON and XML
encodings.
version: 10.5.0
contact:
name: Cisco DevNet Support
url: https://developer.cisco.com/site/support/
email: [email protected]
license:
name: Cisco DevNet
url: https://developer.cisco.com/site/license/
x-documentation:
- title: NX-API REST SDK User Guide
url: https://developer.cisco.com/docs/cisco-nexus-3000-and-9000-series-nx-api-rest-sdk-user-guide-and-api-reference/latest/
- title: Nexus Model Reference
url: https://developer.cisco.com/docs/nexus-model/latest/
- title: NX-OS Programmability Guide
url: https://www.cisco.com/c/en/us/td/docs/dcn/nx-os/nexus9000/105x/programmability/cisco-nexus-9000-series-nx-os-programmability-guide-105x.html
servers:
- url: https://{switchIp}/api
description: Cisco Nexus switch NX-API REST endpoint
variables:
switchIp:
default: 192.168.1.1
description: Management IP address or hostname of the Nexus switch
security:
- cookieAuth: []
tags:
- name: Authentication
description: Session authentication and token management via aaaLogin and aaaLogout
- name: Interfaces
description: >-
Physical interface configuration and operational state using the l1PhysIf
managed object class (DN sys/intf/phys-[id])
- name: VLANs
description: >-
VLAN bridge domain management using the l2BD managed object class
(DN sys/bd/bd-[vlan-id]) and SVI interface configuration using sviIf
- name: Routing
description: >-
IPv4 and IPv6 static route configuration using ipv4Route/ipv6Route
managed objects and BGP protocol management using bgpEntity hierarchy
- name: System
description: >-
Top-level system information and feature management via topSystem
and fmEntity managed objects
paths:
/aaaLogin.json:
post:
operationId: authenticateUser
summary: Authenticate and Obtain Session Cookie
description: >-
Authenticates a user against the NX-OS local or remote AAA database
and returns a session cookie (APIC-cookie) used for subsequent API
requests. The cookie has a configurable idle timeout (default 600
seconds).
tags:
- Authentication
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- aaaUser
properties:
aaaUser:
type: object
required:
- attributes
properties:
attributes:
type: object
required:
- name
- pwd
properties:
name:
type: string
description: Username for authentication
examples:
- admin
pwd:
type: string
format: password
description: Password for authentication
example:
aaaUser:
attributes:
name: admin
pwd: Cisco123!
responses:
'200':
description: Authentication successful
headers:
Set-Cookie:
description: Session cookie (APIC-cookie) for subsequent requests
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/AaaLoginResponse'
'401':
description: Authentication failed - invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/aaaLogout.json:
post:
operationId: logoutUser
summary: Terminate Authenticated Session
description: >-
Ends the current authenticated session and invalidates the session
cookie.
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
aaaUser:
type: object
properties:
attributes:
type: object
properties:
name:
type: string
description: Username of the session to terminate
responses:
'200':
description: Logout successful
content:
application/json:
schema:
$ref: '#/components/schemas/ImDataResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/intf/phys-[{interfaceId}].json:
get:
operationId: getPhysicalInterface
summary: Retrieve Physical Interface Configuration and State
description: >-
Returns the configuration and operational state of a specific physical
Ethernet interface identified by its l1PhysIf distinguished name. Use
the query-target parameter to retrieve child objects including counters
and statistics (rmonEtherStats, rmonIfHCIn, rmonIfHCOut).
tags:
- Interfaces
parameters:
- $ref: '#/components/parameters/interfaceId'
- $ref: '#/components/parameters/queryTarget'
- $ref: '#/components/parameters/targetSubtreeClass'
- $ref: '#/components/parameters/queryTargetFilter'
- $ref: '#/components/parameters/rspSubtree'
- $ref: '#/components/parameters/rspPropInclude'
responses:
'200':
description: Interface details returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PhysicalInterfaceResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/intf.json:
post:
operationId: configurePhysicalInterface
summary: Configure a Physical Ethernet Interface
description: >-
Creates or modifies the configuration of one or more physical Ethernet
interfaces. The payload uses the interfaceEntity container with l1PhysIf
child objects. Properties include administrative state, speed, duplex,
MTU, layer mode, switchport mode, access VLAN, trunk VLANs, and
description.
tags:
- Interfaces
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InterfaceEntityPayload'
example:
interfaceEntity:
children:
- l1PhysIf:
attributes:
id: eth1/1
adminSt: up
layer: Layer2
mode: access
accessVlan: vlan-100
descr: Server port
responses:
'200':
description: Configuration applied successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ImDataResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/class/l1PhysIf.json:
get:
operationId: listPhysicalInterfaces
summary: List All Physical Interfaces
description: >-
Returns all l1PhysIf managed objects on the switch via a class-level
query. Supports filtering by property values and pagination. Each
returned object includes the full DN and configured properties.
tags:
- Interfaces
parameters:
- $ref: '#/components/parameters/queryTargetFilter'
- $ref: '#/components/parameters/rspSubtree'
- $ref: '#/components/parameters/rspPropInclude'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/page'
responses:
'200':
description: List of physical interfaces returned
content:
application/json:
schema:
$ref: '#/components/schemas/PhysicalInterfaceListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/bd.json:
post:
operationId: createVlan
summary: Create or Modify a Vlan Bridge Domain
description: >-
Creates or modifies VLAN bridge domains using the bdEntity container
with l2BD child objects. The fabEncap attribute specifies the VLAN ID
in the format vlan-{id}. Supports VLAN naming and pcTag assignment.
tags:
- VLANs
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BdEntityPayload'
example:
bdEntity:
children:
- l2BD:
attributes:
fabEncap: vlan-100
name: Production
pcTag: "1"
responses:
'200':
description: VLAN created or modified successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ImDataResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/bd/bd-[{vlanEncap}].json:
get:
operationId: getVlan
summary: Retrieve a Specific Vlan Bridge Domain
description: >-
Returns the configuration and state of a specific VLAN bridge domain
identified by its fabric encapsulation (e.g., vlan-100). Use
rsp-subtree=full to include child objects like VLAN member ports
and statistics.
tags:
- VLANs
parameters:
- name: vlanEncap
in: path
required: true
description: >-
VLAN fabric encapsulation identifier in the format vlan-{id}
(e.g., vlan-100)
schema:
type: string
pattern: ^vlan-\d+$
examples:
- vlan-100
- $ref: '#/components/parameters/rspSubtree'
- $ref: '#/components/parameters/rspPropInclude'
responses:
'200':
description: VLAN bridge domain details returned
content:
application/json:
schema:
$ref: '#/components/schemas/VlanBridgeDomainResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteVlan
summary: Delete a Vlan Bridge Domain
description: >-
Removes a VLAN bridge domain from the switch configuration. This
operation also removes any associated SVI and port membership
configurations.
tags:
- VLANs
parameters:
- name: vlanEncap
in: path
required: true
description: VLAN fabric encapsulation identifier (e.g., vlan-100)
schema:
type: string
pattern: ^vlan-\d+$
responses:
'200':
description: VLAN deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ImDataResponse'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/class/l2BD.json:
get:
operationId: listVlans
summary: List All Vlan Bridge Domains
description: >-
Returns all l2BD managed objects representing configured VLANs on
the switch. Supports filtering by VLAN name, encapsulation, or
administrative state.
tags:
- VLANs
parameters:
- $ref: '#/components/parameters/queryTargetFilter'
- $ref: '#/components/parameters/rspPropInclude'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/page'
responses:
'200':
description: List of VLAN bridge domains returned
content:
application/json:
schema:
$ref: '#/components/schemas/VlanBridgeDomainListResponse'
'400':
$ref: '#/components/responses/BadRequest'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/intf/svi-[{sviId}].json:
get:
operationId: getSviInterface
summary: Retrieve an Svi (vlan Interface) Configuration
description: >-
Returns the configuration and operational state of a Switch Virtual
Interface (SVI) identified by its VLAN ID (e.g., vlan100). SVIs
provide Layer 3 routing capability for VLANs.
tags:
- VLANs
parameters:
- name: sviId
in: path
required: true
description: SVI identifier in the format vlan{id} (e.g., vlan100)
schema:
type: string
pattern: ^vlan\d+$
examples:
- vlan100
- $ref: '#/components/parameters/rspSubtree'
- $ref: '#/components/parameters/rspPropInclude'
responses:
'200':
description: SVI interface details returned
content:
application/json:
schema:
$ref: '#/components/schemas/SviInterfaceResponse'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: configureSviInterface
summary: Create or Modify an Svi (vlan Interface)
description: >-
Creates or modifies a Switch Virtual Interface (SVI) for Layer 3
routing on a VLAN. Requires the interface-vlan feature to be enabled
(fmInterfaceVlan adminSt=enabled). Properties include admin state,
description, MTU, bandwidth, MAC address, and medium type.
tags:
- VLANs
parameters:
- name: sviId
in: path
required: true
description: SVI identifier in the format vlan{id}
schema:
type: string
pattern: ^vlan\d+$
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SviIfPayload'
example:
sviIf:
attributes:
id: vlan100
adminSt: up
descr: Production Gateway
mtu: "9216"
responses:
'200':
description: SVI configured successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ImDataResponse'
'400':
$ref: '#/components/responses/BadRequest'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/ipv4/inst.json:
post:
operationId: configureStaticRoute
summary: Create or Modify Ipv4 Static Routes
description: >-
Configures IPv4 static routes using the ipv4Inst container with
ipv4Dom, ipv4Route, and ipv4Nexthop child objects. Routes are
defined by destination prefix and one or more next-hop specifications
including interface, address, VRF, preference, name, and tag.
tags:
- Routing
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Ipv4InstPayload'
example:
ipv4Inst:
children:
- ipv4Dom:
attributes:
name: default
children:
- ipv4Route:
attributes:
prefix: 10.0.0.0/8
children:
- ipv4Nexthop:
attributes:
nhAddr: 192.168.1.1
nhIf: eth1/1
nhVrf: default
pref: "1"
tag: "100"
responses:
'200':
description: Static route configured successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ImDataResponse'
'400':
$ref: '#/components/responses/BadRequest'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/ipv4/inst/dom-{vrfName}/rt-[{prefix}].json:
get:
operationId: getStaticRoute
summary: Retrieve a Specific Ipv4 Static Route
description: >-
Returns the configuration of a specific IPv4 static route including
all configured next-hops. The route is identified by VRF name and
destination prefix.
tags:
- Routing
parameters:
- name: vrfName
in: path
required: true
description: VRF name (use "default" for the global routing table)
schema:
type: string
default: default
- name: prefix
in: path
required: true
description: IPv4 destination prefix in CIDR notation (e.g., 10.0.0.0/8)
schema:
type: string
format: ipv4-network
- $ref: '#/components/parameters/rspSubtree'
responses:
'200':
description: Static route details returned
content:
application/json:
schema:
$ref: '#/components/schemas/Ipv4RouteResponse'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/class/ipv4Route.json:
get:
operationId: listStaticRoutes
summary: List All Ipv4 Static Routes
description: >-
Returns all ipv4Route managed objects across all VRFs. Supports
filtering by prefix, VRF, or route tag.
tags:
- Routing
parameters:
- $ref: '#/components/parameters/queryTargetFilter'
- $ref: '#/components/parameters/rspSubtree'
- $ref: '#/components/parameters/rspPropInclude'
responses:
'200':
description: List of IPv4 static routes returned
content:
application/json:
schema:
$ref: '#/components/schemas/Ipv4RouteListResponse'
'400':
$ref: '#/components/responses/BadRequest'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/bgp.json:
get:
operationId: getBgpConfiguration
summary: Retrieve Full Bgp Configuration
description: >-
Returns the complete BGP configuration tree including bgpEntity,
bgpInst, all bgpDom domains, and bgpPeer neighbors. Use
rsp-subtree=full to retrieve the entire hierarchy.
tags:
- Routing
parameters:
- $ref: '#/components/parameters/rspSubtree'
- $ref: '#/components/parameters/rspPropInclude'
responses:
'200':
description: BGP configuration returned
content:
application/json:
schema:
$ref: '#/components/schemas/BgpEntityResponse'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys.json:
get:
operationId: getSystemInfo
summary: Retrieve Top-level System Information
description: >-
Returns the topSystem managed object containing system-wide
information including hostname, serial number, NX-OS version,
uptime, and system state.
tags:
- System
parameters:
- $ref: '#/components/parameters/rspPropInclude'
responses:
'200':
description: System information returned
content:
application/json:
schema:
$ref: '#/components/schemas/TopSystemResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: configureSystem
summary: Apply System-level Configuration
description: >-
Applies configuration changes at the top system level. This endpoint
accepts a topSystem payload with nested child objects for configuring
interfaces (interfaceEntity), BGP (bgpEntity), features (fmEntity),
and other subsystems in a single atomic transaction.
tags:
- System
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TopSystemPayload'
responses:
'200':
description: Configuration applied successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ImDataResponse'
'400':
$ref: '#/components/responses/BadRequest'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mo/sys/fm.json:
post:
operationId: configureFeatures
summary: Enable or Disable Nx-os Features
description: >-
Manages NX-OS feature activation using the fmEntity container.
Features include interface-vlan (fmInterfaceVlan), BGP (fmBgp),
OSPF (fmOspf), LACP (fmLacp), and others. Each feature has an
adminSt property that accepts enabled or disabled.
tags:
- System
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FmEntityPayload'
example:
fmEntity:
children:
- fmInterfaceVlan:
attributes:
adminSt: enabled
- fmBgp:
attributes:
adminSt: enabled
responses:
'200':
description: Feature configuration applied
content:
application/json:
schema:
$ref: '#/components/schemas/ImDataResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
cookieAuth:
type: apiKey
in: cookie
name: APIC-cookie
description: >-
Session cookie obtained from the /api/aaaLogin endpoint. The cookie
has a configurable idle timeout (default 600 seconds) and must be
included in all subsequent requests.
parameters:
interfaceId:
name: interfaceId
in: path
required: true
description: >-
Physical interface identifier matching the output of show interface
brief (e.g., eth1/1, eth1/2, eth2/1)
schema:
type: string
pattern: ^eth\d+/\d+(/\d+)?$
examples:
- eth1/1
queryTarget:
name: query-target
in: query
required: false
description: >-
Specifies the scope of the query relative to the target DN.
self returns the target MO only. children returns direct children.
subtree returns the full subtree.
schema:
type: string
enum:
- self
- children
- subtree
default: self
targetSubtreeClass:
name: target-subtree-class
in: query
required: false
description: >-
Filters subtree query results to only include objects of the
specified class (e.g., rmonEtherStats, rmonIfHCIn)
schema:
type: string
queryTargetFilter:
name: query-target-filter
in: query
required: false
description: >-
Filter expression using conditions like eq(property,"value"),
ne(property,"value"), gt, lt, ge, le, wcard, and boolean operators
and, or, not
schema:
type: string
rspSubtree:
name: rsp-subtree
in: query
required: false
description: >-
Controls the depth of child objects returned in the response.
no returns the target MO only. children includes direct children.
full includes the complete subtree.
schema:
type: string
enum:
- "no"
- children
- full
default: "no"
rspPropInclude:
name: rsp-prop-include
in: query
required: false
description: >-
Controls which properties are included in the response. all returns
all properties. config-only returns only configurable properties.
set-config-only returns only properties that have been explicitly set.
schema:
type: string
enum:
- all
- config-only
- set-config-only
default: all
pageSize:
name: page-size
in: query
required: false
description: Number of objects to return per page for class-level queries
schema:
type: integer
minimum: 1
default: 50
page:
name: page
in: query
required: false
description: Page number for paginated class-level queries (0-indexed)
schema:
type: integer
minimum: 0
default: 0
schemas:
ImDataResponse:
type: object
description: Standard NX-API REST response wrapper
properties:
totalCount:
type: string
description: Total number of managed objects in the response
example: example_value
imdata:
type: array
description: Array of managed object results
items:
type: object
example: []
ErrorResponse:
type: object
description: Error response from NX-API REST
properties:
imdata:
type: array
items:
type: object
properties:
error:
type: object
properties:
attributes:
type: object
properties:
code:
type: string
description: Numeric error code
text:
type: string
description: Human-readable error message
example: []
AaaLoginResponse:
type: object
properties:
totalCount:
type: string
example: example_value
imdata:
type: array
items:
type: object
properties:
aaaLogin:
type: object
properties:
attributes:
type: object
properties:
token:
type: string
description: Authentication token (also set as cookie)
refreshTimeoutSeconds:
type: string
description: Session idle timeout in seconds
userName:
type: string
description: Authenticated username
example: []
L1PhysIf:
type: object
description: >-
Layer 1 physical interface managed object representing a physical
Ethernet port on a Nexus switch. DN format is
sys/intf/phys-[{id}].
properties:
attributes:
type: object
properties:
dn:
type: string
description: Distinguished name (e.g., sys/intf/phys-[eth1/1])
examples:
- sys/intf/phys-[eth1/1]
id:
type: string
description: Interface identifier matching show interface brief output
examples:
- eth1/1
adminSt:
type: string
description: Administrative state of the interface
enum:
- up
- down
operSt:
type: string
description: Operational state (read-only)
enum:
- up
- down
- link-up
layer:
type: string
description: Layer mode of the interface
enum:
- Layer2
- Layer3
mode:
type: string
description: Switchport mode (applicable when layer is Layer2)
enum:
- access
- trunk
- fex-fabric
- dot1q-tunnel
- promiscuous
accessVlan:
type: string
description: >-
Access VLAN assignment in the format vlan-{id}
(applicable when mode is access)
pattern: ^vlan-\d+$
examples:
- vlan-100
trunkVlans:
type: string
description: >-
Trunk allowed VLANs. Supports ranges (1-100), additions (+50),
and removals (-50). Use 1-4094 for all VLANs.
examples:
- 1-100,200,300-400
nativeVlan:
type: string
description: Native VLAN for trunk ports in the format vlan-{id}
pattern: ^vlan-\d+$
examples:
- vlan-1
speed:
type: string
description: Interface speed setting
enum:
- auto
- "100M"
- "1G"
- "10G"
- "25G"
- "40G"
- "100G"
duplex:
type: string
description: Duplex mode setting
enum:
- auto
- full
- half
mtu:
type: string
description: Maximum transmission unit (bytes, 576-9216)
examples:
- "1500"
- "9216"
descr:
type: string
description: Interface description (max 254 characters)
maxLength: 254
snmpTrapSt:
type: string
description: SNMP trap link-state notifications
enum:
- enable
- disable
modTs:
type: string
format: date-time
description: Last modification timestamp (read-only)
example: example_value
L2BD:
type: object
description: >-
Layer 2 bridge domain managed object representing a VLAN.
DN format is sys/bd/bd-[{fabEncap}].
properties:
attributes:
type: object
properties:
dn:
type: string
description: Distinguished name (e.g., sys/bd/bd-[vlan-100])
examples:
- sys/bd/bd-[vlan-100]
fabEncap:
type: string
description: >-
Fabric encapsulation in the format vlan-{id} or vxlan-{id}
pattern: ^(vlan|vxlan)-\d+$
examples:
- vlan-100
name:
type: string
description: VLAN name
maxLength: 32
examples:
- Production
pcTag:
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cisco-nexus/refs/heads/main/openapi/cisco-nexus-nxapi-rest.yml