# Cisco IQ: Engineering APIs for the Agentic Era > Source: > Published: 2026-11-04 17:30:28+00:00 From day one, [Cisco IQ](https://blogs.cisco.com/customerexperience/from-vision-to-reality-intelligence-in-action-with-cisco-iq) was built on a clear mandate: deliver unified, deterministic, AI-powered operational intelligence through an API-first architecture. We [delivered on that promise](https://blogs.cisco.com/news/cisco-iq-is-the-engine-partners-are-the-business) with the announcements last week at Partner Summit 2026. We officially opened Cisco IQ with a comprehensive suite of production REST APIs and our Model Context Protocol (MCP) server. This ensures our intelligence runs seamlessly with any existing system or AI agent. The best part, the foundation extends to our partners as well. Partners can now enhance their own managed services with capabilities from Cisco IQ, integrated through API and MCP interfaces. Since Cisco IQ’s general availability in Apr 2026, over 16,000 customers have deployed Cisco IQ, and, as we expand this ecosystem, a new class of API consumer has arrived at scale: the autonomous AI agent. Agents do not consume APIs the way human software developers do. Developers read specifications, plan integration loops, and write deterministic code. AI agents explore probabilistically: they guess, they retry, and they attempt to join disparate data within their prompt context window. So, we asked a fundamental engineering question: what does an API architecture look like if it is designed to serve human developers and autonomous AI agents equally well, from the exact same contract? Our answer is that trusting an agent should not be a separate decision. An agent does not get a separate system, a bespoke rulebook, or an unmonitored side door. It works through the exact same domain model and the exact same security policies that already govern your engineering teams, your operational dashboards, and your enterprise integrations. Here is a look under the hood at how we engineered that reality, from the domain model specification up to our Model Context Protocol (MCP) server. ## 1. One Canonical Model, Every Contract In traditional API development, if you want to know which switches are affected by a specific hardware end-of-life announcement, a developer usually writes a custom endpoint to stitch that data together. Our approach starts with how infrastructure entities exist and relate to each other natively, not with a list of disconnected features. Cisco IQ spans multiple operational domains, and the real value lies in the connections between them. When we add a new capability, we model how it links to what is already there – physical hardware, running operating systems, security advisories, and service contracts – and what new value it brings to the capabilities and domains our customers already use. Each addition makes the whole more useful than the sum of its parts. In practice, we model the relationship, not another endpoint. Every entity, relationship, field definition, and business rule is defined once, in a single canonical domain model. That model is the contract. Everything else compiles directly from it: - The OpenAPI 3.2 descriptions and reference documentation that developers read. - The underlying data store schemas, relational tables, and indexing layers that hold the information. - The fine-grained permission catalog that authorizes every operational call. - The query and tool contracts that AI agents use to reason over data through MCP. - Developer tooling, SDK generation, and presentation metadata that stay permanently synchronized. Relationships across the infrastructure lifecycle are declared explicitly in the model with strict direction and cardinality. Because every surface derives from this shared source, they cannot drift apart. A field a developer inspects in the API Reference is identical to the field Cisco IQ stores in the database, indexes in query planning, and exposes to an AI agent. The OpenAPI definition acts as the absolute boundary: if a capability is not in the model, it does not exist. And when a rule changes, we update it once in the canonical model, and it propagates everywhere at once: in the public REST call, in developer tooling, and in the agent’s MCP tool call. **One source of truth for people, software, and AI agents.** ## 2. Predictable for Developers, Checkable for Agents A well-engineered API is predictable. Learn one corner of it, and you know the rest. Because every Cisco IQ API behaves the same way, a developer or an agent that learns one corner of it can predict the rest, and anything that goes wrong comes back as one clear answer instead of a guess. We made specific architectural decisions to ensure our APIs operate with absolute consistency: - **Learn once, run anywhere:** Every resource URL adheres to a consistent structure (https://{host}/api/{namespace}/v1/{resource}), so no call ever needs to be relearned, routing through regional endpoints (e.g., us-west-2, eu-central-1) to enforce strict data sovereignty and residency mandates. - **Standardized Queries and Clean Schemas:** Top-level collections accept uniform parameters using the Common Expression Language (CEL), ensuring conditions behave consistently everywhere. To prevent SDK generation failures, we keep our OpenAPI definitions free of oneOf schema bloat. Furthermore, we enforce a strict Leading Underscore (_) Alias Rule for client-defined calculations in queries to guarantee they never collide with future platform schema additions. - **Resilient Pagination and Bounded Relationships:** Traditional offset pagination breaks when hardware telemetry streams change concurrently. Our collections enforce keyset pagination using opaque cursors (RFC 5988) to guarantee stable reads. We also bound responses for to-many relationships rather than capping data, rendering massive datasets (like 10,000 security findings) inline via bounded envelopes or as structured href links for atomic additions and removals. - **Safe Writes and Failing Loudly:** Lenient APIs encourage guessing. Unknown fields or malformed values return immediate errors using RFC 9457 problem details, delivering all validation errors in one structured array so a developer or agent can correct them in a single iteration. For updates, we use JSON Merge Patch for atomic modifications and ETags for optimistic concurrency, ensuring conflicting writes fail safely rather than overwriting another process’s changes. - **Authorization in the Vocabulary of the Model:** Permissions are named directly after actions, from a complete type (read:asset.Asset) down to a single attribute (update:asset.Asset.tags). Lists filter row by row, ensuring callers receive only the exact records they are authorized to view. - **Operability and Non-Breaking Evolution:** Every operation sits under an immutable version path, with responses carrying W3C traceparent headers for distributed tracing. Automated compatibility checks run in our CI/CD pipelines, catching breaking contract changes before release. ## 3. Why Wrapping APIs is Not Enough for Agents Most MCP servers today expose each individual API operation as a separate tool. To answer a question like “Which critical devices have support coverage ending this quarter, and which contract covers them?”, an agent must page through devices, page through coverage records, page through contracts, and then join the rows itself. In our baseline measurements, answering a sample single cross-domain question using traditional API wrapping took approximately 120 tool calls just to assemble 40 rows. This approach puts the hardest part of the problem – data correlation across domains – in the place least suited for it: the AI model’s context window. Context is lost at every step, latency spikes, and the resulting answers are prone to hallucinated joins. **Correlation belongs in the platform, not in the prompt.** ## 4. General-Purpose Operations: Moving Correlation to the Platform We solved this by engineering two general-purpose platform operations that handle cross-domain complexity natively: - **Structured Query (POST /api/system/v1/query):** Reads any entity with filtering, projection, ordering, and nested expansion in a single JSON payload. It expands related records and runs aggregations ( groupby, apply, having, compute) across related domains in one trip under the caller’s authorization. - **Bulk Engine (POST /api/system/v1/bulk):** Executes multiple state changes in one request. Clients send a flat list of operations across namespaces without computing manual dependency graphs. 1. **Automated Dependency Resolution:** The engine automatically orders the operations and resolves cyclic entity references by withholding deferred references and writing them as automated follow-up steps. 2. **Synchronous Partial Success:** Atomicity is an inherent property of the write operation, not the HTTP connection. The bulk engine supports partial successes in synchronous responses, returning explicit results mapped exactly to the original submitted positions. This allows a client or agent to instantly resubmit only the operations that failed. ## 5. Four Tools for the Agentic Era Because correlation lives in the platform, our MCP server does not need to expose hundreds of fragile, individual operations to an AI agent. It exposes exactly four tools, projected directly from the canonical model: - **discover:** Finds the entities a question requires, the relationship paths that connect them, and the actions that apply. - **describe:** Returns the exact contract, fields, data types, and action preconditions for an entity or operation. - **query:** Validates a structured query against the schema and executes it through the platform query engine. - **mutate:** Executes an atomic change after validating preconditions and authorization. When Cisco IQ adds a new entity, every agent discovers it automatically using these same four tools. **A stable, secure surface area that grows organically with the model.** ## 6. Agent Identity An agent accessing our platform through MCP uses standard API authentication, inheriting the exact authorization profile of the calling principal. Cisco IQ integrates natively with Cisco Unified Identity (CUI), connecting that identity to our granular, role-based catalog. Whether a policy grants read access to an entire domain or restricts write permissions exclusively to a single asset tag, the AI assistant operates strictly within the caller’s authorized boundaries. It acquires no ambient business privileges simply because it connects over MCP. ## 7. Check Before It Runs: Deterministic Behavior From Probabilistic Models In an enterprise, a query that fails is an annoyance. A query that returns the wrong answer is an unacceptable risk. To ensure determinism, every query an agent writes is checked against the domain model before it hits the execution engine. If an agent gets a field name, value, or relationship wrong: - All validation errors return at once in a structured RFC 9457 response. - The server includes a pre-checked, corrected request payload that the agent can resubmit directly. - The server never silently rewrites or runs a query on assumptions; the agent remains in explicit, deterministic control. - Mutations present prerequisite states as read operations first, allowing human operators to inspect exact diffs before confirming execution. What does this mean in practice? In scripted tests across a benchmark corpus of 17 complex enterprise scenarios, this architecture delivered decisive operations improvements: - Total tool calls dropped from 256 down to 36. - Interactive approval prompts reduced from 181 down to 1. - Standard multi-domain read investigations executed in exactly two calls: discover followed by query. Fewer calls, fewer prompts, and answers the platform can stand behind. ## Engineering Opportunities for Customers and Partners These design choices deliver concrete engineering opportunities across every operational role: - **For Customers:** Whoever acts on your behalf, whether an engineer, an automated CI/CD pipeline, or an autonomous AI agent, operates within the exact security guardrails you already trust. An agent never sees more than the principal it represents is permitted to see, eliminating the need to maintain parallel permission models. Deploying an AI agent in front of your data is not a new trust decision. - **For Partners:** Integrate once against a unified contract. Every capability we introduce follows identical schema conventions, query parameters, and access rules. Whether you are building custom managed services under your own brand or connecting bespoke internal agents, you master the integration pattern once rather than building one-off adapters for every lifecycle stage. ## Coming Soon: Meaning-Based Discovery and Live Agent Measurements We are actively expanding this foundation. We are introducing meaning-based semantic discovery next to keyword search, ensuring natural language requests find target entities as reliably as queries written in strict schema terms. We are also measuring live autonomous AI agents against our 17-question benchmark corpus, preparing to publish real-world agentic performance data alongside our existing scripted baselines. ## The Foundation for Agent-Ready APIs Ultimately, these architectural choices serve human developers and autonomous AI agents simultaneously. Predictable URLs, standardized response envelopes, structured error formats, and uniform CEL parameters simplify integration for developers while making agent outputs strictly checkable. A single model behind every contract ensures that what we expose to an agent is exactly what the platform executes. This architecture also prepares us for what comes next. Because query validation, structural correlation, and error repairs live in the platform rather than the prompt, execution quality does not depend on model parameter size. This design allows smaller, highly efficient, and self-hosted models to operate with the same precision as frontier models. It guarantees that identical contracts and guardrails apply wherever Cisco IQ runs, from regional cloud instances to fully air-gapped sovereign virtual appliances. APIs engineered exclusively for human developers are no longer sufficient. They must actively guide AI agents to verified truths and physically prevent them from executing invalid operations. That is engineering APIs for the agentic era. ### Get Started - Dive deeper: Explore the Cisco IQ API documentation and full [API Reference](https://iq.cisco.com/apidocs/reference) . - Connect an agent: Access the [Cisco IQ MCP server guide](https://iq.cisco.com/apidocs/mcp-server) to bring your AI clients online. - Talk to us: Contact your Cisco account team to discuss how to leverage Cisco IQ APIs and MCP in your environment.