Build with AI agents
Everything in these docs is available to AI assistants and coding agents: llms.txt, a Markdown copy of every page, a structured index, and WebMCP tools. An agent can also connect to your account through agent sign-in, with the access you choose.
On this page
Give your assistant the docs
Point your coding assistant at one of these, depending on how much context it can take:
| Resource | What it is |
|---|---|
| /docs/llms.txt | A summary of the API and its rules, with a link to every page. Start here |
| /docs/llms-full.txt | Every docs page in one Markdown file |
/docs/<page>.md | Any page as Markdown: add .md to its path, as in /docs/quickstart.md. The overview is /docs/index.md |
| Any page, asking for Markdown | A request whose Accept header prefers text/markdown, as coding agents send, gets the page's Markdown copy instead of its HTML |
| /agents/docs.json | A structured index: every page, section and endpoint, with links |
| /auth.md | Agent sign-in: how an agent asks for its own access to your account, which you approve. See Connect an agent |
Each page also has Copy page for AI in its sidebar, which copies the page's Markdown for pasting into a chat.
Any Railbed link leads here
You can give your assistant any Railbed address, not only these docs, and it will find its way:
- An assistant that asks for Markdown gets the page's Markdown copy, and every copy names
/docs/llms.txtnear its top, so one page leads to the rest. - Every page's HTML also carries a short note for AI assistants, following the inline llms.txt proposal. Browsers don't show it; an assistant reading the raw page gets links to the page's Markdown copy and to
llms.txt. - Dashboard and checkout links (
app.railbed.io,pay.railbed.io) draw their pages in JavaScript, so their HTML carries a hidden note pointing to these docs, and both hosts serve an/llms.txtthat does too.
Read https://railbed.com/docs/llms.txt and the pages it links to that you need.
Then add Railbed card checkout to this app: create a checkout session on the server
when the user clicks Buy, redirect to its url, and fulfil the order from a verified
payment.paid webhook. Use my test key from RAILBED_SECRET_KEY and my webhook secret
from RAILBED_WEBHOOK_SECRET. Deduplicate on the event id.Rules worth giving an agent
These are the mistakes that matter most in a payments integration. They're in llms.txt too.
- Call the API only from a server, with the key in an environment variable. There is no publishable key.
- Fulfil only when a payment is
paid, confirmed by a verified webhook orGET /v1/payments/:id. Never from the buyer's return tosuccess_url. - Verify webhook signatures against the raw body, and deduplicate on the event
id. - Send an
Idempotency-Keywith every create. - Treat
heldas not paid, andexpiredas possibly paid later. - Send the order as
order, with items whose total lessdiscountplusshippingandtaxequalsamountto the cent, and your order id inorder.id. On409 order_paid, don't ask the buyer to pay again. - Ship each order once, keyed on its order id, and report it with
PATCH /v1/orders/:id. - Start in Test mode (
rb_test_…keys) and simulate outcomes; no money moves.
Connect an agent to your account
An AI agent can use the Railbed API on your account without a secret key. You approve it once in the dashboard, it gets its own short-lived access, and you can disconnect it at any time. This is agent sign-in, and everything the agent needs to know is at railbed.com/auth.md.
How connecting works
- Ask your agent to connect to your Railbed account, and tell it the email address you sign in with. It reads railbed.com/auth.md and follows it.
- Your agent gives you a link to approve it. It opens Connect an AI agent on
app.railbed.io. Sign in with the same email address you gave the agent. The link works for a few minutes; if it has expired, ask your agent for a new one. - Check the business, give the agent a name you'll recognize, and choose the mode and the access level. Test and Full access are selected to start with.
- Choose Connect agent. The page shows Your agent's code. Give it to your agent, in the conversation where you asked it to connect. The code works once, for a few minutes.
- The agent finishes connecting and starts using the API. It's listed in Developers under AI agents, in the mode you chose.
Only owners and developers of a business can connect an agent to it, the same people who can create secret keys. If a link has expired or was already used, ask the agent to start again.
The access you choose
| Choice | What the agent can do |
|---|---|
| Test | Work with Test data only. Payments are simulated and no money moves, so it's the place to try an agent out |
| Live | Work with your real payments, orders and customers |
| Full access | Everything the API allows: create and start checkout sessions, read payments, orders and customers, and update orders |
| Read only | Look up payments, checkout sessions, orders and customers. It can't create or change anything |
A connection works in one mode, like a secret key. An agent connected in Test can't see Live data. It uses access tokens that last about five minutes and gets new ones itself, so there's no key for you to create, paste or rotate.
Disconnect an agent
In Developers, AI agents lists the agents connected in the current mode, with who approved each one and when it was last used. Choose Disconnect next to an agent and confirm. Its next request is refused. To use it again, it has to ask to connect again, and someone has to approve it.
An agent also loses its access for good when the person who approved it leaves the business, moves to a role that can't manage keys, or has their access disabled. Putting them back doesn't restore it: an owner or developer connects the agent again.
For agent developers
auth.md describes the whole flow, with request templates. WorkOS, which runs Railbed's sign-in, hosts the registration, claim and token endpoints it lists. The API itself is https://pay.railbed.io/v1.
- Register with the person's email address (
service_auth). Anonymous registration isn't offered. - Give the person the claim link, wait for the code they read back to you, and complete the claim.
- Exchange your identity assertion for an access token. Access tokens last about five minutes. Get the next one yourself, as auth.md describes.
- Call the API with
Authorization: Bearer <access token>, the way a server sends a secret key. The token carries the business, the mode and the access level the person chose. Authentication lists each endpoint's scope. - On
401 invalid_token, get a new access token. On401 agent_disconnected, ask the person to connect you again. On403 insufficient_scope, the person chose Read only: tell them what you need and why.
WebMCP tools
WebMCP lets a web page offer tools to an AI agent working in the visitor's browser, so the agent can act through the page's own logic instead of reading the screen. Railbed's pages offer tools in browsers that support it; elsewhere nothing changes.
On railbed.com and these docs
Every page on railbed.com, including these docs, offers tools for learning about Railbed and building with it. All are read-only except the two that open signup or login.
| Tool | What it does |
|---|---|
railbed_status | Current service availability, observation times and check coverage; optionally filter by service. It fetches fresh results, not saved browser history. This does not verify a payment or settlement |
railbed_docs_search | Search the developer docs; returns the best matching sections with links |
railbed_docs_read | A docs page, or one section of it, as Markdown |
railbed_api_reference | Every API endpoint with its method, path and reference link, plus the base URL and the rules for authentication, idempotency, money and errors |
railbed_webhook_reference | The webhook event types, when each is sent, the signature scheme and the retry schedule |
railbed_code_samples | The docs' code examples, filtered by topic and language |
railbed_overview, railbed_faq, railbed_search, railbed_read_page, railbed_contact | What Railbed is, the FAQ, and the company and legal pages |
railbed_start_signup, railbed_open_login | Take the visitor to signup (email optionally filled in) or login. Nothing is submitted for them |
In the dashboard
When a merchant is signed in, onboarding and the Wallet, Developers, Integrations, Shopify and WooCommerce pages offer tools that work on their account, in the mode the dashboard is in (Test or Live). They run with the merchant's own session, in their browser, so an agent can do only what the merchant could.
| Tool | Page | What it does |
|---|---|---|
railbed_onboarding_status | Onboarding | Where setup stands: whether the business name and payout wallet are saved, the main way to sell, and the ways the account can choose, with what each involves |
railbed_prepare_sales_channel | Onboarding | Open How will you take payments? with one way selected, for the merchant to confirm with Continue. Tools never fill in the payout wallet |
railbed_setup_checklist | Wallet | The Your first payment steps for the merchant's way to sell: each step, whether it's done, where it's done or who can do it, and the optional extras |
railbed_developer_status | Developers | The mode, the setup steps done so far, and a summary of keys, endpoints and connected AI agents |
railbed_list_api_keys | Developers | The keys, masked (rb_test_••••••••3f9a), with their access level and when each was created and last used |
railbed_list_agent_connections | Developers | The AI agents connected in this mode: name, access level, who approved it, and when it connected and was last used |
railbed_list_webhook_endpoints | Developers | Endpoints with their addresses, labels, events and latest delivery. Signing secrets are never included |
railbed_list_webhook_deliveries | Developers | An endpoint's recent deliveries: status, attempts, your server's answer and, if asked, the body sent |
railbed_send_test_webhook | Developers | Send a signed test event to an endpoint and report how it answered. Test endpoints take any event type; Live endpoints take ping only |
railbed_prepare_api_key | Developers | Open Create key with a name filled in. The merchant creates it; the secret is shown only to them |
railbed_prepare_webhook_endpoint | Developers | Open Add endpoint with the address, description and events filled in, for the merchant to review and save |
railbed_open_webhook_deliveries | Developers | Open an endpoint's delivery log, optionally filtered to failed or retrying deliveries, so the merchant can resend |
railbed_list_integrations | Integrations | The ways to take payments (links, checkouts, the API, store plugins), their status and where to set each up |
railbed_list_card_providers | Integrations | The card providers Railbed routes to, with their status and minimum amounts (in Test mode, the fixed test list) |
railbed_shopify_status | Shopify | Each connected store's setup steps and the checks behind them, its own Test or Live mode, ad-tracking ids set, failed syncs, and the exact values to paste into Shopify. Never the client secret or tracking tokens |
railbed_list_shopify_checkouts | Shopify | A store's recent checkouts, newest first: the buyer's email, items, total, payment status, and how far the Shopify draft or order got, with the error when a sync failed. Optionally only failed syncs |
railbed_send_shopify_test_event | Shopify | Send one test event to an ad platform or affiliate postback set up in the Ad tracking card, and report whether it was accepted. It never counts as a sale |
railbed_prepare_shopify_store | Shopify | Open Connect a store with the address filled in, for the merchant to confirm |
railbed_prepare_shopify_retry | Shopify | Open the confirmation to send a checkout whose sync failed to Shopify again |
railbed_prepare_shopify_mode | Shopify | Open the confirmation to take a store Live or back to Test. Refused, with what's missing, when the store isn't ready |
railbed_woocommerce_setup | WooCommerce | Where setup stands: the plugin download, the four steps, the store's webhook address and last delivery, and recent WooCommerce orders. Never keys or secrets |
Some things are deliberately left to the merchant. Tools never return a secret key or a signing secret, and they never create or revoke keys, roll secrets, remove endpoints or resend real events: those open the dashboard's own dialog for the merchant to confirm, or aren't offered at all.