API Overview

Current published contract

The current developer contract published from pinrail-platform is broader than the original four report reads. The safest way to discover the live surface is now:

curl -sS \
  -H 'X-API-Key: $PINRAIL_API_KEY' \
  https://api.pinrail.xyz/v1/integrations/catalog

That catalog is the contract-derived index for the current public-facing integration surface.

For machine-readable tooling, pinrail-platform also publishes a public OpenAPI companion at GET /v1/integrations/public-openapi.json. Use the catalog when you want a curated service inventory first, and use the OpenAPI document when you want schema-driven SDK or docs generation from the same public contract surface.

Current endpoint families

The live catalog currently groups endpoints into these families:

• account and fleet snapshot
• terminals, locations, and telemetry
• transactions and processor activity
• RMS, commands, connectors, and provisioning
• settlements, payouts, and disputes
• branding and public status
• portal-first compliance, onboarding, documents, and videos

Recommended first calls

For most customer and sponsor-bank integrations, start with:

• GET /v1/portal
• GET /v1/integrations/catalog
• GET /v1/transactions
• GET /v1/settlements
• GET /v1/disputes

Then branch into narrower contract surfaces such as terminal telemetry, connector status, provisioning export, RSS feeds, or webhook subscriptions.

Additional live surfaces

The current contract also includes:

• RSS endpoints at GET /v1/feeds/account.xml and GET /v1/feeds/terminals/{terminal_id}.xml
• a public branding readiness endpoint at GET /v1/public/branding-status
• a public OpenAPI contract at GET /v1/integrations/public-openapi.json for cacheable docs and SDK ingestion
• account- and terminal-scoped webhook subscription flows documented from the current TMS behavior

Scope and guardrails

Read APIs are the safest default because they mirror the same account, role, and visibility rules already enforced in the portal. Several write paths exist for operational workflows, but configuration-changing behavior remains more privileged than ISO-safe reporting reads.

Next pages

• Integration Catalog for the live service-by-service inventory
• Portal Data APIs for the most common read paths
• Webhooks for the current signed delivery model
• RSS Feed for the currently published feed endpoints