> ## 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 Quickstart

> Get started with the SensorUp GraphQL API - make your first query and learn the basics.

# GraphQL API Quickstart

This guide will help you make your first GraphQL query to the SensorUp API and understand the basics of working with the federated graph.

## Prerequisites

Before you begin, you'll need:

* Access to a SensorUp environment (demo, staging, or production)
* Valid authentication credentials (see [Authentication](./authentication))
* A GraphQL client or HTTP tool (curl, Postman, or a programming language client)

## Your First Query

### Using curl

```bash theme={null}
curl -X POST https://customer-demo.sensorup.com/api/graphql \
  -H "Content-Type: application/json" \
  -H "x-sensorup-sessionid: YOUR_SESSION_ID" \
  -d '{
    "query": "query { session { username authenticated } }"
  }'
```

### Response

```json theme={null}
{
  "data": {
    "session": {
      "username": "your-username",
      "authenticated": true
    }
  }
}
```

## Understanding the Query Structure

GraphQL queries have three main components:

```graphql theme={null}
query {           # Operation type (query, mutation, or subscription)
  session {       # Root field - what you're querying
    username      # Selection - fields you want returned
    authenticated
  }
}
```

## Common Query Patterns

### Querying Asset Profiles

```graphql theme={null}
query GetAssetProfiles {
  assetProfiles {
    all(first: 10) {
      edges {
        node {
          profile
          title
          displayNameProperty
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

### Getting Specific Asset by ID

```graphql theme={null}
query GetAsset($profileId: ID!, $assetId: ID!) {
  assetProfiles {
    byId(profile: $profileId) {
      profile
      title
      assetById(id: $assetId) {
        id
        displayName
        properties
        geometry
      }
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "profileId": "your-profile-id",
  "assetId": "your-asset-id"
}
```

### Querying Issues

```graphql theme={null}
query GetIssues {
  issues {
    all(first: 10) {
      edges {
        node {
          id
          displayName
          status
          createdAt
          audit {
            createdBy {
              userId
            }
          }
        }
      }
    }
  }
}
```

## Making Mutations

Mutations modify data on the server. All mutations follow a consistent pattern with result types that include `correlationId` and `errors`.

### Creating an Asset Filter

```graphql theme={null}
mutation CreateAssetFilter($input: CreateAssetFilterInput!) {
  createAssetFilter(input: $input) {
    assetFilter {
      id
      displayName
      profile
    }
    correlationId
    errors {
      message
      type
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "input": {
    "id": "my-filter-id",
    "displayName": "My Asset Filter",
    "profile": "asset-profile-id",
    "subProfiles": []
  }
}
```

## Pagination

The API uses Relay-style cursor-based pagination:

```graphql theme={null}
query PaginatedAssets($first: Int!, $after: String) {
  assetProfiles {
    byId(profile: "your-profile") {
      assets(first: $first, after: $after) {
        edges {
          node {
            id
            displayName
          }
        }
        pageInfo {
          hasNextPage
          hasPreviousPage
          startCursor
          endCursor
        }
      }
    }
  }
}
```

**First page:**

```json theme={null}
{ "first": 10 }
```

**Next page:**

```json theme={null}
{ "first": 10, "after": "cursor-from-previous-page" }
```

## Error Handling

### Query Errors

GraphQL returns errors in the `errors` array:

```json theme={null}
{
  "errors": [
    {
      "message": "Cannot query field 'invalidField' on type 'Asset'",
      "locations": [{ "line": 3, "column": 5 }]
    }
  ]
}
```

### Mutation Errors

Mutations return errors in the result type:

```json theme={null}
{
  "data": {
    "createAssetFilter": {
      "assetFilter": null,
      "correlationId": "abc-123",
      "errors": [
        {
          "message": "Asset filter with this ID already exists",
          "type": "DUPLICATE_ID"
        }
      ]
    }
  }
}
```

## Using GraphQL Clients

### JavaScript/TypeScript

```javascript theme={null}
// Using graphql-request
import { request, gql } from 'graphql-request'

const query = gql`
  query {
    session {
      username
      authenticated
    }
  }
`

const data = await request(
  'https://customer-demo.sensorup.com/api/graphql',
  query,
  {},
  { 'x-sensorup-sessionid': sessionId }
)
```

### Python

```python theme={null}
# Using gql
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

transport = RequestsHTTPTransport(
    url='https://customer-demo.sensorup.com/api/graphql',
    headers={'x-sensorup-sessionid': session_id}
)

client = Client(transport=transport, fetch_schema_from_transport=True)

query = gql("""
    query {
        session {
            username
            authenticated
        }
    }
""")

result = client.execute(query)
```

## Next Steps

Now that you've made your first queries:

1. **[Authentication](./authentication)** - Learn about auth methods and credential management
2. **[Common Patterns](./common-patterns)** - Deep dive into pagination, filtering, and GeoJSON
3. **Domain Guides** - Explore specific use cases:
   * [Assets](./guides/cam-assets) - Asset management
   * [Field Service Management](./guides/field-service) - Issues, workflows, and mobile tasks
   * [Emissions](./guides/emissions) - LDAR operations
   * [Core Platform](./guides/core-platform) - Authentication, users, and platform services
4. **Subgraph Reference** - Complete schema documentation:
   * [Assets](./subgraphs/assets) - Asset profiles for field service
   * [CAM Assets](./subgraphs/cam-assets) - Connected asset management
   * [Issues](./subgraphs/issues) - Issue tracking
   * [Forms](./subgraphs/forms) - XForms data collection
   * [Auth](./subgraphs/auth) - Authentication and sessions
   * [Workflow](./subgraphs/workflow) - Workflow definitions
   * And more in the subgraphs directory

## Interactive Exploration

### Apollo Explorer (Recommended)

SensorUp includes Apollo Explorer as a built-in plugin for interactive query building and schema exploration:

**Demo Environment:**

```
https://customer-demo.sensorup.com/plugins/sr/apolloGraphql
```

**Features:**

* Interactive query builder with autocomplete
* Full schema documentation browser
* Query history and saved queries
* Authentication handled automatically (no need to manually set headers)
* Real-time query validation

**For other environments:**

* Replace `customer-demo.sensorup.com` with your environment's hostname
* The plugin path remains `/plugins/sr/apolloGraphql`

### Additional Resources

For further exploration tools, contact your SensorUp account team about:

* Apollo Studio access for advanced query planning and performance monitoring
* Postman collections with example queries