> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The interactive Expys /v1 reference and Try it playground, generated from the OpenAPI spec - how to authenticate, which token each tag needs, and where to read the streaming and webhook concepts.

The interactive reference and its **Try it** playground are generated directly
from the Expys OpenAPI spec, so every endpoint, parameter, schema, and example
matches the live `/v1` API. Use the playground to call endpoints from your
browser without writing any code.

## Base URL

All requests go to a single host:

```
https://api.expys.com
```

Sandbox and live share this host. The environment is **not** in the URL - it is a
property of the credential you authenticate with. A sandbox key reads sandbox
data, a live key reads live data. See [Environments](/environments).

## Authenticating the playground

Every operation is authenticated with a `Bearer` token pasted into the
playground's authorization field. **Which** token depends on the operation's
mode:

| Operation mode | Token to paste                                                 | Examples                                                       |
| -------------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
| Member mode    | A short-lived **member token** (from `POST /v1/auth/exchange`) | Offers, Redemptions, Eligibility, Wallet reads, Conversations  |
| Server mode    | Your **Org-API-Key** (`expys_live_...` / `expys_sandbox_...`)  | `auth/exchange`, Members, Analytics, `wallet/credit`, Webhooks |

<Warning>
  The Org-API-Key is a server-side secret. Use it in the playground only from a
  trusted machine, and never ship it in an app or client-side code. See
  [Authentication](/authentication) and [Server mode](/guides/server-mode).
</Warning>

To mint a member token for member-mode operations, call `POST /v1/auth/exchange`
with your Org-API-Key (it returns a `TokenGrant` with an `accessToken`), then
paste that `accessToken` to try member-mode endpoints. The full two-token model is
covered in [Authentication](/authentication).

<Note>
  Two parts of the API are documented as **concept pages**, not playground
  operations: SSE [streaming](/guides/streaming) (the concierge message stream is
  a long-lived Server-Sent Events connection, not a request/response call) and
  outbound [webhook deliveries](/guides/webhooks) (signed event POSTs that Expys
  sends to your endpoint). Read those pages for their contracts.
</Note>

## Endpoint groups

The reference is organized by tag. Each group below links to the concept guide
that explains its behavior, points-mechanics, and error codes; open the
corresponding tag in the **Endpoints** section of this reference to call the
operations.

<CardGroup cols={3}>
  <Card title="Auth" icon="key" href="/authentication">
    Exchange an Org-API-Key for a short-lived member token.
  </Card>

  <Card title="Offers" icon="ticket" href="/guides/offers">
    List the cursor-paginated offer catalog with points pricing.
  </Card>

  <Card title="Redemptions" icon="cart-shopping" href="/guides/redemptions">
    Create, read, and list redemptions across the lifecycle.
  </Card>

  <Card title="Eligibility" icon="user-check" href="/guides/eligibility">
    Read a member's tier and wallet in one call.
  </Card>

  <Card title="Wallet" icon="coins" href="/guides/points-and-wallet">
    Read balances and the points ledger; credit points server-side.
  </Card>

  <Card title="Members" icon="users" href="/guides/members">
    Set, read, and remove member profiles and tiers (server mode).
  </Card>

  <Card title="Analytics" icon="chart-line" href="/guides/analytics">
    Summary, per-offer, and time-series program analytics (server mode).
  </Card>

  <Card title="Conversations" icon="comments" href="/guides/conversations">
    List conversations and messages; send a member message.
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Register, list, and delete webhook subscriptions (server mode).
  </Card>
</CardGroup>

## See also

<CardGroup cols={2}>
  <Card title="Environments" icon="layer-group" href="/environments">
    How sandbox and live are selected by the key, not the URL.
  </Card>

  <Card title="Server mode" icon="server" href="/guides/server-mode">
    The Org-API-Key surface and what stays on your backend.
  </Card>
</CardGroup>