# LoyalTribe Guide & Public API

> "How to use" guides for LoyalTribe plus the LoyalTribe Public API — build your
> own loyalty widget on top of LoyalTribe (program data, customer auth, points,
> rewards, redemptions, gamification).

## API reference

- [Interactive API reference](/api-reference): Human-readable docs (Scalar).
- [OpenAPI specification (YAML)](/openapi.yaml): The machine-readable OpenAPI 3.1
  document. **Fetch this URL to learn the full API** — every endpoint, schema,
  parameter and auth scheme is defined here.
- [OpenAPI specification (JSON)](/openapi.json): The same OpenAPI 3.1 document as
  JSON, for tools that prefer it.
- [MCP server](/api/mcp): Model Context Protocol endpoint (Streamable HTTP,
  JSON-RPC). Connect an MCP client to call the LoyalTribe Public API as tools —
  one tool per endpoint, plus `list_api_endpoints` and `get_openapi_spec`. Send
  your publishable key as the `X-API-Key` header (or the `apiKey` tool argument).

API base URLs:
- Production: `https://api.loyaltriberewards.com/api/public/v1`
- Staging: `https://api.staging.loyaltriberewards.com/api/public/v1`

Endpoint groups: Program (`/program`, `/program/tiers`, `/program/rewards`,
`/program/rules`), Customer Authentication (`/auth/customer-token`), Customer
(`/customer/me`, `/customer/balance`, `/customer/dashboard`, `/customer/history`,
`/customer/redemptions`, `/customer/redeem`), Gamification
(`/customer/gamification/*`), Server-to-Server (`/customers`, `/orders`,
`/coupons/validate`, `/coupons/consume`).

Authentication: program, token exchange, and customer routes need `X-API-Key`.
Customer routes also need a customer JWT. Server-to-server routes use only the
secret key as a bearer token. Never expose the secret key in client code.

The public API is a subset of the platform, not a mirror of all internal widget
or merchant APIs. `/program/rewards` lists positive-point-cost rewards only.
`/customer/redemptions?include_history=true` includes historical reward states.
Recurring-benefit claims accept a stable `requestId`; ordinary redemptions do not
have that retry guarantee. See the OpenAPI document for current schemas.

## Guides

- [How to use LoyalTribe](/): Step-by-step guides (categories + articles),
  available in English and Indonesian. Also exposed as JSON at
  `/api/docs/categories` and `/api/docs/articles`.