New Bring your own storage. Keep your diagrams in your own private GitHub repository, on Pro and Team.Bring your own storage on GitHub, for Pro and Team. Learn more about bring your own storage

All examples

API dependency map from OpenAPI specs

Build a diagram of which services expose, consume, and depend on which APIs from OpenAPI specs and SDK imports, then patch it with typed operations instead of redrawing it.

architecture OpenAPI specs / SDK imports scangenerateupdate

What this example shows

A directed graph of HTTP / SDK dependencies between services, with edge labels showing the actual endpoint or SDK call rather than abstract “depends on” arrows. The “Web App” and “Mobile App” hit the gateway, the gateway fans out to auth / users / orders / catalog APIs, internal services call each other (orders → billing, orders → users, catalog → search), and external SDK integrations (Stripe, SendGrid) sit at the edge of the graph.

When to use it

When your platform has more than ~10 services and “who calls whom” is no longer something a single engineer holds in their head. The diagram is invaluable for: scoping deprecation work (who’d be affected if we sunset Catalog?), auditing third-party data exposure (which services hand data to which vendors?), incident scoping (when Billing is down, what else fails?), and onboarding (here’s the call graph; here’s the entry points).

What the agent does

The agent scans the OpenAPI specs in your repo (and / or grep for SDK imports - import Stripe from "stripe"), builds the directed call graph, then applies typed operations to the persisted scene. New endpoints become new edge labels; new services become nodes; deprecated endpoints disappear from the graph. Each change is a new revision, so the diagram is never rebuilt from scratch.

Edge labels show the actual endpoint where space allows (“POST /v1/login”, “GET /users/:id”) rather than abstract direction. For high-cardinality calls (e.g. dozens of REST endpoints between gateway and a single service), the agent collapses them to a representative (“REST”) to keep the diagram readable.

What the output includes

  • A directed call graph with stable element IDs across runs (the same service keeps the same elementId every time).
  • Edge labels showing endpoint paths or SDK names - readers learn the integration shape from the diagram alone.
  • External systems (Stripe, SendGrid, etc.) visually distinct via the externalSystem node type.
  • Auto-layout via layoutStrategy: { direction: "LR" } - the agent never hand-positions; the engine figures it out.
  • Synthesized background bands grouping nodes by nodeType via extensions.autoGroup: "byNodeType" at the top of the document - the engine emits subtle “Services” and “External Systems” regions so the reader scans the call graph as a layered architecture instead of a flat blob of floating shapes.
  • A revision history showing how the API surface evolved (which endpoints existed when).

Rendered diagram

API dependency map from OpenAPI specs - rendered diagram

Open full size

Drawn by Zindex from the scene below with POST /v1/diagrams/preview. Open it in the Playground to swap themes (clean / dark / blueprint / sketch), or add format: "png" to the same request for a PNG.

Scene JSON

Raw

The DSP scene the diagram above is drawn from. Open it in the Playground, or send it as scene to POST /v1/diagrams/preview to draw it yourself.

