{"slug": "agent-protocol-inspector-api-tutorial-scan-look-up-and-diff-two-scans", "title": "Agent Protocol Inspector API Tutorial: Scan, Look Up, and Diff Two Scans", "summary": "ContextIQ published a curl-based tutorial for its Agent Protocol Inspector API, covering three API-key-authenticated endpoints for scanning MCP or A2A targets, retrieving a stored scan by scanId, and diffing two scans for a pass/warn/fail verdict. All three endpoints share a rate limit of 20 requests per minute and 1,000 per day at $0.02 per call, and API keys require a Pro plan. The diff endpoint returns a CI-usable verdict, with the tutorial's example showing a \"fail\" after a deploy removed the search_docs tool from an MCP target.", "body_md": "# Agent Protocol Inspector API Tutorial: Scan, Look Up, and Diff Two Scans\n\nA curl-based tutorial for the Agent Protocol Inspector API: scanning an MCP or A2A target, retrieving a stored scan by scanId, and diffing two scans for a pass/warn/fail verdict.\n\nThis is a working tutorial for the three API-key-authenticated Agent Protocol Inspector endpoints that matter for automation: running a scan, retrieving a past one without re-scanning, and diffing two scans for a CI-usable verdict. Every request below uses a real endpoint and a real response shape.\n\n## Prerequisites\n\n- An API key from the [developer dashboard](https://contextiq.trango-compute.com/dashboard/developers) — API keys require a Pro plan.\n- `curl` and`jq` for the examples below.\n- If you'd rather pay per call with USDC instead of holding an API key, every endpoint here has an `x402-v2` sibling covered in our[x402 wire v2 tutorial](https://contextiq.trango-compute.com/blog/agent-protocol-inspector-v2-tutorial-mcp-a2a-ard) — the request/response shapes are identical, only the payment step differs.\n\nAll three endpoints share one rate limit bucket: 20 requests/minute, 1,000/day, at $0.02 per call.\n\n## Step 1: Run a Scan\n\n```\ncurl -X POST https://contextiq.trango-compute.com/api/v1/agent-protocol-inspector \\\n  -H \"Authorization: Bearer $CONTEXTIQ_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\":\"mcp.example.com\"}'\n```\n\nThe response is the full scan result, plus a `scanId` you'll reuse in the next two steps:\n\n```\n{\n  \"target\": \"https://mcp.example.com\",\n  \"origin\": \"https://mcp.example.com\",\n  \"protocols\": {\n    \"mcp\": { \"status\": \"confirmed\", \"evidence\": [\"...\"], \"details\": { \"endpoint\": \"https://mcp.example.com/mcp\", \"mcpEra\": \"modern\", \"tools\": [{ \"name\": \"search_docs\" }] } },\n    \"a2a\": { \"status\": \"not_detected\", \"evidence\": [] },\n    \"ard\": { \"status\": \"not_detected\", \"evidence\": [] }\n  },\n  \"detectedCount\": 1,\n  \"conformance\": \"pass\",\n  \"scanId\": \"7f3c9a2e-1b44-4e8d-9c2a-5e7d0f1a8b3c\",\n  \"normalizedAgent\": { \"skills\": [\"...\"] },\n  \"capabilities\": [\"...\"],\n  \"igaPacket\": { \"recommendedDecision\": \"approve\" }\n}\n```\n\nStore `scanId` — it's how you refer back to this exact scan without paying to re-run it, and it's what the diff endpoint compares against.\n\n## Step 2: Look Up That Scan Later\n\nWeeks later, without re-scanning:\n\n```\ncurl https://contextiq.trango-compute.com/api/v1/agent-protocol-inspector/7f3c9a2e-1b44-4e8d-9c2a-5e7d0f1a8b3c \\\n  -H \"Authorization: Bearer $CONTEXTIQ_API_KEY\"\n```\n\nThis returns the identical response shape from Step 1 — `normalizedAgent`, `capabilities`, and `igaPacket` are recomputed fresh from the stored raw scan on every lookup, not cached from when the scan originally ran. That means a capability-rule improvement we ship later applies retroactively to a scan you ran months ago, with no re-scan required.\n\n`scanId` lookup is ownership-scoped for API-key callers: you can only retrieve your own account's scans (anonymous-tier scans, with no owner, are the one exception — they resolve for anyone holding the id within their short retention window). Requesting a scanId that belongs to another account returns a `404`, not a `403` — the endpoint doesn't reveal that the id exists at all.\n\n## Step 3: Run a Second Scan After Your Next Deploy\n\nSame call as Step 1, run again after a deploy, producing a second, different `scanId`.\n\n## Step 4: Diff the Two Scans\n\n```\ncurl -X POST https://contextiq.trango-compute.com/api/v1/agent-protocol-inspector/compare \\\n  -H \"Authorization: Bearer $CONTEXTIQ_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"baselineScanId\":\"7f3c9a2e-1b44-4e8d-9c2a-5e7d0f1a8b3c\",\"currentScanId\":\"a1d8e4f0-22b7-4c91-8e5a-9f0c1d2b3a4e\"}'\n```\n\nResponse:\n\n```\n{\n  \"baselineScanId\": \"7f3c9a2e-1b44-4e8d-9c2a-5e7d0f1a8b3c\",\n  \"currentScanId\": \"a1d8e4f0-22b7-4c91-8e5a-9f0c1d2b3a4e\",\n  \"verdict\": \"fail\",\n  \"protocols\": {\n    \"mcp\": { \"statusChanged\": false, \"from\": \"confirmed\", \"to\": \"confirmed\", \"itemsRemoved\": [\"search_docs\"] },\n    \"a2a\": { \"statusChanged\": false, \"from\": \"not_detected\", \"to\": \"not_detected\" },\n    \"ard\": { \"statusChanged\": false, \"from\": \"not_detected\", \"to\": \"not_detected\" }\n  },\n  \"summary\": [\"MCP tool(s) removed: search_docs\"]\n}\n```\n\n`verdict` is `pass`, `warn`, or `fail` — a tool or skill disappearing between scans is always a `fail`; something new appearing is a `warn`; no meaningful change is a `pass`. Both `baselineScanId` and `currentScanId` go through the same ownership check as Step 2 — comparing across two different accounts' scans 404s regardless of which side either scan lands on.\n\n## Step 5: Make the Verdict Actually Gate Something\n\nA `200` response with `\"verdict\":\"fail\"` in the body still exits `curl` with status `0` — nothing about a successful HTTP call fails a build on its own. Pipe it through `jq` and check the field explicitly:\n\n```\nRESPONSE=$(curl -sS -X POST https://contextiq.trango-compute.com/api/v1/agent-protocol-inspector/compare \\\n  -H \"Authorization: Bearer $CONTEXTIQ_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\\\"baselineScanId\\\":\\\"$BASELINE_SCAN_ID\\\",\\\"currentScanId\\\":\\\"$CURRENT_SCAN_ID\\\"}\")\n\necho \"$RESPONSE\" | jq .\n\nVERDICT=$(echo \"$RESPONSE\" | jq -r '.verdict')\nif [ \"$VERDICT\" = \"fail\" ]; then\n  echo \"Agent Protocol Inspector: regression detected — failing build.\" >&2\n  exit 1\nfi\n```\n\nDrop that into a post-deploy CI job, with `$BASELINE_SCAN_ID` read from wherever you stored last deploy's scan id, and `$CURRENT_SCAN_ID` from the scan you just ran in Step 3. We cover the reasoning behind the pass/warn/fail rules — and why only `fail` should block a pipeline — in a [separate post on the diff verdict itself](https://contextiq.trango-compute.com/blog/ai-agent-protocol-regression-detection-ci-diff).\n\n## Error Shapes Worth Handling\n\n- `400` — missing or malformed`url` (scan endpoint) or missing`baselineScanId` /`currentScanId` (compare endpoint).\n- `404` — the scanId doesn't exist, has expired, or belongs to a different account.\n- `402` — no API key and no x402 payment attached (see the[x402 tutorial](https://contextiq.trango-compute.com/blog/agent-protocol-inspector-v2-tutorial-mcp-a2a-ard) for the payment flow).\n\nThat's the full loop: scan, store the id, scan again later, diff the two, and gate a pipeline on the result. Get an API key from the [developer dashboard](https://contextiq.trango-compute.com/dashboard/developers) and try it against your own MCP or A2A endpoint.\n\nFollow Trango Compute on LinkedIn\n\nWe post updates on new tools, context engineering patterns, and LLM cost research.\n\n[Follow on LinkedIn](https://www.linkedin.com/company/trango-compute)", "url": "https://wpnews.pro/news/agent-protocol-inspector-api-tutorial-scan-look-up-and-diff-two-scans", "canonical_source": "https://contextiq.trango-compute.com/blog/agent-protocol-inspector-api-tutorial-scan-compare-diff", "published_at": "2026-09-18 00:00:00+00:00", "updated_at": "2026-09-28 15:20:00.533583+00:00", "lang": "en", "topics": ["agent-protocols", "ai-agents", "ai-tools", "developer-tools"], "entities": ["ContextIQ", "Agent Protocol Inspector", "MCP", "A2A", "ARD", "x402-v2"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/agent-protocol-inspector-api-tutorial-scan-look-up-and-diff-two-scans", "markdown": "https://wpnews.pro/news/agent-protocol-inspector-api-tutorial-scan-look-up-and-diff-two-scans.md", "text": "https://wpnews.pro/news/agent-protocol-inspector-api-tutorial-scan-look-up-and-diff-two-scans.txt", "jsonld": "https://wpnews.pro/news/agent-protocol-inspector-api-tutorial-scan-look-up-and-diff-two-scans.jsonld"}}