Skip to content

docs: sync documentation with recent OpenAPI schema changes #851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
claude wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: sync documentation with recent OpenAPI schema changes #851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions mintlify/snippets/error-handling.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,7 @@ When a transaction fails, the `failureReason` field provides specific details:
- `PAYMENT_APPROVAL_WEBHOOK_ERROR` - Webhook returned an error
- `OFFRAMP_FAILED` - Failed to convert and send funds to destination
- `QUOTE_EXPIRED` - Quote expired during processing
- `COLLECTION_FAILED` - Inbound bank-rail collection deposit failed after arrival and did not credit; funds returned to sender

@greptile-apps greptile-apps Bot Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Passive descriptions obscure actors

The new phrases “funds returned to sender” here and “funding instructions are added or modified” in internal-accounts.mdx use passive voice, contrary to the Mintlify writing standard, and obscure who performs these operational actions.

Context Used: mintlify/AGENTS.md (source)

Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/error-handling.mdx
Line: 234

Comment:
**Passive descriptions obscure actors**

The new phrases “funds returned to sender” here and “funding instructions are added or modified” in `internal-accounts.mdx` use passive voice, contrary to the Mintlify writing standard, and obscure who performs these operational actions.

**Context Used:** mintlify/AGENTS.md ([source](https://github.com/lightsparkdev/grid-api/blob/main/mintlify/AGENTS.md))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!


## Handling failures

Expand Down
4 changes: 4 additions & 0 deletions mintlify/snippets/global-accounts/managing-sessions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ The list endpoint returns all **active** sessions; expired sessions are not incl

Session refresh creates a new session signing key from an existing active session. Use this when the customer is still present and the current session is close to expiration. If the session has already expired, reauthenticate with the original credential instead.

<Note>
The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/snippets/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.

@greptile-apps greptile-apps Bot Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Broken client-key documentation link

When a reader follows the new client-held-key recommendation, the link targets the snippet import path rather than the registered public page, causing navigation to a missing route instead of the session-key instructions.

Suggested change
The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/snippets/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.
The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.

Knowledge Base Used: Mintlify Documentation Site

Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/global-accounts/managing-sessions.mdx
Line: 44

Comment:
**Broken client-key documentation link**

When a reader follows the new client-held-key recommendation, the link targets the snippet import path rather than the registered public page, causing navigation to a missing route instead of the session-key instructions.

```suggestion
  The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.
```

**Knowledge Base Used:** [Mintlify Documentation Site](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/mintlify-docs-site.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

</Note>

<Steps>
<Step title="First call — receive the challenge">
```bash
Expand Down
2 changes: 1 addition & 1 deletion mintlify/snippets/internal-accounts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -371,7 +371,7 @@ Show the payment details prominently in your UI:
Set up webhook listeners to receive notifications when deposits are credited to the internal account. The account balance will update automatically.

<Info>
You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes.
You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes, and `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` when funding instructions are added or modified.

@greptile-apps greptile-apps Bot Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Missing cache invalidation guidance

The new webhook guidance does not tell readers to refresh cached fundingPaymentInstructions; integrations following the same snippet's caching advice can continue displaying withdrawn or outdated deposit coordinates after receiving this event.

Suggested change
You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes, and `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` when funding instructions are added or modified.
You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. When `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` reports new or withdrawn funding instructions, invalidate any cached `fundingPaymentInstructions` and fetch the account again.
Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/internal-accounts.mdx
Line: 374

Comment:
**Missing cache invalidation guidance**

The new webhook guidance does not tell readers to refresh cached `fundingPaymentInstructions`; integrations following the same snippet's caching advice can continue displaying withdrawn or outdated deposit coordinates after receiving this event.

```suggestion
You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. When `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` reports new or withdrawn funding instructions, invalidate any cached `fundingPaymentInstructions` and fetch the account again.
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

</Info>
</Step>
</Steps>
Expand Down
Loading