{
  "schemaVersion": "0.1",
  "diagramFamily": "architecture",
  "scene": {
    "id": "api-dependency-map",
    "title": "API Dependency Map",
    "brief": "Which services call which: the web and mobile apps, the API gateway, the internal APIs and the third parties they use.\nBuilt from each service's OpenAPI spec and SDK imports; change it with edits from those, keeping element IDs, never by starting over. Edges run from caller to callee, labeled with the call (method and path), REST or the SDK's name. Third parties are external systems. Keep the left-to-right layout: clients, gateway, then services.",
    "units": "px",
    "canvas": {
      "width": 1200,
      "height": 600
    }
  },
  "extensions": {
    "autoGroup": "byNodeType"
  },
  "layoutStrategy": {
    "direction": "LR",
    "nodeSpacing": 60,
    "rankSpacing": 130
  },
  "elements": [
    {
      "id": "web",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Web App",
      "icon": "lucide:monitor"
    },
    {
      "id": "mobile",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Mobile App",
      "icon": "lucide:smartphone"
    },
    {
      "id": "gateway",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "API Gateway",
      "icon": "lucide:network"
    },
    {
      "id": "auth_api",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Auth API",
      "icon": "lucide:lock"
    },
    {
      "id": "users_api",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Users API",
      "icon": "lucide:users"
    },
    {
      "id": "orders_api",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Orders API",
      "icon": "lucide:package"
    },
    {
      "id": "catalog_api",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Catalog API",
      "icon": "lucide:boxes"
    },
    {
      "id": "billing_api",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Billing API",
      "icon": "lucide:credit-card"
    },
    {
      "id": "search_api",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Search API",
      "icon": "lucide:search"
    },
    {
      "id": "stripe",
      "kind": "node",
      "nodeType": "externalSystem",
      "shape": "roundedRect",
      "label": "Stripe",
      "icon": "lucide:external-link"
    },
    {
      "id": "sendgrid",
      "kind": "node",
      "nodeType": "externalSystem",
      "shape": "roundedRect",
      "label": "SendGrid",
      "icon": "lucide:mail"
    },
    {
      "id": "e_web_gw",
      "kind": "edge",
      "from": {
        "elementId": "web"
      },
      "to": {
        "elementId": "gateway"
      },
      "label": "REST",
      "router": "orthogonal"
    },
    {
      "id": "e_mob_gw",
      "kind": "edge",
      "from": {
        "elementId": "mobile"
      },
      "to": {
        "elementId": "gateway"
      },
      "label": "REST",
      "router": "orthogonal"
    },
    {
      "id": "e_gw_auth",
      "kind": "edge",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "auth_api"
      },
      "label": "POST /v1/login",
      "router": "orthogonal"
    },
    {
      "id": "e_gw_users",
      "kind": "edge",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "users_api"
      },
      "label": "GET /v1/users",
      "router": "orthogonal"
    },
    {
      "id": "e_gw_orders",
      "kind": "edge",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "orders_api"
      },
      "label": "REST",
      "router": "orthogonal"
    },
    {
      "id": "e_gw_catalog",
      "kind": "edge",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "catalog_api"
      },
      "label": "REST",
      "router": "orthogonal"
    },
    {
      "id": "e_orders_billing",
      "kind": "edge",
      "from": {
        "elementId": "orders_api"
      },
      "to": {
        "elementId": "billing_api"
      },
      "label": "POST /charge",
      "router": "orthogonal"
    },
    {
      "id": "e_orders_users",
      "kind": "edge",
      "from": {
        "elementId": "orders_api"
      },
      "to": {
        "elementId": "users_api"
      },
      "label": "GET /users/:id",
      "router": "orthogonal"
    },
    {
      "id": "e_catalog_search",
      "kind": "edge",
      "from": {
        "elementId": "catalog_api"
      },
      "to": {
        "elementId": "search_api"
      },
      "label": "POST /index",
      "router": "orthogonal"
    },
    {
      "id": "e_billing_stripe",
      "kind": "edge",
      "from": {
        "elementId": "billing_api"
      },
      "to": {
        "elementId": "stripe"
      },
      "label": "Stripe SDK",
      "router": "orthogonal"
    },
    {
      "id": "e_orders_sendgrid",
      "kind": "edge",
      "from": {
        "elementId": "orders_api"
      },
      "to": {
        "elementId": "sendgrid"
      },
      "label": "SendGrid SDK",
      "router": "orthogonal"
    }
  ]
}

Agent workflow

Build a diagram of which services expose, consume, and depend on which APIs by parsing OpenAPI specs and SDK imports across the repository, then change the saved Zindex diagram with typed operations when the API topology changes.

