Skip to main content
PacketMentor logo
← All topics
Automation & Programmability Foundational

Cisco ACI API Basics: Login, Class Query, Managed Objects

The ACI REST API in exam shape: login with aaaLogin to get a cookie, then class-level queries like /api/node/class/fvTenant.json. Covers 3.9.a for ACI.

Quick summary
  • ACI is managed by one or more APIC controllers. All config is a tree of Managed Objects (MOs) under /api.
  • Auth: POST /api/aaaLogin.json with username+password; APIC sets a cookie you reuse.
  • Common first calls: list tenants (/api/node/class/fvTenant.json), list devices (/api/node/class/fabricNode.json).

Studying for an exam? Get a free study plan from a Cisco NetAcad instructor. 20 minutes, no card.

Mental model

Cisco objective 3.9.a also includes ACI. ACI is Cisco’s data-center fabric; it is controlled by a cluster of APICs (Application Policy Infrastructure Controllers). The REST API is on each APIC, usually https://apic1.example.com/api/.

ACI’s model is different from most Cisco APIs:

  • Everything is a Managed Object (MO). Switches, interfaces, tenants, bridge domains, EPGs, contracts.
  • MOs form a tree under a root called polUni (policy universe).
  • Each MO has a Distinguished Name (DN) that spells its path through the tree, e.g. uni/tn-Acme/BD-Web.
  • The API lets you GET the MOs by class (every tenant: fvTenant) or by DN (one specific MO).
curl -k -c cookie.jar -X POST \
     -H "Content-Type: application/json" \
     -d '{"aaaUser":{"attributes":{"name":"admin","pwd":"password"}}}' \
     https://apic1.example.com/api/aaaLogin.json
  • -c cookie.jar tells curl to save response cookies to a file.
  • APIC responds with a JSON body AND a Set-Cookie: APIC-cookie=... header.
  • From now on, pass -b cookie.jar on every call to send the cookie back.

Response (abbreviated):

{
  "imdata": [{"aaaLogin": {"attributes": {
    "token": "GgAAAAAAAAAAAAAAAAAAAA==", "refreshTimeoutSeconds": "600"
  }}}]
}

Cookie-based session; expires after refreshTimeoutSeconds seconds (default ~600). Call POST /api/aaaRefresh.json to extend.

3.9.a — List tenants (class query)

curl -k -b cookie.jar https://apic1.example.com/api/node/class/fvTenant.json

Response:

{
  "totalCount": "3",
  "imdata": [
    {"fvTenant": {"attributes": {"name": "common", "dn": "uni/tn-common"}}},
    {"fvTenant": {"attributes": {"name": "Acme", "dn": "uni/tn-Acme"}}},
    {"fvTenant": {"attributes": {"name": "mgmt", "dn": "uni/tn-mgmt"}}}
  ]
}

Every response wraps results in imdata (an array of per-MO objects). Each MO entry has an attributes dict and sometimes children.

List fabric devices

curl -k -b cookie.jar https://apic1.example.com/api/node/class/fabricNode.json

Returns every spine + leaf + APIC in the fabric. Attributes include id, name, role (spine / leaf / controller), model, serial, fabricSt (active / inactive).

Query by DN

curl -k -b cookie.jar https://apic1.example.com/api/node/mo/uni/tn-Acme.json

Pulls one specific MO (and optionally its children with ?query-target=children).

Python with requests

import requests
requests.packages.urllib3.disable_warnings()

BASE = "https://apic1.example.com"
session = requests.Session()

# login
session.post(f"{BASE}/api/aaaLogin.json",
             json={"aaaUser": {"attributes": {"name": "admin", "pwd": "password"}}},
             verify=False)

# list tenants
r = session.get(f"{BASE}/api/node/class/fvTenant.json", verify=False)
for entry in r.json()["imdata"]:
    tn = entry["fvTenant"]["attributes"]
    print(tn["name"], tn["dn"])

A Session() object persists the cookie across calls automatically.

Common ACI MO classes worth knowing

Class What it is
fvTenant A tenant (customer / business unit)
fvBD Bridge domain (L2 broadcast scope)
fvAEPg Application EPG (endpoint group)
vzBrCP Contract (traffic policy between EPGs)
fabricNode Any switch or APIC
topSystem System info per node
l1PhysIf Physical interface

Common gotchas

  • Cookie expires in minutes. Catch 403 and re-login, or call aaaRefresh.json on a timer.
  • XML or JSON. APIC accepts both; use .json extension on URL for JSON.
  • Case-sensitive class names. fvTenant works; fvtenant returns empty.
  • Trailing-slash sensitivity. APIC is strict about URL shape.
  • Child vs self query. ?query-target=children returns children, not the parent. ?query-target=subtree returns the whole sub-tree below.

FAQ

Is the ACI API REST? Yes, HTTP + JSON (or XML). It is RESTful but with its own model (MOs, DNs) rather than resource-per-URL.

What is the cobra Python SDK? acicobra is Cisco’s Python SDK for ACI. Models every MO as a Python class. For 200-901, requests + Session is enough.

Can I use NETCONF/RESTCONF against ACI? No, APIC uses its own management plane. The per-leaf Nexus 9000s do speak NX-API / RESTCONF but managed-by-APIC fabrics expect you to drive via the APIC.

Where do I practice without a real fabric? DevNet Sandbox has an always-on ACI simulator. Credentials on its sandbox page.

Master this on a real network

Want this drilled into reflex?

1:1 weekly sessions, live feedback on your labs, and US interview prep: built around the CCNA Automation® exam blueprint. Free first session. No card on file until you decide.

Claim my free session →
Free first session

Stuck on Cisco ACI API Basics: Login, Class Query, Managed Objects?

Walk your plan with a Cisco NetAcad instructor in a free 20 minute call. We find the one thing blocking you and name the next step. No card. No pitch.

  • 20 minutes, 1:1 with a Cisco NetAcad instructor
  • No card, no obligation, no sales pitch
  • You pick the slot that fits your week
Book free session
Free first session

Get your study plan in a free 20-minute call

  • ✓ 1:1 with a senior network engineer, by video
  • ✓ You leave with a written study plan and a realistic exam date
  • ✓ No card, no sign-up, no sales pitch