How to make your API agent-native — Stripe's developer playbook

The single most-cited stat from Stripe Sessions 2026 was hidden inside a developer keynote that almost no one in devtools Twitter wrote up.

“In 2025, agent traffic to Stripe’s documentation 10xed in a single year. We went from agents representing less than 5% of our doc’s traffic to nearly 40%. And on this trajectory, agents will soon be reading more documentation than humans.” — Michelle Bu, head of API Design and Developer Experience, on stage in Moscone West, April 29 2026.

That number is the bet. Inside Stripe, 91% of engineers are now using AI tools daily. Bu, a 13-year Stripe product engineer, said she has shipped more code since January than in the previous five years combined. The internal coding agent, Minions, ships more than 1,000 PRs to production every week; 57,000 PRs went up in March 2026 alone with AI assistance, a 140% increase in three months.

Stripe is not predicting the agentic shift. They are already on the other side of it, and the dev keynote is the first public articulation of what a platform looks like when 40% of its developer audience is non-deterministic, eager to please, and built from a transformer. It is also the first complete playbook any API company has shipped for retrofitting itself for that audience, and it sits cleanly alongside the Software 3.0 thesis Andrej Karpathy laid out at AI Ascent days earlier. The framework is clean: three pillars (smarter, more capable, trustworthy), each with concrete, copyable primitives. In the 28-minute talk, the two Stripe presenters walked an autonomous customer-support agent through reading email, refunding Sarah, getting blocked on Marcus, requesting a human approval, firing a workflow, and tagging the case in a custom object. Every step deterministic, auditable, reproducible.

Devtools Twitter did not catch this. Patrick Collison’s thread the next day hit 1,173 likes and explicitly framed it: “AI is making developer-centricity strategic in a new way: agents are even hungrier for good DX than developers themselves are.” But the people who normally adjudicate developer platform launches (Guillermo Rauch, Lee Robinson, Theo Browne, Cassidy Williams, Logan Kilpatrick, Will Larson) were silent on the dev keynote. Rauch’s only Sessions post was a 32-like thank-you note. Wes Bos, Matt Pocock, Brian Lovin: nothing. The closest signal was Jeff Weinstein of Stripe itself, whose “agents love it” line about the CLI collected 267 likes, and Pejman John’s Link CLI demo at 2,076 likes. Both adjacent surfaces, neither the architecture itself.

So this is the canonical write-up. Seven steps, every one of them mapped to a Stripe artifact you can study or install today. If you ship a developer-facing API in 2026 and skip these, you are losing to whoever copies them first.

The framing — three pillars, in Bu’s words

“We’re empowering agents — this little blobby non-deterministic thing — in three ways. First, smarter. Second, more capable. Third, trustworthy.” — Bu, dev keynote.

Every product in the talk maps to one pillar. Forget the 288-launch megalist from the main keynote for a moment. The dev-keynote subset is tightly designed.

That is the whole talk. Now to the playbook.

Step 1 — Add .md to every doc URL

The smallest shipped change with the largest second-order effects.

“Our docs were designed to be easily scannable by the human eye. But now they also have to be as lightweight as possible to fit into precious context space and to minimize token waste for all of you. So to address this constraint, we’ve made all of our documentation available as raw markdown. By appending MD to any URL, an agent gets all the content without headers, footers, and UI elements.” — Bu.

Hit https://docs.stripe.com/api/refunds.md. You get a 727-byte plain-text file. First line: # Refunds. The interactive sidebar, footer, JS bundles, theme toggles, all gone. An agent fetches one page, costs maybe 200 tokens, and gets the canonical surface.

This is the llms.txt spec Jeremy Howard proposed in late 2024, applied at every page instead of a single manifest. Stripe also publishes docs.stripe.com/llms.txt so an agent can index the tree before it crawls. The Stripe internal benchmark made the case quantifiable: token waste on chrome was a measurable fraction of every doc fetch. In a 40%-of-traffic-is-agents world, you pay that tax on every retrieval-augmented call your customers make against your platform.

