# API reference

The reference is read from the spec Rivr's platform publishes for `/api/public`, vendored in the portal and compared with the test environment in CI. The operations' own texts are in the spec's language. The reference follows the sandbox, which is ahead of production: an operation the production spec doesn't have yet is labelled "Sandbox only for now". The portal also adds `x-rivr-error-codes` to every operation in the `/api/public` spec that the error catalog knows, in `/openapi/api-public.json` and in the MCP tool `get_openapi`: an object from error code to HTTP status with the codes the operation can answer with, in alphabetical order. Every code has a page in the error catalog, and the codes that only the sandbox has for now are included. The codes the key check in front of `/api/public` answers with, for example `key_invalid`, are not included, because the error catalog doesn't tie them to an operation. An operation the error catalog doesn't know gets no extension. The addition is made when the spec is read in: the vendored copy is not changed.

The examples target the sandbox (`https://api.test.rivr.io`) and need test credentials.

## /api/public

The surface journal systems integrate with today: orders, clinics, settlements, subscriptions and onboarding, with the platform's and the clinic's tokens. The callback to an order's `callbackUrl` is under Webhooks.

- API reference: https://developers.rivr.io/reference/api-public.md
- The spec: https://developers.rivr.io/openapi/api-public.json
- The Postman collection: https://developers.rivr.io/postman/rivr-api-public.postman_collection.json

### Health

- [GET /api/public/health](https://developers.rivr.io/reference/api-public/getHealth.md): Health check
- [GET /api/public/health/client-ip](https://developers.rivr.io/reference/api-public/getClientIp.md): Client IP address
- [GET /api/public/health/ready](https://developers.rivr.io/reference/api-public/getReadiness.md): Readiness check
- [GET /api/public/health-secure](https://developers.rivr.io/reference/api-public/getHealthSecure.md): Health check (authenticated)

### OnboardingLinks

- [GET /api/public/onboarding-links](https://developers.rivr.io/reference/api-public/getOnboardingLinks.md): List onboarding links
- [POST /api/public/onboarding-links](https://developers.rivr.io/reference/api-public/createOnboardingLink.md): Create onboarding link
- [GET /api/public/onboarding-links/{id}](https://developers.rivr.io/reference/api-public/getOnboardingLink.md): Retrieve onboarding link
- [POST /api/public/onboarding-links/{id}/refresh](https://developers.rivr.io/reference/api-public/refreshOnboardingLink.md): Refresh onboarding link

### Device

- [GET /api/public/devices](https://developers.rivr.io/reference/api-public/getDevices.md): Get all devices for the current merchant

### Merchant

- [GET /api/public/merchants](https://developers.rivr.io/reference/api-public/listMerchants.md): Retrieve a paged list of Merchants
- [GET /api/public/merchants/{merchantId}](https://developers.rivr.io/reference/api-public/getMerchant.md): Retrieve a Merchant by MerchantId

### Onboarding

- [GET /api/public/onboarding/progress](https://developers.rivr.io/reference/api-public/getOnboardingProgress.md): Retrieve onboarding progress for the authenticated platform

### Order

- [GET /api/public/orders/{orderId}](https://developers.rivr.io/reference/api-public/getOrder.md): Retrieve Order
- [PUT /api/public/orders/{orderId}](https://developers.rivr.io/reference/api-public/createOrder.md): Create Order
- [GET /api/public/orders/{orderId}/status](https://developers.rivr.io/reference/api-public/getOrderStatus.md): Retrieve Order Status
- [GET /api/public/orders/{orderId}/receipts/{receiptId}](https://developers.rivr.io/reference/api-public/getOrderReceipt.md): Retrieve Order Receipts
- [POST /api/public/orders/{orderId}/refund](https://developers.rivr.io/reference/api-public/refundOrder.md): Refund Order
- [POST /api/public/orders/{orderId}/cancel](https://developers.rivr.io/reference/api-public/cancelOrder.md): Cancel Order
- [POST /api/public/orders/{orderId}/send-to-device](https://developers.rivr.io/reference/api-public/sendOrderToDevice.md): Send Order to Device

### OrderSettlement

- [GET /api/public/order-settlements](https://developers.rivr.io/reference/api-public/listOrderSettlements.md): Retrieve a paged list of OrderSettlements
- [GET /api/public/order-settlements/{orderSettlementId}](https://developers.rivr.io/reference/api-public/getOrderSettlement.md): Retrieve Order Settlement
- [GET /api/public/order-settlements/next-unread](https://developers.rivr.io/reference/api-public/getNextUnreadSettlement.md): Retrieve Next Unread Order Settlement

### Subscription

- [POST /api/public/subscriptions](https://developers.rivr.io/reference/api-public/createSubscription.md): Creates or updates a subscription
- [GET /api/public/subscriptions/{subscriptionId}](https://developers.rivr.io/reference/api-public/getSubscription.md): Get a subscription by id

### Webhooks

- [POST {callbackUrl} (callback)](https://developers.rivr.io/reference/api-public/receiveCallback.md): Callback to your callbackUrl