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

# GraphQL API Overview

> Introduction to the SensorUp federated GraphQL API, architecture, and available endpoints across multiple environments.

# GraphQL API Overview

The SensorUp platform provides a comprehensive GraphQL API built on Apollo Federation, allowing you to query and manipulate data across assets, emissions, issues, workflows, and more through a unified graph interface.

## Architecture

The SensorUp GraphQL API uses **Apollo Federation v2.3** to compose 15 specialized subgraphs into a single, unified API. This architecture enables:

* **Domain separation**: Each subgraph owns a specific business domain
* **Independent deployment**: Subgraphs can be updated independently
* **Type composition**: Entities can be extended across multiple subgraphs
* **Optimized queries**: The gateway intelligently routes and batches requests

### Subgraphs by Domain

| Domain                               | Subgraphs                                                                    | Purpose                                                                                     |
| ------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Connected Asset Management (CAM)** | su-cam-assets                                                                | Asset types, properties, and hierarchy for connected operations                             |
| **Field Service Management**         | su-assets, su-issues, su-workflow, su-forms                                  | Form subjects for mobile workflows, issue tracking, workflow orchestration                  |
| **Emissions/LDAR**                   | su-methane-ldar-backend, su-methane-reconcile-backend, su-detections-ingress | LDAR operations, reconciliation, detection ingestion                                        |
| **Core Platform**                    | su-backend, su-auth, su-user, su-maps, su-catalog, su-eventhub               | Authentication, user management, geospatial services, catalogs, events, core infrastructure |
| **Deprecated**                       | su-sites                                                                     | Site management (deprecated - use su-maps for geospatial features)                          |

## Available Environments

The GraphQL API is available in multiple environments:

| Environment    | Gateway URL                                      | Purpose                  |
| -------------- | ------------------------------------------------ | ------------------------ |
| **Demo**       | `https://customer-demo.sensorup.com/api/graphql` | Demo and POC environment |
| **Staging**    | Contact your account team                        | Pre-production testing   |
| **Production** | Contact your account team                        | Production workloads     |

<Callout type="info">
  Staging and production URLs are tenant-specific. Contact your SensorUp account team for your organization's endpoints.
</Callout>

## API Capabilities

### Queries

* Asset management and profiles
* Emission observations and LDAR workflows
* Issue tracking and templates
* Site and geospatial data
* User and authentication information
* Workflow definitions and tasks
* Dynamic forms and catalogs

### Mutations

* Create and update assets
* Manage emission events and observations
* Create and modify issues
* Update workflow states
* User authentication and session management
* Configure asset profiles and views

### Common Features

* **Relay-style pagination**: Cursor-based pagination with `edges`, `nodes`, and `PageInfo`
* **GeoJSON support**: Full GeoJSON type system for geospatial data
* **Audit trails**: Automatic tracking of creation and modification metadata
* **Error handling**: Consistent `MutationError` interface across all mutations
* **Entity references**: Cross-subgraph entity resolution via Apollo Federation

## Getting Started

1. **[Quickstart Guide](./quickstart)** - Make your first GraphQL query
2. **[Authentication](./authentication)** - Learn how to authenticate API requests
3. **[Common Patterns](./common-patterns)** - Understand pagination, filtering, and error handling
4. **[Domain Guides](./guides/cam-assets)** - Explore specific use cases by domain:
   * [Connected Asset Management](./guides/cam-assets) - Asset types, properties, and hierarchy
   * [Field Service Management](./guides/field-service) - Mobile workflows and issue tracking
   * [Emissions & LDAR](./guides/emissions) - Methane detection and compliance
   * [Core Platform](./guides/core-platform) - Authentication, maps, and infrastructure

## GraphQL Tools

You can interact with the API using:

* **Apollo Explorer** (Recommended): Built-in interactive explorer available as an application plugin
  * Demo environment: `https://customer-demo.sensorup.com/plugins/sr/apolloGraphql`
  * Authentication handled automatically when accessed within the application
  * Full schema documentation, query building, and testing capabilities
* **Apollo Studio**: View the federated schema and query planning (requires credentials)
  * Access at: [https://studio.apollographql.com/graph/su-graphql-t912yf/](https://studio.apollographql.com/graph/su-graphql-t912yf/)
* **HTTP Clients**: Any GraphQL client library (Apollo Client, urql, graphql-request, etc.)
* **curl**: Direct HTTP requests to the gateway endpoint

## Schema Reference

For detailed type definitions and technical reference:

* **[Subgraph Reference](./subgraphs/assets)** - Full schema documentation for each subgraph
* **[Raw SDL Files](./schemas/sdl/)** - GraphQL schema definition language files
* **[Federation Concepts](./federation)** - Understanding entity composition across subgraphs

## Support

Need help with the GraphQL API?

* Review the [Domain Guides](./guides/cam-assets) for common use cases
* Check the [Common Patterns](./common-patterns) for best practices
* Contact your SensorUp account team for technical support