API Reference
Rails Yield GraphQL API — endpoint, authentication, rate limits, error format, and per-resource reference for nodes, liquidity, and direct LND access.
The Rails Yield API is a single GraphQL endpoint shared with Rails Payments. It exposes monitoring, asset configuration, and withdrawal flows; node creation itself runs in the dashboard because it depends on browser-side cryptography (see Deploy a Node).
Endpoint
POST https://rails.amboss.tech/graphqlOpen the live schema in Apollo Studio for interactive exploration.
Authentication
Rails Yield operations are authenticated with your dashboard session token passed as a Bearer token. This is the same authentication used for master-account operations in the Payments API.
Authorization: Bearer $AMBOSS_DASHBOARD_TOKENService API keys (amb_live_… / amb_test_…) currently scope to Payments resources only (PAYMENTS, WALLETS, WEBHOOKS, ENVIRONMENTS). Yield-specific resolvers under node and liquidity_provider require dashboard auth. See Authentication for the full per-product matrix.
Grab the token from the auth_token cookie on a logged-in session at rails.amboss.tech, or via your team's SSO integration.
Operation namespaces
| Namespace | Purpose | Docs |
|---|---|---|
node | Node queries and mutations (deploy, connect, activate, withdraw, asset config) | Nodes API |
user.liquidity_provider | Balances, revenue, charts, transactions, asset balances | Liquidity API |
| Direct LND | Forwarded LND macaroon for direct daemon access | LND API |
Rate limits
| Limit | Value | Scope |
|---|---|---|
| Requests per minute | 60 | Per authenticated user / IP |
A 429 response indicates you've exceeded the limit. Back off and retry; there is no separate burst allowance.
Error format
GraphQL errors come back in the standard errors array. The mutation/query payload is still placed in data, with the failed field set to null.
{
"data": { "node": { "deployed_node": null } },
"errors": [
{
"message": "Node not found!",
"path": ["node", "deployed_node"],
"extensions": { "code": "INTERNAL_SERVER_ERROR" }
}
]
}Common error codes:
| Code | Meaning |
|---|---|
UNAUTHENTICATED | Missing or invalid Bearer token. |
FORBIDDEN | Authenticated, but the account lacks permission for the resource (e.g. non-master account creating environments). |
GRAPHQL_VALIDATION_FAILED | Input shape or required fields are wrong. |
INTERNAL_SERVER_ERROR | Server-side failure. In production the original message is redacted; check the message field for a safe-to-show explanation. |
User-facing messages are intentionally short ("Node not found!", "You can only change settings once a day"). Treat them as stable enough for switch statements but defensive about wording changes.
Pagination
Endpoints that return lists accept a page input with limit (default 10) and offset (default 0). The response includes total_count and a pagination { limit offset } block so a client can compute the next page.
transaction_list(input: { page: { limit: 50, offset: 100 } }) {
total_count
pagination { limit offset }
list { id type date }
}Network choices
Mutations that touch real Bitcoin operate on mainnet by default. Testnet, signet, and regtest are available to teams flagged for testing; they bypass the Stripe subscription on activate. Talk to your account contact if you need a non-mainnet node.
Versioning
The GraphQL schema is evolved additively. Breaking changes are extremely rare and pre-announced via Apollo Studio's schema change notifications.
Withdraw Funds
Initiate a Rails Yield withdrawal — set a withdrawal target, derive the master-account password hash, and track funds becoming available as channels unwind.
Nodes API
GraphQL reference for Rails Yield node operations — deploy, connect, activate, deactivate, change settings, and query state, sockets, credentials, and partners.