docs(api): sync nav + error codes with openapi drift fixes

[indykish]

Tracks agentsfleet#430 (OpenAPI drift remediation).

The API reference auto-renders from main's public/openapi.json, so rendered operations update when #430 merges; this aligns the hand-maintained pieces:

• Nav: adds the previously-undocumented Authentication lifecycle ops (approve/verify/delete session/delete all/clerk identity-event), the per-charge billing telemetry endpoint, and new Fleet + Model Catalogue groups for the runner operator plane and model catalogue.
• error-codes: adds UZ-GRANT-002 (404, integration grant not found) — the new code backing the revoke not-found path.

🤖 Generated with Claude Code

Greptile Summary

This PR syncs hand-maintained documentation (nav and error-codes) with the OpenAPI drift fixes from agentsfleet#430. It adds previously-undocumented auth lifecycle endpoints, a billing telemetry endpoint, Fleet and Model Catalogue nav groups, and the new UZ-GRANT-002 error code for the revoke-not-found path.

• error-codes.mdx: UZ-AGT-010 gets a more general state-transition description, and UZ-GRANT-002 (HTTP 404) is added with a remediation path that correctly matches the existing integration-grants nav entry.
• docs.json: Five new Authentication endpoints, one Billing telemetry endpoint, a four-entry Fleet group, and a single-entry Model Catalogue group are added to the nav; the Fleet path inconsistency (POST /v1/runners vs /v1/fleet/runners) and the /_um/ hash path for Model Catalogue were flagged in previous review rounds.

Confidence Score: 5/5

Safe to merge — all changes are additive nav entries and an error-code addition; no logic, schema, or migration files are touched.

Both files contain purely additive, documentation-only changes. The error-code update to UZ-AGT-010 is a description clarification with no structural impact, and the new UZ-GRANT-002 entry references an endpoint already present in the nav. The open questions about the Fleet path prefix and Model Catalogue hash path were raised in prior review rounds and carry no correctness risk to the docs themselves.

No files require special attention beyond the open questions from prior review threads on docs.json.

Important Files Changed

Filename	Overview
api-reference/error-codes.mdx	Updates UZ-AGT-010 to a broader state-transition message and adds UZ-GRANT-002 (404, grant not found) with a correct remediation path matching the existing integration-grants nav entry.
docs.json	Adds Authentication lifecycle ops, billing telemetry, Fleet group, and Model Catalogue group to the nav. Fleet group has a noted path-prefix inconsistency (POST /v1/runners vs /v1/fleet/runners) and Model Catalogue uses a non-standard /_um/ hash path — both flagged in previous review threads.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[docs.json nav] --> B[Authentication group]
    A --> C[Billing group]
    A --> D[Fleet group]
    A --> E[Model Catalogue group]

    B --> B1[POST /v1/auth/sessions]
    B --> B2[GET /v1/auth/sessions/session_id]
    B --> B3[PATCH .../approve NEW]
    B --> B4[POST .../verify NEW]
    B --> B5[DELETE .../session_id NEW]
    B --> B6[DELETE .../sessions/all NEW]
    B --> B7[POST .../identity-events/clerk NEW]

    C --> C1[GET /v1/tenants/me/billing]
    C --> C2[GET .../charges]
    C --> C3[GET .../charges/event_id/telemetry NEW]

    D --> D1[POST /v1/runners NEW - different prefix]
    D --> D2[GET /v1/fleet/runners NEW]
    D --> D3[PATCH /v1/fleet/runners/id NEW]
    D --> D4[GET /v1/fleet/runners/id/events NEW]

    E --> E1[GET /_um/hash/cap.json NEW]

    F[error-codes.mdx] --> G[UZ-AGT-010 description updated]
    F --> H[UZ-GRANT-002 added - 404 grant not found NEW]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[docs.json nav] --> B[Authentication group]
    A --> C[Billing group]
    A --> D[Fleet group]
    A --> E[Model Catalogue group]

    B --> B1[POST /v1/auth/sessions]
    B --> B2[GET /v1/auth/sessions/session_id]
    B --> B3[PATCH .../approve NEW]
    B --> B4[POST .../verify NEW]
    B --> B5[DELETE .../session_id NEW]
    B --> B6[DELETE .../sessions/all NEW]
    B --> B7[POST .../identity-events/clerk NEW]

    C --> C1[GET /v1/tenants/me/billing]
    C --> C2[GET .../charges]
    C --> C3[GET .../charges/event_id/telemetry NEW]

    D --> D1[POST /v1/runners NEW - different prefix]
    D --> D2[GET /v1/fleet/runners NEW]
    D --> D3[PATCH /v1/fleet/runners/id NEW]
    D --> D4[GET /v1/fleet/runners/id/events NEW]

    E --> E1[GET /_um/hash/cap.json NEW]

    F[error-codes.mdx] --> G[UZ-AGT-010 description updated]
    F --> H[UZ-GRANT-002 added - 404 grant not found NEW]

Loading

_{Reviews (3): Last reviewed commit: "docs(api): use full path params in UZ-GR..." | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentsfleet	🔴 Failed	–	Jun 18, 2026, 8:11 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.