postman_collection.json

{
  "auth": {
    "bearer": [
      {
        "key": "token",
        "type": "string",
        "value": "{{apiKey}}"
      }
    ],
    "type": "bearer"
  },
  "info": {
    "description": "## Fast start\n\n1. Run the first public demo request for a real, unmetered result.\n2. Run the key-email request, paste the emailed token into `claimToken`, then run the claim request.\n3. The claim test stores `apiKey` and `keyId` locally; authenticated requests then work as shown.\n\n## Result and errors\n\nSaved 200 examples show the first useful fields. `401` means the API key is missing, invalid, or revoked. The service uses `400 invalid_request` for malformed input; client-side schema tooling may show `422` before send. For `429`, honor `Retry-After` and retry with backoff. Share the request ID, never a key.\n\nAll committed secret-bearing variables are empty. Generated from the current route contract.\n\nThis runnable public collection intentionally excludes the provider-only billing webhook and the browser-session subscription, invoice, and payment routes. Those operations require a signed hub request or the dashboard's HttpOnly session and CSRF controls; a bearer API key cannot run them. POST /v1/checkout remains a public no-key prospect path.",
    "name": "ChangeGraph API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Public demo — detect changes without a key",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"subject\": \"Acme Corp\",\n  \"before\": {\n    \"plan.pro.monthly\": \"49\",\n    \"headcount.engineering\": \"120\"\n  },\n  \"after\": {\n    \"plan.pro.monthly\": \"59\",\n    \"headcount.engineering\": \"145\"\n  }\n}"
        },
        "description": "Run first: compares two non-empty string fact maps with the real engine. `eventCount` and `events` are the first useful result; nothing is stored or metered.",
        "header": [],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "demo",
            "detect"
          ],
          "raw": "{{baseUrl}}/v1/demo/detect"
        }
      },
      "response": [
        {
          "_postman_previewlanguage": "json",
          "body": "{\n  \"subject\": \"Acme Corp\",\n  \"eventCount\": 2,\n  \"events\": [\n    {\n      \"id\": \"evt_example_headcount\",\n      \"monitorId\": \"demo\",\n      \"subject\": \"Acme Corp\",\n      \"kind\": \"hiring\",\n      \"direction\": \"increased\",\n      \"factKey\": \"headcount.engineering\",\n      \"before\": \"120\",\n      \"after\": \"145\",\n      \"confidence\": 80,\n      \"summary\": \"Acme Corp: \\\"headcount.engineering\\\" increased from \\\"120\\\" to \\\"145\\\".\",\n      \"evidence\": [\n        {\n          \"source\": \"demo://before\",\n          \"observedAt\": \"2026-09-06T00:00:00.000Z\",\n          \"factKey\": \"headcount.engineering\",\n          \"before\": \"120\",\n          \"after\": null\n        },\n        {\n          \"source\": \"demo://before\",\n          \"observedAt\": \"2026-09-06T00:00:00.000Z\",\n          \"factKey\": \"headcount.engineering\",\n          \"before\": null,\n          \"after\": \"145\"\n        }\n      ],\n      \"detectedAt\": \"2026-09-06T00:00:00.000Z\"\n    },\n    {\n      \"id\": \"evt_example_price\",\n      \"monitorId\": \"demo\",\n      \"subject\": \"Acme Corp\",\n      \"kind\": \"pricing\",\n      \"direction\": \"increased\",\n      \"factKey\": \"plan.pro.monthly\",\n      \"before\": \"49\",\n      \"after\": \"59\",\n      \"confidence\": 80,\n      \"summary\": \"Acme Corp: \\\"plan.pro.monthly\\\" increased from \\\"49\\\" to \\\"59\\\".\",\n      \"evidence\": [\n        {\n          \"source\": \"demo://before\",\n          \"observedAt\": \"2026-09-06T00:00:00.000Z\",\n          \"factKey\": \"plan.pro.monthly\",\n          \"before\": \"49\",\n          \"after\": null\n        },\n        {\n          \"source\": \"demo://before\",\n          \"observedAt\": \"2026-09-06T00:00:00.000Z\",\n          \"factKey\": \"plan.pro.monthly\",\n          \"before\": null,\n          \"after\": \"59\"\n        }\n      ],\n      \"detectedAt\": \"2026-09-06T00:00:00.000Z\"\n    }\n  ],\n  \"requestId\": \"req_example\"\n}",
          "code": 200,
          "cookie": [],
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "name": "200 — two actionable change events",
          "originalRequest": {
            "auth": {
              "type": "noauth"
            },
            "body": {
              "mode": "raw",
              "options": {
                "raw": {
                  "language": "json"
                }
              },
              "raw": "{\n  \"subject\": \"Acme Corp\",\n  \"before\": {\n    \"plan.pro.monthly\": \"49\",\n    \"headcount.engineering\": \"120\"\n  },\n  \"after\": {\n    \"plan.pro.monthly\": \"59\",\n    \"headcount.engineering\": \"145\"\n  }\n}"
            },
            "description": "Run first: compares two non-empty string fact maps with the real engine. `eventCount` and `events` are the first useful result; nothing is stored or metered.",
            "header": [],
            "method": "POST",
            "url": {
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "demo",
                "detect"
              ],
              "raw": "{{baseUrl}}/v1/demo/detect"
            }
          },
          "status": "OK"
        }
      ]
    },
    {
      "name": "Request a free sandbox API key (sends a verification email)",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"email\": \"you@example.com\",\n  \"name\": \"postman\",\n  \"source\": {\n    \"source\": \"postman\",\n    \"medium\": \"collection\",\n    \"campaign\": \"changegraph-postman\",\n    \"content\": \"public-collection\"\n  }\n}"
        },
        "description": "Sends a one-time claim token by email. This request returns 202 and never returns an API key. Attribution: postman / collection / changegraph-postman / public-collection.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys"
          ],
          "raw": "{{baseUrl}}/v1/keys"
        }
      }
    },
    {
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "if (pm.response.code === 201) {",
              "  const body = pm.response.json();",
              "  pm.collectionVariables.set('apiKey', body.apiKey);",
              "  pm.collectionVariables.set('keyId', body.keyId);",
              "  pm.collectionVariables.set('claimToken', '');",
              "}"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "name": "Exchange an emailed claim token for the API key",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"token\": \"{{claimToken}}\"\n}"
        },
        "description": "Paste the emailed token into claimToken and send once. A 201 response is captured into the local apiKey and keyId collection variables; the key is not present in this file.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys",
            "claim"
          ],
          "raw": "{{baseUrl}}/v1/keys/claim"
        }
      }
    },
    {
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "if (pm.response.code === 201) {",
              "  pm.collectionVariables.set('monitorId', pm.response.json().id);",
              "}"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "name": "Create a monitor",
      "request": {
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"subject\": \"Acme Corp\",\n  \"kinds\": [\n    \"pricing\",\n    \"hiring\",\n    \"executive\"\n  ]\n}"
        },
        "description": "Registers a subject to watch. Billed per monitored entity. `kinds` filters server-side, so you only receive the change types you asked for. The test stores the returned id in monitorId for both snapshot requests.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          },
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "monitors"
          ],
          "raw": "{{baseUrl}}/v1/monitors"
        }
      }
    },
    {
      "name": "1. Establish the monitor baseline",
      "request": {
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"source\": \"https://acme.example/pricing\",\n  \"facts\": {\n    \"plan.pro.monthly\": \"49\",\n    \"headcount.engineering\": \"120\"\n  }\n}"
        },
        "description": "Run after Create a monitor. A first snapshot establishes a baseline and emits no events.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          },
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "monitors",
            "{{monitorId}}",
            "snapshots"
          ],
          "raw": "{{baseUrl}}/v1/monitors/{{monitorId}}/snapshots"
        }
      },
      "response": [
        {
          "_postman_previewlanguage": "json",
          "body": "{\n  \"snapshotId\": \"snap_example_baseline\",\n  \"monitorId\": \"mon_example\",\n  \"baseline\": true,\n  \"eventCount\": 0,\n  \"events\": [],\n  \"requestId\": \"req_example\"\n}",
          "code": 201,
          "cookie": [],
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "name": "201 — baseline established",
          "originalRequest": {
            "body": {
              "mode": "raw",
              "options": {
                "raw": {
                  "language": "json"
                }
              },
              "raw": "{\n  \"source\": \"https://acme.example/pricing\",\n  \"facts\": {\n    \"plan.pro.monthly\": \"49\",\n    \"headcount.engineering\": \"120\"\n  }\n}"
            },
            "description": "Run after Create a monitor. A first snapshot establishes a baseline and emits no events.",
            "header": [
              {
                "key": "content-type",
                "value": "application/json"
              },
              {
                "key": "authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "method": "POST",
            "url": {
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "monitors",
                "{{monitorId}}",
                "snapshots"
              ],
              "raw": "{{baseUrl}}/v1/monitors/{{monitorId}}/snapshots"
            }
          },
          "status": "Created"
        }
      ]
    },
    {
      "name": "2. Submit a changed observation",
      "request": {
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"source\": \"https://acme.example/pricing\",\n  \"facts\": {\n    \"plan.pro.monthly\": \"59\",\n    \"headcount.engineering\": \"145\"\n  }\n}"
        },
        "description": "Run after the baseline. `eventCount` and `events` are the useful result.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          },
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "monitors",
            "{{monitorId}}",
            "snapshots"
          ],
          "raw": "{{baseUrl}}/v1/monitors/{{monitorId}}/snapshots"
        }
      },
      "response": [
        {
          "_postman_previewlanguage": "json",
          "body": "{\n  \"snapshotId\": \"snap_example_changed\",\n  \"monitorId\": \"mon_example\",\n  \"baseline\": false,\n  \"eventCount\": 2,\n  \"events\": [\n    {\n      \"id\": \"evt_example_headcount\",\n      \"monitorId\": \"demo\",\n      \"subject\": \"Acme Corp\",\n      \"kind\": \"hiring\",\n      \"direction\": \"increased\",\n      \"factKey\": \"headcount.engineering\",\n      \"before\": \"120\",\n      \"after\": \"145\",\n      \"confidence\": 80,\n      \"summary\": \"Acme Corp: \\\"headcount.engineering\\\" increased from \\\"120\\\" to \\\"145\\\".\",\n      \"evidence\": [\n        {\n          \"source\": \"demo://before\",\n          \"observedAt\": \"2026-09-06T00:00:00.000Z\",\n          \"factKey\": \"headcount.engineering\",\n          \"before\": \"120\",\n          \"after\": null\n        },\n        {\n          \"source\": \"demo://before\",\n          \"observedAt\": \"2026-09-06T00:00:00.000Z\",\n          \"factKey\": \"headcount.engineering\",\n          \"before\": null,\n          \"after\": \"145\"\n        }\n      ],\n      \"detectedAt\": \"2026-09-06T00:00:00.000Z\"\n    },\n    {\n      \"id\": \"evt_example_price\",\n      \"monitorId\": \"demo\",\n      \"subject\": \"Acme Corp\",\n      \"kind\": \"pricing\",\n      \"direction\": \"increased\",\n      \"factKey\": \"plan.pro.monthly\",\n      \"before\": \"49\",\n      \"after\": \"59\",\n      \"confidence\": 80,\n      \"summary\": \"Acme Corp: \\\"plan.pro.monthly\\\" increased from \\\"49\\\" to \\\"59\\\".\",\n      \"evidence\": [\n        {\n          \"source\": \"demo://before\",\n          \"observedAt\": \"2026-09-06T00:00:00.000Z\",\n          \"factKey\": \"plan.pro.monthly\",\n          \"before\": \"49\",\n          \"after\": null\n        },\n        {\n          \"source\": \"demo://before\",\n          \"observedAt\": \"2026-09-06T00:00:00.000Z\",\n          \"factKey\": \"plan.pro.monthly\",\n          \"before\": null,\n          \"after\": \"59\"\n        }\n      ],\n      \"detectedAt\": \"2026-09-06T00:00:00.000Z\"\n    }\n  ],\n  \"requestId\": \"req_example\"\n}",
          "code": 201,
          "cookie": [],
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "name": "201 — two changes detected",
          "originalRequest": {
            "body": {
              "mode": "raw",
              "options": {
                "raw": {
                  "language": "json"
                }
              },
              "raw": "{\n  \"source\": \"https://acme.example/pricing\",\n  \"facts\": {\n    \"plan.pro.monthly\": \"59\",\n    \"headcount.engineering\": \"145\"\n  }\n}"
            },
            "description": "Run after the baseline. `eventCount` and `events` are the useful result.",
            "header": [
              {
                "key": "content-type",
                "value": "application/json"
              },
              {
                "key": "authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "method": "POST",
            "url": {
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "monitors",
                "{{monitorId}}",
                "snapshots"
              ],
              "raw": "{{baseUrl}}/v1/monitors/{{monitorId}}/snapshots"
            }
          },
          "status": "Created"
        }
      ]
    },
    {
      "name": "Read detected change events, newest first",
      "request": {
        "description": "Optional `limit` query parameter, 1-500, default 50. Free — reading your own events consumes no quota.",
        "header": [
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "monitors",
            "{{monitorId}}",
            "events"
          ],
          "raw": "{{baseUrl}}/v1/monitors/{{monitorId}}/events"
        }
      }
    },
    {
      "name": "Liveness and deployed version",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "header": [],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "health"
          ],
          "raw": "{{baseUrl}}/health"
        }
      }
    },
    {
      "name": "Service index — endpoints, auth and error format",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "header": [],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [],
          "raw": "{{baseUrl}}/"
        }
      }
    },
    {
      "name": "List your monitors",
      "request": {
        "description": "Every monitor on your account for this API. Free — reading your own monitors consumes no quota.",
        "header": [
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "monitors"
          ],
          "raw": "{{baseUrl}}/v1/monitors"
        }
      }
    },
    {
      "name": "Start a hosted Square checkout for a paid tier",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"tier\": \"developer\"\n}"
        },
        "description": "Returns a Square-hosted payment URL for the requested tier. No API key is needed — a prospect has not got one yet. The email Square collects becomes the account, so a key issued later for the same address inherits the paid quota. Enterprise returns a contact route rather than a payment link. THIS IS THE PATH FOR SOMEONE WHO IS NOT YET PAYING. It starts a NEW Square recurring subscription, so it is refused with 409 `conflict` (`details.reason` `existing_subscription`) when the request carries a dashboard session for an account that already has a live plan on this API — a second subscription would be charged alongside the first, every month, and this API cannot cancel either one. Change tier with POST /v1/subscription/plan, or, when Square collects your base fee, cancel it with Square first.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "checkout"
          ],
          "raw": "{{baseUrl}}/v1/checkout"
        }
      }
    },
    {
      "name": "List your API keys for this API",
      "request": {
        "description": "Every key on YOUR account for this API — label, non-secret prefix, status, when it was created, when it was last used, and what it has consumed this period. Authenticate with any active key on the account; the account is taken from that key, never from a parameter, so this can only ever return your own keys. Keys you hold for other APIs in the portfolio are not listed here. Secrets are not returned and cannot be: only a peppered hash is stored. Free, and consumes no quota.",
        "header": [
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys"
          ],
          "raw": "{{baseUrl}}/v1/keys"
        }
      }
    },
    {
      "name": "Revoke one of your API keys",
      "request": {
        "description": "Kills a key immediately: the very next request made with it is refused with 401 invalid_api_key. There is no propagation delay and no cache to wait out. You may revoke the key you are authenticating with — that is the correct move when it has leaked, though you will then need another key, or the email flow, to get back in; rotate does both in one call. A key belonging to another account, or to another API, answers 404 exactly as an unknown id does, so this cannot be used to probe for keys you do not own. Idempotent, and free.",
        "header": [
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys",
            "{{keyId}}",
            "revoke"
          ],
          "raw": "{{baseUrl}}/v1/keys/{{keyId}}/revoke"
        }
      }
    },
    {
      "name": "Replace one of your API keys with a new secret",
      "request": {
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"name\": \"production (rotated)\"\n}"
        },
        "description": "Issues a replacement key and revokes the old one. This is the answer to a leaked or lost key: the new secret is returned once, the old secret stops working immediately, and the label carries over unless you supply a new one. The replacement is issued at your account's current allowance — your paid plan if you have one — not at the old key's. Rotating does not count against the active-key limit, because it replaces rather than adds. Free, and it works while you are out of quota.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          },
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys",
            "{{keyId}}",
            "rotate"
          ],
          "raw": "{{baseUrl}}/v1/keys/{{keyId}}/rotate"
        }
      }
    },
    {
      "name": "Your consumption and remaining allowance for this period",
      "request": {
        "description": "Reports what YOUR ACCOUNT has consumed in the current quota period, the ceiling being enforced against it, and when that ceiling resets. The allowance belongs to the account, not to a key: every key you hold for this API draws on the same budget, so \"used\" is the total across all of them and a new key does not arrive with a fresh one. Free, and it consumes no quota, so it still answers once you are getting 429 quota_exceeded — which is the point: compare \"used\" against \"ceiling\" and read \"period.resetsAt\" to tell a period you have simply exhausted from a plan that is no longer active, which shows as a \"status\" of canceled and a ceiling of 0. \"used\" counts billing units (see \"unit\"), not HTTP requests: a single request can consume several. All money is in integer minor units (cents), never a decimal. The period reported here is the quota period — the calendar month in UTC, resetting at 00:00 UTC on the 1st. Your invoice window is anchored to the date you subscribed and is a different window; the amounts here are what this period’s usage has accrued so far, not a bill.",
        "header": [
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "usage"
          ],
          "raw": "{{baseUrl}}/v1/usage"
        }
      }
    }
  ],
  "variable": [
    {
      "key": "baseUrl",
      "type": "string",
      "value": "https://changegraph-api.com"
    },
    {
      "description": "Set automatically after a successful claim; stored only in your local Postman collection.",
      "key": "apiKey",
      "type": "string",
      "value": ""
    },
    {
      "description": "Paste the one-time token from the verification email; never commit a real value.",
      "key": "claimToken",
      "type": "string",
      "value": ""
    },
    {
      "description": "Set automatically after claim for rotate/revoke requests.",
      "key": "keyId",
      "type": "string",
      "value": ""
    },
    {
      "description": "Set automatically after creating a monitor; never use a literal placeholder ID.",
      "key": "monitorId",
      "type": "string",
      "value": ""
    }
  ]
}