Generic GraphQL Client

This guide covers how to connect to the Lumar GraphQL API from any programming language or HTTP client.

Endpoint

All GraphQL requests are sent as HTTP POST requests to:

https://api.lumar.io/graphql

Headers

Every request must include:

Header	Value
Content-Type	application/json
x-auth-token	Your session token (obtained via createSessionUsingUserKey)

Optionally include:

Header	Value
apollographql-client-name	A name identifying your client application
apollographql-client-version	The version of your client application

Request body

The request body is a JSON object with the following fields:

{
  "query": "query { me { id username } }",
  "variables": {},
  "operationName": "OptionalOperationName"
}

Example with curl

Authenticate

curl -X POST https://api.lumar.io/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Login($userKeyId: ObjectID!, $secret: String!) { createSessionUsingUserKey(input: { userKeyId: $userKeyId, secret: $secret }) { token } }",
    "variables": {
      "userKeyId": "TjAwN1VzZXJLZXkxMzA",
      "secret": "your-user-key-secret"
    }
  }'

Make authenticated requests

curl -X POST https://api.lumar.io/graphql \
  -H "Content-Type: application/json" \
  -H "x-auth-token: YOUR_TOKEN_HERE" \
  -d '{
    "query": "query { me { id username accounts(first: 5) { nodes { id name } } } }"
  }'

Downloading the schema

You can download the full schema using GraphQL introspection:

curl -X POST https://api.lumar.io/graphql \
  -H "Content-Type: application/json" \
  -H "x-auth-token: YOUR_TOKEN_HERE" \
  -d '{"query": "{ __schema { types { name kind fields { name type { name kind ofType { name } } } } } }"}'

Alternatively, download the schema SDL from the public schema page.

Language-specific libraries

Most languages have mature GraphQL client libraries. Here are some popular options:

Language	Library	Link
Go	github.com/hasura/go-graphql-client	GitHub
Java	graphql-java	graphql-java.com
Ruby	graphql-client	GitHub
PHP	webonyx/graphql-php	GitHub
C#	GraphQL.Client	GitHub

All of these libraries support sending POST requests to a GraphQL endpoint with custom headers, which is all you need to interact with the Lumar API.

Tips

• Always use variables for dynamic values instead of string interpolation to avoid injection issues.
• Set apollographql-client-name and apollographql-client-version headers to help with debugging and analytics.
• Handle pagination using cursor-based first / after parameters. See Pagination.
• Respect rate limits -- implement retry logic with exponential backoff for HTTP 429 responses.