Agent integration

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

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

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

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:

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

Start

Guides

Reference

Install the skill

Fetch capabilities

Inspect schemas

Read-only resource tools

Mutation rules

Recovery pattern

​Install the skill

​Fetch capabilities

​Inspect schemas

​Read-only resource tools

​Mutation rules

​Recovery pattern

Install the skill

Fetch capabilities

Inspect schemas

Read-only resource tools

Mutation rules

Recovery pattern