From 4a13559f70716c8d2a60bd788569178f69d2b4e2 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Fri, 19 Jun 2026 01:37:42 +0530 Subject: [PATCH 1/3] docs(api): sync nav + error codes with openapi drift fixes Tracks agentsfleet#430 (OpenAPI drift remediation). The API reference auto-renders from main's public/openapi.json, so the rendered operations update on that PR's merge; this aligns the hand-maintained nav and the error-code table. - Nav: add 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 the model catalogue. - error-codes: add UZ-GRANT-002 (404, integration grant not found), the new code that backs the revoke not-found path. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/error-codes.mdx | 1 + docs.json | 25 +++++++++++++++++++++++-- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index e5e7174..54e8b5a 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -157,6 +157,7 @@ Load-shedding on a saturated API instance — back off and retry. | Code | HTTP | Title | Common Causes | |---|---|---|---| | `UZ-GRANT-001` | 403 | No integration grant for service | This agent has no approved grant for the target service. Request one with `POST /v1/agents/{id}/integration-requests`. | +| `UZ-GRANT-002` | 404 | Integration grant not found | No grant with that id exists for this agent, or it was already revoked. List current grants with `GET /v1/workspaces/{ws}/agents/{id}/integration-grants`. | ## Approval gate diff --git a/docs.json b/docs.json index 33acb15..67fb673 100644 --- a/docs.json +++ b/docs.json @@ -113,7 +113,12 @@ "group": "Authentication", "pages": [ "POST /v1/auth/sessions", - "GET /v1/auth/sessions/{session_id}" + "GET /v1/auth/sessions/{session_id}", + "PATCH /v1/auth/sessions/{session_id}/approve", + "POST /v1/auth/sessions/{session_id}/verify", + "DELETE /v1/auth/sessions/{session_id}", + "DELETE /v1/auth/sessions/all", + "POST /v1/auth/identity-events/clerk" ] }, { @@ -143,7 +148,23 @@ "group": "Billing", "pages": [ "GET /v1/tenants/me/billing", - "GET /v1/tenants/me/billing/charges" + "GET /v1/tenants/me/billing/charges", + "GET /v1/tenants/me/billing/charges/{event_id}/telemetry" + ] + }, + { + "group": "Fleet", + "pages": [ + "POST /v1/runners", + "GET /v1/fleet/runners", + "PATCH /v1/fleet/runners/{id}", + "GET /v1/fleet/runners/{id}/events" + ] + }, + { + "group": "Model Catalogue", + "pages": [ + "GET /_um/da5b6b3810543fe108d816ee972e4ff8/cap.json" ] }, { From 4b58a78f49d57aa93c097bc2b8ccbedd05ab72ab Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Fri, 19 Jun 2026 06:51:31 +0530 Subject: [PATCH 2/3] docs(api): retitle UZ-AGT-010 to match generalized registry entry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tracks agentsfleet#430 — UZ-AGT-010 is reused by both the patch (invalid transition) and delete (not-yet-killed) paths, so the title generalizes from 'Agent already stopped or killed' to 'Agent state transition not allowed'. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/error-codes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 54e8b5a..615dcd1 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -148,7 +148,7 @@ Load-shedding on a saturated API instance — back off and retry. | `UZ-AGT-006` | 409 | Agent name already exists | Name taken. Kill the existing agent first, then re-install. | | `UZ-AGT-008` | 400 | Invalid agent config | `TRIGGER.md` config_json fails schema validation. Verify trigger, tools, credentials, and budget fields. | | `UZ-AGT-009` | 404 | Agent not found | No agent with this ID in the workspace. | -| `UZ-AGT-010` | 409 | Agent already stopped or killed | This agent is already stopped or killed. Re-install before issuing another stop. | +| `UZ-AGT-010` | 409 | Agent state transition not allowed | The requested lifecycle action is not valid from the agent's current state. The response detail names the specific transition that was refused. | | `UZ-AGT-011` | 400 | SKILL.md and TRIGGER.md disagree on `name:` | Top-level `name:` must match across both files. One identity per agent bundle. | | `UZ-AGT-012` | 409 | Agent is paused | Agent is not active and refuses new work. Resume with `agentsfleet resume `, then retry. | From 9efb0779a987496d54c1ed8f0f5fc3969a32691d Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Fri, 19 Jun 2026 19:15:59 +0530 Subject: [PATCH 3/3] docs(api): use full path params in UZ-GRANT-002 remediation URL Greptile flagged the abbreviated {ws}/{id} placeholders in the UZ-GRANT-002 remediation URL. Every other path in the nav and the Integration grants group uses {workspace_id}/{agent_id}; match them so a reader can copy-paste without guessing the mapping. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/error-codes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 615dcd1..87eebb9 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -157,7 +157,7 @@ Load-shedding on a saturated API instance — back off and retry. | Code | HTTP | Title | Common Causes | |---|---|---|---| | `UZ-GRANT-001` | 403 | No integration grant for service | This agent has no approved grant for the target service. Request one with `POST /v1/agents/{id}/integration-requests`. | -| `UZ-GRANT-002` | 404 | Integration grant not found | No grant with that id exists for this agent, or it was already revoked. List current grants with `GET /v1/workspaces/{ws}/agents/{id}/integration-grants`. | +| `UZ-GRANT-002` | 404 | Integration grant not found | No grant with that id exists for this agent, or it was already revoked. List current grants with `GET /v1/workspaces/{workspace_id}/agents/{agent_id}/integration-grants`. | ## Approval gate