Add OTP email update endpoint to OpenAPI

[DhruvPareek]

Summary:

• Adds the new PATCH /internal-accounts/{id}/email OpenAPI path for updating the email address used by an Embedded Wallet account EMAIL_OTP credential.
• Models the endpoint as the existing two-step signed-retry flow: initial calls return the shared SignedRequestChallenge shape with payloadToSign, requestId, and expiresAt; signed retries return 200 with the updated account email resource.
• Adds InternalAccountEmailUpdateRequest with the required email field and InternalAccountEmailUpdateResponse with id, email, and updatedAt.
• Documents 409 Conflict for duplicate EMAIL_OTP email addresses and adds the EMAIL_OTP_EMAIL_ALREADY_EXISTS error code to Error409.
• Wires the path into openapi/openapi.yaml and regenerates the bundled openapi.yaml and mintlify/openapi.yaml files.

Files added:

• openapi/paths/internal_accounts/internal_accounts_{id}_email.yaml
• openapi/components/schemas/internal_accounts/InternalAccountEmailUpdateRequest.yaml
• openapi/components/schemas/internal_accounts/InternalAccountEmailUpdateResponse.yaml

Files updated:

• openapi/components/schemas/errors/Error409.yaml

Testing:

• npm run lint:openapi

[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 8, 2026 0:30am

[DhruvPareek]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Add wallet privacy endpoint to OpenAPI #452
• Add auth session refresh endpoints #451
• Add OTP email update endpoint to OpenAPI #450 👈 (View in Graphite)
• Add passkey credentialId to auth challenge response #449
• Add passkey credentialId to auth credential list #448
• Align auth session request-id contract #445 : 1 other dependent PR (#446 )
• Align auth credential create contract #444
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✱ Stainless preview builds

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

kotlin

feat(api): add updateEmail method to customers

openapi

feat(api): add update_email method to internal_accounts

python

feat(api): add update_email method to customers

typescript

feat(api): add updateEmail method to customers

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-python studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

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

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

✅ grid-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ❗ → lint ❗ → test ❗

✅ grid-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

---

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-08 00:28:29 UTC

[greptile-apps]

Greptile Summary

This PR documents a new PATCH /internal-accounts/{id}/email endpoint for updating the EMAIL_OTP credential email on an Embedded Wallet account, following the existing two-step signed-retry pattern established by the export endpoint.

• Adds the path definition, InternalAccountEmailUpdateRequest and InternalAccountEmailUpdateResponse schemas, and wires them into the root spec and both generated bundles.
• Extends Error409 with the EMAIL_OTP_EMAIL_ALREADY_EXISTS error code and documents the 409 conflict response on the new endpoint.

Confidence Score: 5/5

Safe to merge — this is a documentation-only change that correctly mirrors the established signed-retry flow pattern with no logic or runtime code affected.

The new endpoint definition closely tracks the sibling export endpoint, all required response codes (including the previously requested 409) are present, the schema fields are correctly typed, and the bundled outputs match the source. The only finding is a cosmetic response-ordering inconsistency in the source YAML that the bundler already corrects in generated output.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/paths/internal_accounts/internal_accounts_{id}_email.yaml	New PATCH endpoint for updating EMAIL_OTP email via the two-step signed-retry flow; closely mirrors the export endpoint pattern with correct responses (200, 202, 400, 401, 409, 404, 500), though 409 and 404 are listed out of ascending order in the source file.
openapi/components/schemas/internal_accounts/InternalAccountEmailUpdateRequest.yaml	New request schema with required email field (format: email), detailed description, and correct structure.
openapi/components/schemas/internal_accounts/InternalAccountEmailUpdateResponse.yaml	New response schema with required id, email, and updatedAt fields; missing top-level description (noted in previous thread).
openapi/components/schemas/errors/Error409.yaml	Adds EMAIL_OTP_EMAIL_ALREADY_EXISTS to the Error409 error code enum and description table.
openapi/openapi.yaml	Wires /internal-accounts/{id}/email path ref into the root spec alongside the existing export path.
openapi.yaml	Auto-generated bundle; correctly includes the new endpoint inline with all schema definitions.
mintlify/openapi.yaml	Auto-generated Mintlify bundle; identical new content to openapi.yaml; bundler correctly reorders 404 before 409 in the output.

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant G as Grid API

    C->>G: "PATCH /internal-accounts/{id}/email<br/>Body: { email }"
    G-->>C: "202 Accepted<br/>{ payloadToSign, requestId, expiresAt }"

    Note over C: Sign payloadToSign with session API keypair

    C->>G: "PATCH /internal-accounts/{id}/email<br/>Grid-Wallet-Signature: stamp<br/>Request-Id: requestId<br/>Body: { email }"
    alt Email available
        G-->>C: "200 OK { id, email, updatedAt }"
    else Email already in use
        G-->>C: 409 Conflict EMAIL_OTP_EMAIL_ALREADY_EXISTS
    else Signature or challenge mismatch
        G-->>C: 401 Unauthorized
    end

Loading

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
openapi/paths/internal_accounts/internal_accounts_{id}_email.yaml:103-118
The `409` response block is placed before `404`, breaking the ascending HTTP status-code order that every other endpoint in this repo follows (including the sibling export endpoint). OpenAPI parsers are order-agnostic so this is harmless at runtime, but the bundled output already reorders them correctly, which signals the mismatch with the source.

```suggestion
    '404':
      description: Internal account not found
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error404.yaml
    '409':
      description: >-
        Conflict. Returned when the supplied email address is already
        associated with an `EMAIL_OTP` credential on this or another
        internal account.
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error409.yaml
    '500':
```

_{Reviews (2): Last reviewed commit: "Add internal account email update endpoi..." | Re-trigger Greptile}