[numarasSigmaSoftware]

Change

Regenerate docs/api/openapi.json with scripts/generate_openapi.py against current main, and add a drift test so it cannot fall behind again.

What the regeneration picks up, classified from the JSON diff rather than by hand:

• The operator key route POST /auth/api-keys/operator and its request schema (Cleans up operator key management #59).
• Operator-auth header parameters on 17 admin paths (Require operator credentials on the admin surface (REST + MCP) #39).
• Description-only updates on 7 paths, several of them buyer-facing: quotes, deals, change requests, negotiation messages, order transition.
• The required idempotency_key on change-request creation (fix: enforce idempotency for change requests #64) and on quotes (fix: enforce idempotency on POST /api/v1/quotes, add conflict detection #50).
• exclusiveMinimum on RateCardEntry.base_cpm (feat: wire the operator rate card into pricing (issue #69) #78).
• The deal list route GET /api/v1/deals (feat: list stored deals over REST and make export read them #84), picked up by merging main after that PR landed.

The regenerated document counts 89 operations. The six hand-written pages that said 87 now say 89; the delta is the operator-key route and the deal list route above. The README group table had not moved with the total (its rows summed to 87); Authentication now counts 5 and Deal Booking 12, so the rows sum to 89.

tests/unit/test_openapi_drift.py builds the document from the app the same way the script does and compares parsed JSON to the committed file, with the regeneration command in the failure message. Modeled on test_docs_inventory_drift.py, which already guards the endpoint and tool inventories. The absence of this guard is why the file fell behind.

Not in this PR, observed while regenerating

• The document declares no securitySchemes and no security arrays, so OpenAPI consumers see every endpoint as anonymous. That is a faithful report of how the app declares auth, as optional headers; the fix belongs in the app and is tracked as feat: declare security schemes in the OpenAPI document #89.
• Six mutating routes carry no auth dependency at all: POST /deals, /agentic-audience/match, /api/v1/deals/curated, /api/v1/deals/{id}/deprecate, /sessions/{id}/messages, /sessions/{id}/close. Pre-existing on main; tracked as fix: six mutating routes accept unauthenticated callers #86.

[numarasSigmaSoftware]

@atc964 @Sirajmx Can you take a look on this PR? I can provided further info if needed.

[Kishore-2572]

Thanks @numarasSigmaSoftware. The drift guard is a good addition. It caught every real drift I tried, ignored formatting-only differences, and gave the same result across .env and setting changes and on Python 3.11 and 3.12. The endpoint counts are right too. One thing needs fixing before merge: main has moved, and merged as-is this PR makes its own new test fail on main.

Blocking

The drift test fails once merged with main

Since this branch last merged main, #111 (Index Exchange) added account_id to SSPDealDistributeRequest. Git merges docs/api/openapi.json with no conflicts, but the result no longer matches what the app generates. That field is the only difference:

/components/schemas/SSPDealDistributeRequest/properties/account_id   (in the app, missing from the doc)

Full suite, run locally:

• This branch: 1,697 passed, 0 failed.
• Current main: 1,874 passed, 0 failed.
• This branch merged with main: 1 failed (tests/unit/test_openapi_drift.py::test_openapi_json_matches_app), 1,874 passed.

CI is green because it tests the branch as it is, not the merge result. Merging main in again and running python scripts/generate_openapi.py fixes it.

That's the guard doing its job; it just needs to happen before merge. To keep future PRs from doing the same thing

Minor

The change list in the description is out of date

#95 regenerated openapi.json on main on Sep 30, so most of the listed changes are already there: the operator-key route, the auth header parameters, idempotency_key, and exclusiveMinimum. Compared with the merge base, this PR's document diff is only:

• GET /api/v1/deals and its DealListResponse schema
• Description changes on GET /products and GET /products/{product_id}

After regenerating, the description should list just what the PR adds on top of main. The count updates (87 → 89) are still correct and needed.

What I tested

• Drift guard: it failed for an edited version, a removed path, a changed route description, and a deleted document. It passed for a formatting-only rewrite (re-indented, sorted keys), as its
  docstring says.
• Generator: running scripts/generate_openapi.py on this branch reproduces the committed file byte for byte.
• Environment: same result with the repo .env, with 9 different settings changode, auth off, Redis, ad server type, CORS and root path), on Python 3.11 and 3.12,and when run from a different directory.
• Counts:
  • The app has 89 operations across 25 tags.
  • The README group table has 25 rows summing to 89, and each row matches its tag c
  • No hand-written page still says 87 or 88, and docs/reference/endpoints.md says 89.
  • test_docs_inventory_drift.py passes.
• Description claims: in the regenerated document, POST /auth/api-keys/operator and GET /api/v1/deals are present, idempotency_key is required on QuoteRequest and CreateChangeRequestModel, and RateCardEntry.base_cpm has exclusiveMinimum: 0. mesorsecurity` arrays, as the description says.