API Overview

The Stations API is a GraphQL API that provides full access to all platform features. This guide covers the basics of connecting to and using the API.

Endpoint

All API requests are made to your Stations GraphQL endpoint:

https://api.stations.build/graphql

Authentication

Stations uses AWS Cognito for authentication. Include your JWT token in the Authorization header:

POST /graphql HTTP/1.1
Host: api.stations.build
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Obtaining a Token

After signing in through the Stations authentication flow, you’ll receive a JWT token. Store this securely and include it with all API requests.

const headers = {
  'Authorization': `Bearer ${jwtToken}`,
  'Content-Type': 'application/json'
};

GraphQL Operations

The API supports three types of operations:

Operation	Description
Query	Read data (stations, routes, users, etc.)
Mutation	Create, update, or delete data
Subscription	Real-time updates via WebSocket

Making Requests

JavaScript

const response = await fetch('https://api.stations.build/graphql', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: `
      query {
        listStations {
          id
          name
        }
      }
    `
  })
});

const { data } = await response.json();
console.log(data.listStations);

cURL

curl -X POST https://api.stations.build/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { listStations { id name } }"
  }'

Python

import requests

url = "https://api.stations.build/graphql"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}
query = """
    query {
        listStations {
            id
            name
        }
    }
"""

response = requests.post(url, json={"query": query}, headers=headers)
data = response.json()
print(data["data"]["listStations"])

Response Format

All responses follow the standard GraphQL response format:

Success Response

{
  "data": {
    "listStations": [
      {
        "id": "station-123",
        "name": "Review Document"
      }
    ]
  }
}

Error Response

{
  "data": null,
  "errors": [
    {
      "message": "Not authorized",
      "path": ["listStations"],
      "errorType": "Unauthorized"
    }
  ]
}

Role-Based Access

Different operations require different permission levels:

Role	Access Level
Owner	Full access including billing and account deletion
Admin	Manage stations, routes, templates, and users
User	View data and mark stops as completed
Free	Limited access based on free tier

Operations specify their required roles:

# Requires Owner, Admin, or Free role
addStation(input: AddStationInput): Station
  @aws_cognito_user_pools(cognito_groups: ["Free", "Owner", "Admin"])

# Requires Owner or Admin role only
addAdminUser(username: AWSEmail!): User
  @aws_cognito_user_pools(cognito_groups: ["Owner", "Admin"])

Subscriptions (Real-time)

For real-time updates, use GraphQL subscriptions over WebSocket:

import { createClient } from 'graphql-ws';

const client = createClient({
  url: 'wss://api.stations.build/graphql',
  connectionParams: {
    Authorization: `Bearer ${token}`,
  },
});

client.subscribe(
  {
    query: `
      subscription {
        routeUpdated(tenantId: "your-tenant-id") {
          id
          status
        }
      }
    `,
  },
  {
    next: (data) => console.log('Route updated:', data),
    error: (err) => console.error('Error:', err),
    complete: () => console.log('Subscription complete'),
  }
);

Pagination

For queries that return lists, use the limit parameter where available:

query {
  listCharges(limit: 10) {
    id
    amount
    created
  }
}

Error Handling

Always handle potential errors in your code:

try {
  const { data, errors } = await graphqlClient.request(query);

  if (errors) {
    errors.forEach(error => {
      console.error(`GraphQL Error: ${error.message}`);
      // Handle specific error types
      if (error.errorType === 'Unauthorized') {
        // Redirect to login
      }
    });
  }

  return data;
} catch (networkError) {
  console.error('Network error:', networkError);
}

Rate Limiting

The API implements rate limiting to ensure fair usage. If you exceed the limits, you’ll receive a 429 Too Many Requests response. Implement exponential backoff in your retry logic.

API Sections

Explore the full API documentation:

• Queries - Read operations for all resources
• Mutations - Create, update, and delete operations
• Subscriptions - Real-time update streams
• Types - All GraphQL types and inputs