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

# How the GraphQL API works

> One endpoint, queries and mutations, and the response format you can expect from every call.

Fluz exposes a single GraphQL endpoint per environment. There are no versioned REST paths and no per-capability base URLs — you send a query or mutation to `/graphql`, and the token decides whose account you're operating on.

## Endpoints

| Environment | URL                                                              |
| ----------- | ---------------------------------------------------------------- |
| Staging     | `https://transactional-graph.staging.fluzapp.com/api/v1/graphql` |
| Live        | `https://transactional-graph.fluzapp.com/api/v1/graphql`         |

Access tokens are minted from a separate OAuth service at `https://oauth-service.fluzapp.com`.

## Anatomy of a request

```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetWallet($id: ID!) { wallet(id: $id) { balance { value currency } } }",
    "variables": { "id": "wal_01H..." }
  }'
```

* **`query`** — the GraphQL document. Use named operations (`query GetWallet`) for better logs.
* **`variables`** — typed inputs, keeping values out of the query string.
* **`operationName`** — optional, useful when a document defines multiple operations.

## Queries vs. mutations

* **Queries** are read-only (`viewer`, `wallet`, `transactions`).
* **Mutations** change state (`createVirtualCard`, `purchaseGiftCard`, `depositCashBalance`, `createTransfer`).

Money-moving mutations use request de-duplication — see [Idempotency](/concepts/idempotency).

## Response format

GraphQL always returns HTTP 200 with a `data` / `errors` envelope:

```json theme={null}
{
  "data": { "wallet": { "balance": { "value": 12500, "currency": "USD" } } },
  "errors": null,
  "extensions": { "requestId": "req_01H..." }
}
```

On failure, `data` may be `null` and `errors` will describe what went wrong — including a machine-readable `code` you can branch on. See [Errors](/api-reference/errors).

## Introspection and schema

Introspection is enabled in staging so you can point tools like Apollo Studio or GraphiQL at the endpoint. In live, introspection is disabled; use the published schema from [API reference](/api-reference/overview) instead.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/concepts/authentication">
    How the token in that `Authorization` header gets minted — for your account or a customer's.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/api-reference/errors">
    What the `errors` array contains and how to branch on error codes.
  </Card>
</CardGroup>