> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getopenrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent integration

> Use Open Rails with coding agents, runtime schemas, and compact machine-readable surfaces.

Open Rails is designed for agents to integrate without scraping the dashboard. Agents should use the capability endpoint, runtime schema endpoint, and the hosted skill file before mutating anything.

## Install the skill

```bash theme={null}
npx skills add winterrx/getopenrails
```

The skill tells agents what Open Rails can do, what endpoints to inspect, and what safety constraints matter.

## Fetch capabilities

```bash theme={null}
curl https://dash.getopenrails.com/api/agent/capabilities
```

This returns entrypoints, webhook events, schema routes, action descriptors, planned CLI commands, and MCP-compatible tool metadata.

## Inspect schemas

```bash theme={null}
curl https://dash.getopenrails.com/api/agent/schema/checkout.create
curl https://dash.getopenrails.com/api/agent/schema/fees.estimate
curl https://dash.getopenrails.com/api/agent/schema/webhook.example
```

Agents should generate payloads from these schemas instead of copying stale examples from a prompt.

## Read-only resource tools

After creating a checkout session, agents can read back records using the gateway endpoints:

```bash theme={null}
# List customers
curl "https://dash.getopenrails.com/api/gateway/customers?email=buyer@example.com"

# Fetch a customer
curl https://dash.getopenrails.com/api/gateway/customers/cus_7G42M9

# List payments for a customer
curl "https://dash.getopenrails.com/api/gateway/payments?customerId=cus_7G42M9"

# Fetch a payment by session ID
curl https://dash.getopenrails.com/api/gateway/payments/chk_nimbus_1056

# List invoices for a customer
curl "https://dash.getopenrails.com/api/gateway/invoices?customerId=cus_7G42M9"

# Fetch an invoice
curl https://dash.getopenrails.com/api/gateway/invoices/inv_xyz789
```

All list endpoints return `{ "object": "list", "data": [], "hasMore": false }`.

## Mutation rules

* Prefer `checkout.preview` and `fees.estimate` before `checkout.create`.
* Use `environment: "sandbox"` until the merchant has production provider credentials.
* Always set an `idempotencyKey` for order-backed checkouts.
* Pass `redirectUrl` per checkout session when the merchant needs dynamic return pages.
* Treat production activation and provider credential connection as human-approved steps.

## Recovery pattern

When an API call fails, parse the `error.code`, `error.issues`, and `error.suggestion` fields. Do not retry blindly. Fetch the schema for the failed operation, repair the payload, and retry once with the same idempotency key.