# 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.

Source: https://railbed.com/docs/agents/ · Updated: 2026-10-05 · Railbed by DeepWork developer docs

For AI assistants: the index of every docs page, with the rules for an integration, is https://railbed.com/docs/llms.txt

## 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](https://railbed.com/docs/llms.txt) | A summary of the API and its rules, with a link to every page. Start here |
| [/docs/llms-full.txt](https://railbed.com/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](https://railbed.com/docs/quickstart.md). The overview is [/docs/index.md](https://railbed.com/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](https://railbed.com/agents/docs.json) | A structured index: every page, section and endpoint, with links |
| [/auth.md](https://railbed.com/auth.md) | Agent sign-in: how an agent asks for its own access to your account, which you approve. See [Connect an agent](#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.txt` near 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](https://vercel.com/blog/a-proposal-for-inline-llm-instructions-in-html) 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.txt` that does too.

Example: A prompt that works well

```text
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.
```

> [!IMPORTANT]
> Keep secret keys and webhook secrets out of prompts, chats and code. Put them in your server's environment and let the assistant refer to them by name. To let an agent use the API on your account, [connect it](#connect-an-agent) instead of pasting a key into the chat.

## 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 or `GET /v1/payments/:id`. Never from the buyer's return to `success_url`.
- Verify webhook signatures against the raw body, and deduplicate on the event `id`.
- Send an `Idempotency-Key` with every create.
- Treat `held` as not paid, and `expired` as possibly paid later.
- Send the order as `order`, with items whose total less `discount` plus `shipping` and `tax` equals `amount` to the cent, and your order id in `order.id`. On `409 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](https://railbed.com/docs/testing.md); 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](https://railbed.com/auth.md).

### How connecting works

1. 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](https://railbed.com/auth.md) and follows it.
2. 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.
3. 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.
4. 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.
5. The agent finishes connecting and starts using the API. It's listed in [Developers](https://app.railbed.io/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.

> [!WARNING]
> The code lets an agent into your account. Give it only to your own agent, right after you asked that agent to connect. Never type it into a website, and never give it to someone who contacted you and asked for it, by email, message or phone, whoever they say they are. If you didn't just ask an agent to connect, close the page.

### 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](https://app.railbed.io/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](https://railbed.com/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](https://railbed.com/docs/api.md#authentication) lists each endpoint's scope.
- On `401 invalid_token`, get a new access token. On `401 agent_disconnected`, ask the person to connect you again. On `403 insufficient_scope`, the person chose **Read only**: tell them what you need and why.

## WebMCP tools

[WebMCP](https://webmachinelearning.github.io/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](https://railbed.com/status/), 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.

> [!NOTE]
> Content returned by the delivery log and the Shopify checkout list includes data your buyers typed, such as their email, and your server's answers. Agents receive it marked as untrusted content.