fix(agents): correct auth scheme, stale paths, and phantom COMPLETED status

[k15z]

Summary

• Auth scheme: Added AgentAuth to the global security array in openapi/openapi.yaml. Per Stainless docs, the top-level security array determines which schemes the SDK client supports — without it, the Stainless merge step was failing, which is why the published docs at grid.lightspark.com never reflected the agents endpoints after feat(agents): add Agents (experimental) to Grid API spec #430 merged.
• Stale paths: Three agent endpoint descriptions still referenced the old POST /agents/{agentId}/transactions/{transactionId}/approve path. Updated to POST /agents/{agentId}/actions/{actionId}/approve.
• Phantom status: approvals-and-audit.mdx step 8 documented a COMPLETED terminal state that does not exist in AgentActionStatus. APPROVED is the terminal success state. Removed to prevent integrators from polling for a state that never arrives.

Test plan

• Stainless merge check passes (unblocks published docs update)
• Verify agent endpoints appear in published sidebar after merge

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 1, 2026 6:33pm

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	May 1, 2026, 6:34 PM

[github-actions]

✱ Stainless preview builds

This PR will update the grid SDKs with the following commit messages.

kotlin

docs(api): update approval endpoint reference in transfer and quote methods

openapi

feat(client): add AgentAuth authentication option

python

docs(api): update approval endpoint references in agents/me methods

typescript

docs(api): update endpoint references in agents.me transfer and quote methods

⚠️ grid-openapi studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗

⚠️ grid-kotlin studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗ → build ✅ → lint ✅ → test ✅

⚠️ grid-python studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗ → build ✅ → lint ✅ → test ✅

pip install https://pkg.stainless.com/s/grid-python/2c1786b0bbe88b5effbdc7412b9c09c600a7e504/grid-0.0.1-py3-none-any.whl

⚠️ grid-typescript studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ❗ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/8b4243825baa545d8402b0b9b9a9d4d2e273d488/dist.tar.gz

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-01 19:07:41 UTC

[greptile-apps]

Greptile Summary

This PR fixes three documentation/spec correctness issues introduced when agent endpoints shipped in #430: the missing AgentAuth entry in the global security array (which blocked the Stainless SDK merge step), three endpoint descriptions still referencing the old transactions/{transactionId}/approve path, and a phantom COMPLETED status in the approval-lifecycle walkthrough.

• Potential second phantom status: FAILED is referenced in the Warning block and the status field description of approvals-and-audit.mdx (lines 42–43, 52), but AgentActionStatus.yaml only enumerates PENDING_APPROVAL, APPROVED, and REJECTED — the same situation as the COMPLETED state being removed here.

Confidence Score: 3/5

Safe to merge after confirming whether FAILED is a valid AgentActionStatus value; if not, it should be removed alongside COMPLETED.

A P1 finding exists: FAILED is referenced as a terminal AgentActionStatus in the docs but is absent from the schema enum, the same pattern as the COMPLETED phantom status this PR fixes. The other changes (auth scheme, path corrections) are correct and straightforward.

mintlify/global-accounts/agents/approvals-and-audit.mdx — FAILED status on lines 42–43 and 52 needs verification against AgentActionStatus.yaml

Important Files Changed

Filename	Overview
mintlify/global-accounts/agents/approvals-and-audit.mdx	Removes phantom COMPLETED state from step 8, but FAILED is still referenced (lines 42–43, 52) and is absent from AgentActionStatus.yaml enum — possible second phantom status.
openapi/openapi.yaml	Adds AgentAuth to global security array; AgentAuth scheme is already defined in securitySchemes — correct fix to unblock Stainless merge.
openapi/paths/agents/agents_me_quotes_{quoteId}_execute.yaml	Updates stale approval path from transactions/{transactionId}/approve to actions/{actionId}/approve — correct.
openapi/paths/agents/agents_me_transfer-in.yaml	Updates stale approval path from transactions/{transactionId}/approve to actions/{actionId}/approve — correct.
openapi/paths/agents/agents_me_transfer-out.yaml	Updates stale approval path from transactions/{transactionId}/approve to actions/{actionId}/approve — correct.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant Grid
    participant Platform Backend
    participant Customer App

    Agent->>Grid: POST /agents/me/quotes/{quoteId}/execute (or transfer-in/out)
    alt Policy requires approval
        Grid-->>Agent: AgentAction {status: PENDING_APPROVAL}
        Grid->>Platform Backend: Webhook AGENT_ACTION.PENDING_APPROVAL
        Platform Backend->>Customer App: Push notification
        Customer App->>Platform Backend: Customer approves/rejects
        Platform Backend->>Grid: POST /agents/{agentId}/actions/{actionId}/approve (or /reject)
        Grid-->>Platform Backend: AgentAction {status: APPROVED | REJECTED}
    else Auto-execution allowed
        Grid-->>Agent: AgentAction {status: APPROVED, transaction: {...}}
    end

Loading

Comments Outside Diff (1)

1. mintlify/global-accounts/agents/approvals-and-audit.mdx, line 52 (link)

   Possible phantom FAILED status in AgentActionStatus

   This PR removes COMPLETED as a phantom status, but FAILED is also referenced on lines 42–43 (Warning block) and line 52 (status field description) — yet AgentActionStatus.yaml only enumerates PENDING_APPROVAL, APPROVED, and REJECTED. If FAILED is not a real AgentActionStatus value, integrators polling for it will wait forever, the same issue that motivated removing COMPLETED.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: mintlify/global-accounts/agents/approvals-and-audit.mdx
   Line: 52
   
   Comment:
   **Possible phantom `FAILED` status in `AgentActionStatus`**
   
   This PR removes `COMPLETED` as a phantom status, but `FAILED` is also referenced on lines 42–43 (Warning block) and line 52 (`status` field description) — yet `AgentActionStatus.yaml` only enumerates `PENDING_APPROVAL`, `APPROVED`, and `REJECTED`. If `FAILED` is not a real `AgentActionStatus` value, integrators polling for it will wait forever, the same issue that motivated removing `COMPLETED`.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
mintlify/global-accounts/agents/approvals-and-audit.mdx:52
**Possible phantom `FAILED` status in `AgentActionStatus`**

This PR removes `COMPLETED` as a phantom status, but `FAILED` is also referenced on lines 42–43 (Warning block) and line 52 (`status` field description) — yet `AgentActionStatus.yaml` only enumerates `PENDING_APPROVAL`, `APPROVED`, and `REJECTED`. If `FAILED` is not a real `AgentActionStatus` value, integrators polling for it will wait forever, the same issue that motivated removing `COMPLETED`.

_{Reviews (1): Last reviewed commit: "fix(agents): correct auth scheme, stale ..." | Re-trigger Greptile}