Action: Add content negotiation to your docs router. Detect a literal .md suffix or a known agent UA. Strip layout, return raw markdown. Ship /llms.txt. Less than a day for any docs-as-code stack: Mintlify, Fern, Docusaurus, Nextra, custom.

Step 2 — Ship a skills/<topic> package via npx

Markdown alone is not enough. An agent reading your docs perfectly will still pick the wrong primitive if it has no opinion baked in. Bu’s vibe-coding example was brutal:

A developer ran the prompt “set up payments for my side business that takes upfront payments and starts long-term engagements, plus recurring subscriptions” through Claude Code with no Stripe context. Claude recommended the plans API (deprecated since 2019), Card Element (a low-level UI primitive that breaks for EU local payment methods), asked no clarifying question about customer geography, and rendered an empty rectangle on screen because no API key was wired up. The agent declared the integration done.

The fix is skills. The stripe/agent-toolkit repo on GitHub at 1,518 stars ships SKILL.md files an agent drops into Claude Code, Codex, Cursor, OpenCode, Qwen, or Copilot, any tool respecting the Anthropic Agent Skills convention. Drop a folder under .claude/skills/, restart, and the agent picks up the canonical idiom for “subscriptions on Stripe in 2026” before writing a line.

The lesson generalizes. Any API with non-trivial integration-shape decisions (Twilio, Resend, Linear, Notion, Cloudflare, Supabase, Vercel, the Stripe of voice agents, the Stripe of memory engines) needs a SKILL package or an agent will pick the worst-supported primitive in their docs and ship it to production. Anthropic’s skills GitHub is the spec; npx skills add <repo> is the discovery surface.

Action: Open your-co/skills. Ship one SKILL.md per integration shape. Make it npx-installable. Maintain it like your TypeScript SDK. Then run an internal Integration Benchmark (Bu’s word) that re-runs every model nightly and grades whether they ship deprecated calls. Eval-driven docs is the new TDD.

Step 3 — Structure errors so an LLM can act on them

This is the architectural keystone of the whole talk and the single most-skipped pattern in current API design.

When an agent tries to refund $250 against an Approval Rule that requires human review for amounts over $100, Stripe does not return a 403. It returns a structured error containing an approval_request handle. The agent reads the error, parses the handle, and calls a dedicated /approvals endpoint to escalate.

“Your agent actually figured out how to do that on its own based on the error message we were returning in the API. Exactly. It got all of the information it needed in that error.” — Bu/Nilifer exchange on stage.

That single line is more important than every other primitive in the talk combined. It says: error responses are now contracts, and the contract has to include the recovery path.

Compare the design space:

If you ship a B2B API in 2026 and your error responses still look like the first three rows of that table, you are forcing every customer to reinvent the same approval-loop adapter inside their agent harness. They will eventually wrap your API in a middleware that does it for them, and then your API will be a substrate, not a platform.

Action: Define an error envelope. Pick the verbs (approval_required, quota_exceeded, human_review_required, policy_violation). Pair each verb with an endpoint that resolves it. Document each verb in your .md docs and your SKILL.md. Run the agent against blocked actions in CI and assert that it self-recovers without prompting.

Step 4 — Pair every error with an approval-request contract

Step 3 is the syntax. Step 4 is the semantics: the human-in-loop spec.

Stripe Approvals are surfaced as a settings page, not a code library. Nilifer demoed it on stage:

“Approvals are safe-by-default guardrails that protect your account. You can see different rules here for refunds, subscriptions, changes to my bank account, and more. These apply whether the action comes from an agent or from a human and whether it comes from the API, MCP, or the dashboard. Same rules, same protections everywhere.” — Nilifer.

That last sentence is doing the heavy lifting. The same Approval Rule applies whether a human refunds via dashboard, an agent refunds via MCP, or your backend refunds via API. The rule is the source of truth, not the caller. This collapses the matrix that every B2B SaaS reinvents (“how do we make sure agents follow the same policy our humans follow?”) into a single configuration surface.

