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)
A GraphQL client or HTTP tool (curl, Postman, or a programming language client)

Your First Query

Using curl

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

{
  "data": {
    "session": {
      "username": "your-username",
      "authenticated": true
    }
  }
}

Understanding the Query Structure

GraphQL queries have three main components:

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

query GetAssetProfiles {
  assetProfiles {
    all(first: 10) {
      edges {
        node {
          profile
          title
          displayNameProperty
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Getting Specific Asset by ID

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

Variables:

{
  "profileId": "your-profile-id",
  "assetId": "your-asset-id"
}

Querying Issues

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

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

Variables:

{
  "input": {
    "id": "my-filter-id",
    "displayName": "My Asset Filter",
    "profile": "asset-profile-id",
    "subProfiles": []
  }
}

Pagination

The API uses Relay-style cursor-based pagination:

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:

{ "first": 10 }

Next page:

{ "first": 10, "after": "cursor-from-previous-page" }

Error Handling

Query Errors

GraphQL returns errors in the errors array:

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

Mutation Errors

Mutations return errors in the result type:

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

Using GraphQL Clients

JavaScript/TypeScript

// 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

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

Authentication - Learn about auth methods and credential management
Common Patterns - Deep dive into pagination, filtering, and GeoJSON
Domain Guides - Explore specific use cases:
- Assets - Asset management
- Field Service Management - Issues, workflows, and mobile tasks
- Emissions - LDAR operations
- Core Platform - Authentication, users, and platform services
Subgraph Reference - Complete schema documentation:
- Assets - Asset profiles for field service
- CAM Assets - Connected asset management
- Issues - Issue tracking
- Forms - XForms data collection
- Auth - Authentication and sessions
- 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

​GraphQL API Quickstart

​Prerequisites

​Your First Query

​Using curl

​Response

​Understanding the Query Structure

​Common Query Patterns

​Querying Asset Profiles

​Getting Specific Asset by ID

​Querying Issues

​Making Mutations

​Creating an Asset Filter

​Pagination

​Error Handling

​Query Errors

​Mutation Errors

​Using GraphQL Clients

​JavaScript/TypeScript

​Python

​Next Steps

​Interactive Exploration

​Apollo Explorer (Recommended)

​Additional Resources