Skip to main content

​
API governance

API governance shows API coverage across every endpoint Qodex knows about. Use it to answer practical questions: which endpoints are tested, which are untested, which are failing, and where Qodex should generate more coverage.

​
How it works

Governance reads the same endpoint rows used by imports, the endpoint catalog, the API Playground, and discovery. There is no separate coverage database, so the catalog you see and the numbers the agent uses stay aligned. For every endpoint, governance shows:
  • Method and path.
  • Tag and module (from the spec).
  • Coverage status: tested, untested, or failing.
  • Number of scenarios covering it, broken out by category: functional, security, pentest.
  • Last test verdict (pass or fail) across all scenarios covering it.
  • Open findings tied to scenarios covering this endpoint.
  • Observed auth type and any missing security headers.

​
How endpoints enter the catalog

Endpoints arrive from three places:
  1. Spec import: every operation in an OpenAPI or Swagger document, plus every request in a Postman collection. Spec-derived fields (request_schema, response_schema, parameters, summary) populate at import time.
  2. Auto-discovery: the deterministic crawler (crawl_app) walks your app and captures every API call the UI makes. New method/path pairs upsert into api_endpoints with their observed headers, status, and body shape.
  3. Live runs: every scenario execution syncs the endpoints it touched back to the catalog (endpoint-sync.ts), incrementing testCount and updating last-tested timestamps.
Re-importing a spec preserves user edits via the is_edited flag. Playground-owned fields (name, headers, body, auth when edited) stay; spec-only fields (parameters, request_schema, summary) refresh.

​
Coverage status definitions

StatusWhat it means
TestedAt least one scenario touches this endpoint via a non-cleanup step, and the last run passed.
UntestedZero scenarios touch this endpoint, or scenarioCount == 0.
FailingAt least one scenario covers it and the last run failed.
The “touch” rule is deliberately generous. An auth endpoint that appears as a setup step in twenty scenarios counts as covered because those flows exercise it. A stricter “primary subject only” rule made login-heavy APIs look misleadingly uncovered. The any-step rule better matches what teams mean by “this endpoint has tests.”

​
The fill-coverage scan mode

fill-coverage is a scan mode that targets endpoints with zero scenarios. The agent:
  1. Calls endpoint_describe with action="gaps" to get the uncovered set.
  2. Clusters the uncovered endpoints by tag or path prefix into groups of 5 to 8.
  3. Spawns up to 5 parallel sub-agents (one per cluster) to author scenarios.
  4. Re-queries gaps between waves to converge on full coverage.
Auth and setup endpoints are reused automatically. You do not have to carve out a skip list for login chains the agent has already learned. To trigger a fill-coverage run: 
Fill the API coverage gaps for the Users tag. Skip anything
already covered.
The agent returns draft scenarios for uncovered endpoints, ready for review.

​
When governance matters

  • Use it for quarterly QA review: what is covered, what is not, and what changed.
  • Use it before a release: are any critical endpoints failing?
  • Use it after a spec import: which new endpoints have zero coverage?
  • Use it for security sweeps: which auth-required endpoints have no security tests?
The view is filterable by tag, role, coverage status, and last test verdict so you can answer each of these in one query.

​
When not to use it

  • Single-endpoint debugging. Use the API Playground for that. The catalog is the bird’s-eye view.
  • Real-time alerting. Governance reflects state at view time. For real-time pass/fail signals, watch test-run dashboards.

​
On the roadmap

Route-table vs scenarios diff: once your GitHub repo is linked, the agent parses your actual route table and compares it against the spec-derived catalog. Endpoints that exist in code but are missing from the spec surface as “shadow endpoints.” Endpoints in the spec that no longer exist in code surface as “dead routes.” Time-series tracking of coverage percentage with a visual coverage map follows.

Endpoint catalog

The queryable list of every endpoint.

Scenarios

The unit being counted as coverage.

Auth profiles

How role-aware coverage gets clean.

Findings

What surfaces when a covering scenario fails.