Inputs

  • Glob of OpenAPI spec files in the monorepo (e.g. services/*/openapi.yaml)
  • Glob of source files that import generated SDKs (used to derive consumer→provider edges)
  • The diagram's Zindex key or ID
  • A Zindex API key, or an MCP client signed in to Zindex

Outputs

  • A new revision of the diagram with one node per service and one edge per cross-service call
  • Rendered SVG showing the current API topology
  • A compare listing newly added consumers / providers since the last run
  1. 01

    Create or read the diagram

    On the first run, save the parsed map with diagram_create, a hierarchical LR layoutStrategy, a key such as api-dependency-map and a brief whose first line says what the map shows; Zindex mints the ID; the key is how later runs find it, and the brief's first line is what a search shows. Repeating the same create returns the existing diagram, so a retry never makes a copy. On later runs, read it by key with diagram_get instead.

    diagram_create POST /v1/diagrams
  2. 02

    Parse OpenAPI specs

    Walk every services/*/openapi.yaml in the monorepo. Each spec becomes a service node; emit operationIds + paths so they can later become edge labels (e.g. 'POST /v1/login'). Do not parse free-text README links - the spec is the source of truth.

  3. 03

    Derive consumer→provider edges

    Scan source files for imports of generated SDKs (e.g. import { usersClient } from '@acme/sdk-users'). Each import is evidence that the importing service consumes the imported API. Map the SDK package name back to the spec → an edge from consumer to provider, labeled with the most-frequently-called operationId.

  4. 04

    Diff the parsed topology against the diagram

    Read the diagram's outline: its first line gives the current revision, and each line after it gives a service or an edge with its label. New services become createNode ops; removed services become deleteElement ops; changed labels become updateEdge ops. Always reuse stable element ids (the service name) so a renamed label stays on the same edge.

    diagram_get GET /v1/diagrams/${SCENE_ID}
  5. 05

    Save the changes as one edit

    Send the diff as one diagram_edit with baseRevision set to the revision you read and a message that says what changed. The edit is all or nothing: if an operation has errors, it returns VALIDATION_FAILED and saves nothing. Reuse stable element ids - users_api, orders_api, e_orders_users - so renames update the existing element rather than create a duplicate.

    diagram_edit POST /v1/diagrams/${SCENE_ID}/revisions
  6. 06

    Fix what the warnings report

    The edit's warnings list what checking and drawing the new revision noticed, each with a code, the element when there is one, and a one-line fix. The edit above returns LABEL_DUPLICATION_DETECTED because e_gw_orders and e_gw_catalog both say 'REST'. That is expected where many calls are collapsed to 'REST'; anywhere else, give each edge its own label in a follow-up edit.

  7. 07

    Render the new revision

    Get SVG and PNG links to the new revision; they work without a key for 7 days. The hierarchical LR layout naturally separates clients (left), gateway (center), and provider APIs (right); cloud-icon services render icon-only and read cleanly inside the layout.

    diagram_render GET /v1/diagrams/${SCENE_ID}/render
  8. 08

    List what changed since the last run

    Compare the revision you started from with the new one: the result lists the element IDs added, changed and removed. New or removed services and calls are the cross-service dependencies worth telling the team about.

    diagram_history GET /v1/diagrams/${SCENE_ID}/compare?from=${PREV_REVISION}
  9. 09

    Publish the rendered SVG to the docs site

    Download the SVG from its link and upload it to the docs site (or commit it to the repo's docs/ directory). When the compare lists added or removed services, post a Slack message to the platform channel so the team is aware of the new dependency.

MCP recipe

For agents using Model Context Protocol. The tool sequence below matches the workflow steps; copy the prompt as a system message.

Tool sequence

  1. 01 diagram_create Create or read the diagram
  2. 02 diagram_get Diff the parsed topology against the diagram
  3. 03 diagram_edit Save the changes as one edit
  4. 04 diagram_render Render the new revision
  5. 05 diagram_history List what changed since the last run

Unique tools used: diagram_create, diagram_get, diagram_edit, diagram_render, diagram_history.

Copyable agent prompt

Drop this verbatim into a system prompt for an MCP-connected agent. The Zindex MCP server at https://api.zindex.ai/mcp exposes the tools the prompt references (connect a client), and so does the npm package @zindexai/mcp, which forwards to it.

You maintain the API dependency map that the platform team keeps in Zindex: one diagram of which services expose, consume and depend on which APIs across the organization's microservices. When asked to update it, you parse the OpenAPI specs and SDK imports in the monorepo and change the diagram with typed edits, each with a message saying what changed. Every revision is kept, so anyone can open the map as it was on any date.

The diagram's Zindex ID is `${SCENE_ID}`; it already exists. Each update computes the smallest valid set of typed operations that move the diagram from its current revision to one that matches what you parsed. If nothing changed, send nothing; an edit that changes nothing makes no revision anyway.

Steps for each update:

1. Walk every `services/*/openapi.yaml` in the monorepo. Each spec corresponds to one service node - use the spec's `info.title` (or the directory name) as the stable element id. Capture the operationIds and paths so they can become edge labels.

2. Walk every source file in the monorepo and look for imports of generated SDK packages (`@acme/sdk-users`, `@acme/sdk-orders`, …). Each import is evidence that the importing service consumes the imported API. Build a `(consumer_service_id, provider_service_id, operationId)` tuple for the most-frequently-called operation between each pair.

3. Call `diagram_get({ id: "${SCENE_ID}" })`. The outline's first line gives the current revision, and each line after it gives a service (ID, type, label) or an edge (`id: from -> to "label"`). Diff what you parsed against it: new services → `createNode`, removed services → `deleteElement`, new edges → `createEdge`, removed edges → `deleteElement`, changed edge labels → `updateEdge`.

4. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision, message, ops })` with one batch, `baseRevision` set to the revision you read. The edit is all or nothing. Reuse stable element ids - `users_api`, `orders_api`, `e_orders_billing` - so a renamed service or relabeled edge stays on the same element rather than producing a delete+create. Pass a meaningful `message` like "add billing-api spec; new e_orders_billing edge from POST /charge". If the call returns `REVISION_CONFLICT`, the map changed after you read it: the error lists what changed, so re-plan against the new revision.

5. An edit with errors returns `VALIDATION_FAILED` and saves nothing. A saved edit returns `warnings`: what checking and drawing the new revision noticed, each with a `code`, the `element` when there is one, and a one-line `fix`. `LABEL_DUPLICATION_DETECTED` means edges that start or end at one service share a label, which is expected where you collapsed many calls to 'REST' and worth fixing anywhere else. `EDGE_COLUMN_NOT_FOUND` should not appear here; if it does, an edge is using ER-family `column` anchors by mistake and needs `from/to.elementId` only. Fix the rest with a follow-up edit.

6. Call `diagram_render({ id: "${SCENE_ID}" })`. It returns SVG and PNG links to the new revision, valid for 7 days. Download the SVG and publish it to the docs site (or commit it to `docs/architecture/api-topology.svg`). The image prints its address, `zindex.ai/d/<id>@<revision>`, and date, so the published image is traceable back to its revision.

7. Call `diagram_history({ id: "${SCENE_ID}", compare: { from: PREV_REVISION } })`; it lists the element IDs added, changed and removed since then. If it contains added or removed services (new providers or consumers), post a short Slack message to the platform channel summarizing the change so the team is aware of the new cross-service dependency.

Hard rules: never hand-edit the rendered SVG; always edit the diagram with `diagram_edit` and render again. Never recreate the diagram from scratch; always patch with stable ids - the topology is a long-lived, evolving graph, and stable ids are what make revision history meaningful. Treat the OpenAPI specs as the source of truth; if a spec contradicts a free-text comment elsewhere, follow the spec.

HTTP API recipe

For agents/devs not using MCP. Send Authorization: Bearer $ZINDEX_API_KEY on every call except POST /v1/diagrams/validate and POST /v1/diagrams/preview, which need no key. In the paths, ${SCENE_ID} is the diagram's ID, or the key you gave it in diagram_create. Full reference: REST API, OpenAPI spec.

  1. 01 POST /v1/diagrams

    On the first run, save the parsed map with diagram_create, a hierarchical LR layoutStrategy, a key such as api-dependency-map and a brief whose first line says what the map shows; Zindex mints the ID; the key is how later runs find it, and the brief's first line is what a search shows. Repeating the same create returns the existing diagram, so a retry never makes a copy. On later runs, read it by key with diagram_get instead.

    Example response

    {
      "id": "dgm_bsEyV7SiWCoa",
      "key": "api-dependency-map",
      "revision": 1,
      "hash": "sha256:8f15604a40c52b5fdaa36cf2992d6e34c1b96827acb4a424ca1093d60496bd7a",
      "chain": "sha256:ae53b52766b548119dd31da2fae87501de567d41cf3cc3d9371b72df7611f733",
      "warnings": [
        {
          "code": "LABEL_DUPLICATION_DETECTED",
          "fix": "Edges e_gw_orders, e_gw_catalog share the label 'REST': merge them or give each its own label."
        }
      ],
      "created": true
    }
  2. 02 GET /v1/diagrams/${SCENE_ID}

    Read the diagram's outline: its first line gives the current revision, and each line after it gives a service or an edge with its label. New services become createNode ops; removed services become deleteElement ops; changed labels become updateEdge ops. Always reuse stable element ids (the service name) so a renamed label stays on the same edge.

    Example response

    {
      "id": "dgm_bsEyV7SiWCoa",
      "revision": 1,
      "text": "dgm_bsEyV7SiWCoa \"API Dependency Map\" r1 2026-10-31T18:21Z sha256:8f15604a40c5\nkey: api-dependency-map\nbrief: Which services call which: the web and mobile apps, the API gateway, the internal APIs and the third parties they use.\n  Built from each service's OpenAPI spec and SDK imports; change it with edits from those, keeping element IDs, never by starting over. Edges run from caller to callee, labeled with the call (method and path), REST or the SDK's name. Third parties are external systems. Keep the left-to-right layout: clients, gateway, then services.\nrecent: r1 curl/8.7.1 \"First map from the OpenAPI specs\"\noutline: 10 nodes, 9 edges\n  web service \"Web App\"\n  mobile service \"Mobile App\"\n  gateway service \"API Gateway\"\n  auth_api service \"Auth API\"\n  users_api service \"Users API\"\n  orders_api service \"Orders API\"\n  catalog_api service \"Catalog API\"\n  search_api service \"Search API\"\n  stripe externalSystem \"Stripe\"\n  sendgrid externalSystem \"SendGrid\"\n  e_web_gw: web -> gateway \"REST\"\n  e_mob_gw: mobile -> gateway \"REST\"\n  e_gw_auth: gateway -> auth_api \"POST /v1/login\"\n  e_gw_users: gateway -> users_api \"GET /v1/users\"\n  e_gw_orders: gateway -> orders_api \"REST\"\n  e_gw_catalog: gateway -> catalog_api \"REST\"\n  e_orders_users: orders_api -> users_api \"GET /users/:id\"\n  e_catalog_search: catalog_api -> search_api \"POST /index\"\n  e_orders_sendgrid: orders_api -> sendgrid \"SendGrid SDK\""
    }
  3. 03 POST /v1/diagrams/${SCENE_ID}/revisions

    Send the diff as one diagram_edit with baseRevision set to the revision you read and a message that says what changed. The edit is all or nothing: if an operation has errors, it returns VALIDATION_FAILED and saves nothing. Reuse stable element ids - users_api, orders_api, e_orders_users - so renames update the existing element rather than create a duplicate.

    Example request body

    {
      "baseRevision": 1,
      "message": "add billing-api spec; new e_orders_billing edge from POST /charge",
      "ops": [
        {
          "op": "createNode",
          "id": "billing_api",
          "nodeType": "service",
          "shape": "roundedRect",
          "label": "Billing API",
          "icon": "lucide:credit-card"
        },
        {
          "op": "createEdge",
          "id": "e_orders_billing",
          "from": {
            "elementId": "orders_api"
          },
          "to": {
            "elementId": "billing_api"
          },
          "label": "POST /charge",
          "router": "orthogonal"
        },
        {
          "op": "createEdge",
          "id": "e_billing_stripe",
          "from": {
            "elementId": "billing_api"
          },
          "to": {
            "elementId": "stripe"
          },
          "label": "Stripe SDK",
          "router": "orthogonal"
        }
      ]
    }

    Example response

    {
      "id": "dgm_bsEyV7SiWCoa",
      "revision": 2,
      "hash": "sha256:5ebe42a5b03af394e3a95b0613231d95c2292a1d90aa99ed2aa89cf886e5849f",
      "chain": "sha256:dba03555fc519a023f18cf3f768ad8506d0350ee56094bcec913c10f8e150054",
      "warnings": [
        {
          "code": "LABEL_DUPLICATION_DETECTED",
          "fix": "Edges e_gw_orders, e_gw_catalog share the label 'REST': merge them or give each its own label."
        }
      ],
      "changed": {
        "added": [
          "billing_api",
          "e_orders_billing",
          "e_billing_stripe"
        ],
        "updated": [],
        "removed": []
      }
    }
  4. 04 GET /v1/diagrams/${SCENE_ID}/render

    Get SVG and PNG links to the new revision; they work without a key for 7 days. The hierarchical LR layout naturally separates clients (left), gateway (center), and provider APIs (right); cloud-icon services render icon-only and read cleanly inside the layout.

    Example response

    {
      "id": "dgm_bsEyV7SiWCoa",
      "title": "API Dependency Map",
      "revision": 2,
      "latest": 2,
      "savedAt": "2026-10-31T18:21:45.100Z",
      "hash": "sha256:5ebe42a5b03af394e3a95b0613231d95c2292a1d90aa99ed2aa89cf886e5849f",
      "chain": "sha256:dba03555fc519a023f18cf3f768ad8506d0350ee56094bcec913c10f8e150054",
      "engine": "8.11.0+build.2597",
      "svg": "https://api.zindex.ai/v1/images/dgm_bsEyV7SiWCoa@2.svg?e=1794075705&s=...",
      "png": "https://api.zindex.ai/v1/images/dgm_bsEyV7SiWCoa@2.png?e=1794075705&s=...",
      "expires": "2026-11-07T18:21:45.000Z",
      "width": 1119,
      "height": 903
    }
  5. 05 GET /v1/diagrams/${SCENE_ID}/compare?from=${PREV_REVISION}

    Compare the revision you started from with the new one: the result lists the element IDs added, changed and removed. New or removed services and calls are the cross-service dependencies worth telling the team about.

    Example response

    {
      "id": "dgm_bsEyV7SiWCoa",
      "from": 1,
      "to": 2,
      "added": [
        "billing_api",
        "e_orders_billing",
        "e_billing_stripe"
      ],
      "changed": [],
      "removed": [],
      "scene": [],
      "authors": [
        {
          "by": null,
          "client": "curl/8.7.1"
        }
      ]
    }

Operations

Raw

The typed operations that build this diagram from empty. Save an empty diagram with diagram_create, then send the envelope's baseRevision, message and ops to diagram_edit, or POST /v1/diagrams/{id}/revisions. Each op carries a stable id so subsequent runs can update the same elements instead of regenerating.

  • 22 operations
  • 11 createEdge, 11 createNode
{
  "schemaVersion": "0.1",
  "sceneId": "api-dependency-map",
  "baseRevision": 1,
  "message": "Initial API dependency map: clients, gateway, internal APIs, external systems",
  "ops": [
    {
      "op": "createNode",
      "id": "web",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Web App",
      "icon": "lucide:monitor"
    },
    {
      "op": "createNode",
      "id": "mobile",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Mobile App",
      "icon": "lucide:smartphone"
    },
    {
      "op": "createNode",
      "id": "gateway",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "API Gateway",
      "icon": "lucide:network"
    },
    {
      "op": "createNode",
      "id": "auth_api",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Auth API",
      "icon": "lucide:lock"
    },
    {
      "op": "createNode",
      "id": "users_api",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Users API",
      "icon": "lucide:users"
    },
    {
      "op": "createNode",
      "id": "orders_api",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Orders API",
      "icon": "lucide:package"
    },
    {
      "op": "createNode",
      "id": "catalog_api",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Catalog API",
      "icon": "lucide:boxes"
    },
    {
      "op": "createNode",
      "id": "billing_api",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Billing API",
      "icon": "lucide:credit-card"
    },
    {
      "op": "createNode",
      "id": "search_api",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Search API",
      "icon": "lucide:search"
    },
    {
      "op": "createNode",
      "id": "stripe",
      "nodeType": "externalSystem",
      "shape": "roundedRect",
      "label": "Stripe",
      "icon": "lucide:external-link"
    },
    {
      "op": "createNode",
      "id": "sendgrid",
      "nodeType": "externalSystem",
      "shape": "roundedRect",
      "label": "SendGrid",
      "icon": "lucide:mail"
    },
    {
      "op": "createEdge",
      "id": "e_web_gw",
      "from": {
        "elementId": "web"
      },
      "to": {
        "elementId": "gateway"
      },
      "label": "REST",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_mob_gw",
      "from": {
        "elementId": "mobile"
      },
      "to": {
        "elementId": "gateway"
      },
      "label": "REST",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_gw_auth",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "auth_api"
      },
      "label": "POST /v1/login",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_gw_users",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "users_api"
      },
      "label": "GET /v1/users",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_gw_orders",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "orders_api"
      },
      "label": "REST",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_gw_catalog",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "catalog_api"
      },
      "label": "REST",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_orders_billing",
      "from": {
        "elementId": "orders_api"
      },
      "to": {
        "elementId": "billing_api"
      },
      "label": "POST /charge",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_orders_users",
      "from": {
        "elementId": "orders_api"
      },
      "to": {
        "elementId": "users_api"
      },
      "label": "GET /users/:id",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_catalog_search",
      "from": {
        "elementId": "catalog_api"
      },
      "to": {
        "elementId": "search_api"
      },
      "label": "POST /index",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_billing_stripe",
      "from": {
        "elementId": "billing_api"
      },
      "to": {
        "elementId": "stripe"
      },
      "label": "Stripe SDK",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_orders_sendgrid",
      "from": {
        "elementId": "orders_api"
      },
      "to": {
        "elementId": "sendgrid"
      },
      "label": "SendGrid SDK",
      "router": "orthogonal"
    }
  ]
}

Validation

Valid

Captured response from POST /v1/diagrams/validate, the check diagram_validate runs. It checks the scene and draws it. Every code it can return is in the validation rules.

  • 0 errors
  • 1 warning
  • warning LABEL_DUPLICATION_DETECTED

    Edges e_gw_orders, e_gw_catalog share the label 'REST': merge them or give each its own label.

Each entry has a code, the element it concerns when there is one, and a one-line fix. diagram_create and diagram_edit save nothing when there are errors and return VALIDATION_FAILED; warnings don't block a save. Both return the same warnings for the revision they save, so an agent reads them from the write itself.

Revision diff

Raw

What changed between two revisions of the diagram, as diagram_history returns it with compare. Every revision is kept, so any two can be compared, by revision number or by date.

Scenario

The map's first save. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so every service and call is added and nothing is changed or removed. Each later update compares the same way and names only what it changed, such as a new API and the calls to it, which is quicker to review than re-reading the OpenAPI specs.

  • Revision 1 → 2
  • +22 added
  • -0 removed
  • ~0 changed

+ Added

  • web
  • mobile
  • gateway
  • auth_api
  • users_api
  • orders_api
  • catalog_api
  • billing_api
  • search_api
  • stripe
  • sendgrid
  • e_web_gw
  • e_mob_gw
  • e_gw_auth
  • e_gw_users
  • e_gw_orders
  • e_gw_catalog
  • e_orders_billing
  • e_orders_users
  • e_catalog_search
  • e_billing_stripe
  • e_orders_sendgrid

Raw compare response

{
  "id": "dgm_jivBZnikoXjM",
  "from": 1,
  "to": 2,
  "added": [
    "web",
    "mobile",
    "gateway",
    "auth_api",
    "users_api",
    "orders_api",
    "catalog_api",
    "billing_api",
    "search_api",
    "stripe",
    "sendgrid",
    "e_web_gw",
    "e_mob_gw",
    "e_gw_auth",
    "e_gw_users",
    "e_gw_orders",
    "e_gw_catalog",
    "e_orders_billing",
    "e_orders_users",
    "e_catalog_search",
    "e_billing_stripe",
    "e_orders_sendgrid"
  ],
  "changed": [],
  "removed": [],
  "scene": [],
  "scenario": "The map's first save. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so every service and call is added and nothing is changed or removed. Each later update compares the same way and names only what it changed, such as a new API and the calls to it, which is quicker to review than re-reading the OpenAPI specs."
}

To compare two versions of your own diagram, call diagram_history with compare: { from, to }, or GET /v1/diagrams/{id}/compare with from and to, giving revision numbers or dates. With an API key, GET /v1/images/{id}@{to}.svg?from={from} draws the later version with what changed colored.

Agent resources

Machine-readable versions of this example. Agents should fetch these rather than scrape the rendered HTML.

  • api-dependency-map.scene.json Canonical DSP scene Open
  • api-dependency-map.ops.json Typed-operation envelope that builds the scene Open
  • api-dependency-map.workflow.json Structured agent workflow (goal, inputs, outputs, steps) Open
  • api-dependency-map.diff.json Sample diagram_history compare response Open
  • api-dependency-map.svg Rendered diagram Open
  • api-dependency-map.md Agent-readable markdown summary Open
  • /examples/index.json Manifest of all examples (cross-linked) Open