The live demo: agent reads two refund emails, calls Stripe API with an agent-tagged key. Sarah’s $50 refund passes, under the $100 threshold the team set. Marcus’s $250 refund returns a structured error. The agent calls /approvals, the human approves in dashboard, the refund proceeds, a refund.created event fires, a Workflow with custom-action support pings Slack, and a Custom Object tags Marcus for follow-up. About four minutes of stage time. Nothing custom-built. All wired through Stripe primitives.

This is the substrate every customer-support, finance-ops, and agentic-payments product needs this year:

Every product out there needs an MCP server and a solid API, and probably also an AI agent. I didn’t even login to Stripe to create the products, Claude Code just created them for me in my account.

— @joncphillips May 1, 2026

Action: Ship an Approvals resource with per-resource rules and amount thresholds. Apply the rules uniformly across API, MCP, dashboard, any other actuator. Settings page, not a config file. Pair every blockable verb with a structured-error escalation. Ship a default rule set for the riskiest objects in your domain.

Step 5 — Tag API keys with agent identity

Before approvals can apply differently to agents than to humans, you have to know which is which. Stripe added an actor type to API keys: agent vs. user. Dashboard shows it. Audit logs show it. You can scope permissions and rules to it.

Visa launched their AI agent rail in April 2025. Mastercard shipped theirs one day earlier. Stripe just entered the fight. Look at the CLI demo. link auth-start. A device code. A shared passphrase like apple-grape-orange. This is the OAuth 2.0 device authorization grant.

— @aakashgupta Apr 30, 2026

Agent-tagged keys are not a feature. They are the primitive beneath every other trustworthy-pillar capability: approvals, audit, rate-limit policy, billing analytics, fraud signals. Every refund row in Workbench has a tag indicating “this action was taken by an agent”, traceable to the specific key. When an agent goes wrong (and they will), you filter by actor type instead of grepping production logs.

Action: Add actor_type to your API keys table. Surface in dashboard and audit logs. Wire through to rate-limit, billing, and policy layers. Gate every new feature on the question: “is this safe for agent actors? if not, which Approval Rule covers it?”

Step 6 — Provide a sandbox creator command that needs zero credentials

The first demo failed at exactly the human-developer pain point: the agent asked for an API key, the user said “I’ll get keys later,” Claude wrote code that called Stripe with no key, the page rendered an empty rectangle, the integration was declared done. The friction was the credential request itself.

The fix is a CLI command that provisions a real sandbox without an account. Bu’s framing:

“When we built the CLI, it was originally so that developers could test web hooks locally. But as the ecosystem evolved, so did our CLI usage. And today, the CLI has become one of the primary interfaces for agents to interact with Stripe’s capabilities. We didn’t originally build it for agents, but we’re really leaning into it now.”

New flow: Claude calls stripe sandbox create, the CLI fetches keys and stores them locally, the agent has real credentials against real Stripe infrastructure, webhooks fire, errors round-trip, no manual signup. Once the project is real, the user signs up and claims the sandbox into a real account.

Jeff Weinstein, Stripe’s head of payments, crystallized it:

When we first launched the @stripe CLI seven years ago, humans kinda liked it. Today, agents love it.

— @jeff_weinstein Apr 30, 2026

267 likes — heavy for a Stripe-internal voice, second only to Pejman John’s Link CLI demo at 2,076.

Stripe did not invent a new tool for agents. They re-positioned the existing one. Every API company has a CLI; most treat it as developer convenience. Almost none have re-architected it as the agent interface. Vercel’s CLI, Supabase’s CLI, Cloudflare’s wrangler: all good for humans, all undertooled for agent loops that need to provision, store credentials, and operate isolated environments without manual signup.

Stripe Projects extends the bet. Sentry on Stripe Projects: “2 CLI commands to provision error monitoring + tracing, billing through your existing Stripe account, works with Claude Code, Cursor, and any coding agent.” Jason Liu at OpenAI publicly asked for an intro to the Stripe Projects team for OpenAI’s own integration. The CLI-as-agent-interface is the new platform-distribution surface.

