# Generic GraphQL Client

https://api-docs.lumar.io/docs/graphql-clients/generic

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:

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

## Example with curl

### Authenticate

```bash
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

```bash
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:

```bash
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](/docs/graphql/public-schema.md).

## 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](https://github.com/hasura/go-graphql-client)                 |
| Java     | `graphql-java`                        | [graphql-java.com](https://www.graphql-java.com/)                     |
| Ruby     | `graphql-client`                      | [GitHub](https://github.com/github-community-projects/graphql-client) |
| PHP      | `webonyx/graphql-php`                 | [GitHub](https://github.com/webonyx/graphql-php)                      |
| C#       | `GraphQL.Client`                      | [GitHub](https://github.com/graphql-dotnet/graphql-client)            |

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](/docs/graphql/pagination.md).
- Respect [rate limits](/docs/graphql/rate-limits.md) -- implement retry logic with exponential backoff for HTTP 429 responses.