How the GraphQL API works

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

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.

Response format

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

{
  "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.

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 instead.

Next steps

Authentication

How the token in that Authorization header gets minted — for your account or a customer’s.

Errors

What the errors array contains and how to branch on error codes.

Developers

Recipes

How the GraphQL API works

Endpoints

Anatomy of a request

Queries vs. mutations

Response format

Introspection and schema

Next steps

Authentication

Errors

​Endpoints

​Anatomy of a request

​Queries vs. mutations

​Response format

​Introspection and schema

​Next steps

Authentication

Errors

Endpoints

Anatomy of a request

Queries vs. mutations

Response format

Introspection and schema

Next steps