# About GraphQL

Use this page when you need to call the Luxonis Hub GraphQL control API from your own backend or server-side tooling. It explains
the public request shape, the key Hub-specific boundaries, and the common patterns you need before moving into workflow guides or
schema reference.

Jump to:

 * [Start here](#About%2520GraphQL-Start%2520here)
 * [Request shape](#About%2520GraphQL-Request%2520shape)
 * [Example queries](#About%2520GraphQL-Example%2520queries)
 * [Hub-specific boundaries](#About%2520GraphQL-Hub-specific%2520boundaries)
 * [Core concepts you will see in the
   schema](#About%2520GraphQL-Core%2520concepts%2520you%2520will%2520see%2520in%2520the%2520schema)

## Start here

Send GraphQL requests to:

```http
https://api.cloud.luxonis.com/graphql
```

Use HTTP POST with:

 * Content-Type: application/json
 * Authorization: Bearer <your_api_key>

For external integrations, use the public team { ... } surface and keep Hub API keys in your backend only. See [API
Keys](https://docs.luxonis.com/cloud/api/api-keys.md) if you have not set up authentication yet.

## Request shape

Every GraphQL request has the same practical structure:

 1. Operation definition such as query or mutation, plus an operation name and optional variable definitions.
 2. Selection set that lists the exact fields you want back.
 3. Variables object sent as JSON alongside the query so values stay separate from the document.
 4. HTTP transport envelope with the Authorization and Content-Type headers.

This is a typical Luxonis Hub request:

```json
{
  "query": "query Devices($first: Int!, $after: String) { team { devices(first: $first, after: $after) { nodes { id name status } } } }",
  "variables": {
    "first": 25,
    "after": null
  }
}
```

Because GraphQL responses mirror your selection set, you can ask only for the fields your workflow needs and add more fields later
without changing the endpoint.

## Example queries

### List devices

Use team { ... } as the root for public control-plane integrations:

```graphql
query Devices($first: Int!, $after: String) {
  team {
    devices(first: $first, after: $after) {
      nodes {
        id
        name
        status
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

### Update device state

Mutations change control-plane state:

```graphql
mutation UpdateDevice($input: UpdateDeviceInput!) {
  updateDevice(input: $input) {
    clientMutationId
  }
}
```

The schema defines the exact fields allowed inside UpdateDeviceInput, so use the reference pages or introspection to inspect the
current input shape before wiring production flows.

## Hub-specific boundaries

### Public surface

For external integrations, the GraphQL control API should be understood as the public team { ... } surface.

### Authentication boundary

Hub API keys are backend-only secrets. The recommended customer integration model is:

 1. Your users authenticate to your own frontend and backend.
 2. Your backend stores the Hub API key.
 3. Your backend calls Hub GraphQL.
 4. Your frontend receives only the derived payload it needs.

### Schema inspection

GraphQL introspection is available. Use it together with the official guides and reference pages when you inspect types, fields,
and input shapes.

### Real-time behavior

GraphQL subscriptions are not the public integration path today. Use queries and mutations for control-plane work, and use the
streaming/bootstrap guides for browser-side device or app sessions.

## Core concepts you will see in the schema

You do not need a full GraphQL tutorial to work with Hub, but these concepts appear often in the schema and examples:

 * Object types and fields define the resources and attributes you can query, such as Device, Team, or App.
 * Arguments and variables let you pass pagination, filtering, and input values without rewriting the query string.
 * Input objects group structured mutation inputs such as UpdateDeviceInput.
 * Enums, interfaces, and unions describe constrained values and polymorphic response shapes.
 * Connections are the pagination pattern that uses fields such as nodes, edges, and pageInfo.

If you need to inspect these shapes directly, use introspection in a GraphQL client or continue to the control API reference
pages.

## Next steps

 * Continue with [Integration Guides](https://docs.luxonis.com/cloud/api/guides.md) for end-to-end backend workflows.
 * Use [Streaming and Visualizer](https://docs.luxonis.com/cloud/api/guides/streaming-and-visualizer.md) for browser connection
   bootstrap and remote session flows.
 * Explore [Schema Reference](https://docs.luxonis.com/cloud/api/reference/control-api/schema.md),
   [Queries](https://docs.luxonis.com/cloud/api/reference/control-api/queries.md), and
   [Mutations](https://docs.luxonis.com/cloud/api/reference/control-api/mutations.md) for the current control API surface.