Action: Audit your CLI. Can an agent provision an isolated sandbox in one command without any human signup? Can it store credentials securely? Can it claim that sandbox into a real account later? If any answer is no, you are friction-priced out of every coding-agent integration loop in 2026.

Step 7 — Auto-render Custom Object Dashboards from schema

The closing piece is the quiet one: Custom Objects.

Define a schema on your Stripe account, say, customer_follow_up with fields for customer, refund_amount, refund_reason, status, completed_by, notes. Stripe auto-generates a typed SDK, exposes it through the API, and renders a list-and-detail dashboard inside the Stripe Dashboard. Attach a complete_followup server-side method to the object and Stripe wires up a button in the dashboard that runs it.

This is Retool as a primitive of your billing platform. The Tempo team captured the larger frame in a 209-like tweet: “@collison showed an agent acting as both buyer and seller in the same loop. Using Stripe Projects and Tempo Wallet, the agent paid $0.04 for an Alpha Vantage dataset in stablecoins, generated a research report, listed it for sale to humans and agents.” Without Custom Objects + Workflows + Custom Actions, half that loop has nowhere to live. @ona_hq noted Stripe’s Alistair Gray will speak at Background Agents Virtual Summit on May 6–7 about exactly this surface.

Action: Pick the three nouns in your domain that customers always model in Postgres + Retool: opportunities, tickets, claims, follow-ups, shipments, audit rows. Ship a schema primitive that lets them define those nouns inside your platform, with auto-rendered dashboards and attached server-side methods. Become the substrate, or watch Retool/Internal/Appsmith hold the customer surface above you.

Stripe vs the rest of the API world

The seven-step playbook is portable. The question is whether the platforms most likely to compete for developer mindshare have any of it.

Stripe is the only platform on the board that has shipped all seven. Anthropic has the SKILL spec. Vercel has the cleanest CLI in the industry, and the Vercel AI Gateway is the closest equivalent of a “make any model call deterministic” surface. Cloudflare has the strongest agent-runtime story (AgentKit, Durable Objects, Workers AI). None of them have the full loop. Given the MCP ecosystem map we ran last week, the gap is now visible: every developer platform’s roadmap will get rewritten against this template.

Why devtools Twitter slept on this

The silence is information. The dev keynote ran 28 minutes against a two-hour main keynote packed with headline numbers (288 launches, Tempo, Atlas at 100,000 incorporations, Treasury, Bridge, Privy), and AI Ascent ran concurrently in everyone’s feeds. The most-credentialed developer voices read the press release, watched the headline reel, and posted about Link CLI or Stripe Projects. Both real. Neither is the architectural argument.

The architectural argument lives in the dev keynote, and it is what generalizes. Pejman John’s Link CLI demo is great, but it is a downstream artifact of steps 5 and 6. Watch the dev keynote first and the headline reel reads as inevitable: the productized expression of a framework that already shipped.

Where this lands for everyone else

Every API company that wants developer share in 2026 has to ship six of these seven steps before Q4. Step 7 (auto-rendered dashboards from schema) is platform-specific and may not apply outside billing-shaped products. The other six are universal.

The first to ship them after Stripe will be Cloudflare. They already have AgentKit, an MCP-native runtime, Workers as the actuator, and a CLI culture. Vercel has the distribution but lacks the structured-error and approval-contract primitives. Supabase, Clerk, PostHog, Linear, Resend: all are vulnerable to whichever competitor ships the playbook in their category first. The advantage is going to compound: the platform whose docs an agent prefers, whose SKILL file an agent loads first, whose CLI an agent provisions first, will sit underneath every coding-agent integration in its category.

This is the services-as-software thesis applied to platform plumbing. The platforms underneath agent-built products are about to consolidate fast, and the consolidation criterion is no longer “best React SDK” or “best dashboard.” It is “best agent-experience surface.”

Bu closed the keynote with a line worth re-reading:

“We’ve been obsessing over developer experience for 15 years. Agent experience is just the next chapter.”

The asymmetry is that most platforms have not started writing chapter one yet. The seven steps above are the chapter outline. The first competitor to adopt them cleanly is the one in the strongest position when the next round of agentic-product RFPs land.