docs(cards): panEmbedUrl is nullable and minted only on GET /cards/{id}

[ls-bolt]

This PR has been claimed. The active PR is now #657.

Summary

Follow-up #2 from webdev#29877 (Lithic card PAN-reveal POC) — brings the public docs in line with the actual reveal model: the signed panEmbedUrl is minted only on GET /cards/{id}, is short-lived (~5 min TTL), and is null everywhere else (list/create/update responses and webhook payloads).

• openapi/components/schemas/cards/Card.yaml — panEmbedUrl is now nullable (type: [string, 'null']), with a description stating it's populated only on the single-card GET, is short-lived, and should be fetched right before rendering the iframe (never cached).
• openapi/paths/cards/cards_{id}.yaml — GET /cards/{id} description now calls out that it's the only endpoint that mints a fresh panEmbedUrl.
• mintlify/snippets/cards/issuing-cards.mdx (rendered by mintlify/cards/card-management/issuing-cards.mdx, which just imports the snippet) — removed panEmbedUrl from the fields the CARD.STATE_CHANGE webhook delivers; added a "Revealing the PAN" section with the fetch-on-demand pattern.
• Consistency fixes in the other stale references the task called out as inconsistent: mintlify/snippets/cards/webhooks.mdx and quickstart.mdx (webhook example payloads now show panEmbedUrl: null; reveal notes rewritten to fetch-on-demand), terminology.mdx (PAN embed URL definition mentions single-GET-only + short-lived), and the activated example in openapi/webhooks/card-state-change.yaml.

Verification

• make build — rebundled openapi.yaml + mintlify/openapi.yaml (both included).
• make lint — passes with 0 errors; remaining warnings/infos are pre-existing on main (verified by diffing against a baseline lint run on main).
• Local Codex review: no findings.

Note: the Stainless Build SDKs csharp preview check is expected to go red — it currently fails for any codegen-delta change, content-independently (csharp target is unpublished; precedent: #633, #637 merged through it). Lint / Breaking Changes / Docs build are the real gates here.

---

🤖 thundering-graviton(#1) | Feedback

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jul 6, 2026 11:22pm
grid-wallet-demo	Ignored	Preview	Jul 6, 2026 11:22pm

[github-actions]

⚠️ Breaking OpenAPI changes detected

This PR introduces breaking changes to openapi.yaml:

API Changelog 2026-06-29 vs. 2026-06-29

API Changes

GET /cards

• ⚠️ the response property data/items/panEmbedUrl became nullable for the status 200

POST /cards

• ⚠️ the response property panEmbedUrl became nullable for the status 201

GET /cards/{id}

• ⚠️ the response property panEmbedUrl became nullable for the status 200

PATCH /cards/{id}

• ⚠️ the response property panEmbedUrl became nullable for the status 200

---

Detected by oasdiff. This PR will need approval from an API reviewer before merge.

[akanter]

• docs(cards): panEmbedUrl is nullable and minted only on GET /cards/{id} #654 👈 (View in Graphite)
• main

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

[github-actions]

✱ Stainless preview builds for grid

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

cli

docs(api): expand usage documentation for cards retrieve method

csharp

docs(api): clarify panEmbedUrl is signed, short-lived, only in cards retrieve

go

docs(api): clarify panEmbedUrl behavior in card resource

kotlin

docs(api): clarify panEmbedUrl behavior in cards

openapi

fix(types): make panEmbedUrl nullable in Card model

php

docs(api): clarify panEmbedUrl behavior in cards retrieve and model

python

docs(api): clarify pan_embed_url behavior in cards resource

ruby

docs(api): clarify pan_embed_url behavior in card model and retrieve method

typescript

docs(api): update cards.retrieve and panEmbedUrl field descriptions

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

✅ grid-clistudio · code · diff

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

✅ grid-openapistudio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

✅ grid-phpstudio · code · diff

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

✅ grid-gostudio · code · diff

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

go get github.com/stainless-sdks/grid-go@7ed170003b8bfe4d916511fde4393f3cb9186c44

✅ grid-rubystudio · code · diff

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

✅ grid-kotlinstudio · code · diff

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

⚠️grid-pythonstudio · code · diff

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

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

⚠️grid-typescriptstudio · code · diff

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

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

⚠️grid-csharpstudio · code · diff

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ❗

---

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-07-06 23:27:38 UTC

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Jul 6, 2026, 11:44 PM

[ls-bolt]

📌 Bolt Status

2026-07-06 23:42:57 UTC — ⚠️ Failed to start agent: timeout of 30000ms exceeded

[ls-bolt]

Re: the oasdiff breaking-change notice — the nullability flags on the four card endpoints are intentional and codify existing runtime behavior rather than changing it. The server already returns panEmbedUrl: null on list/create/update responses (and in webhook payloads); the signed URL is only minted on GET /cards/{id} and expires within minutes. The previous spec (non-nullable, implying it's always present) was the inaccuracy — see the PAN-reveal model established in webdev#29877. Any client generated from the old spec that assumed a populated panEmbedUrl outside the single-card GET was already broken against the real API.

The Detect breaking changes check itself is green; this sticky comment is the informational surface for the API-reviewer approval.

---

🤖 thundering-graviton(#2) | Feedback