API Reference

Technical documentation for integrating with Aether’s APIs.

Overview

Aether provides multiple API endpoints for integration:

• GraphQL API - Primary API for all data operations
• REST API - For webhook receivers and simple integrations
• Webhooks - Receive notifications for events

Authentication

All API requests require authentication via JWT tokens.

Authentication Flow

1. User authenticates (magic link, OAuth, SSO)
2. Server returns JWT access token
3. Client includes token in Authorization header
4. Client specifies Workspace in X-Aether-Workspace header
5. Server validates and processes request

Headers

Token Management

• Access Token TTL: Configurable (default: 1 hour)
• Refresh Token TTL: Configurable (default: 7 days)
• Token Type: JWT with claims for account ID, email, etc.
• Revocation: Tokens can be revoked (logout)

Rate Limits

Aether implements comprehensive rate limiting to protect the platform.

Scope Hierarchy

Rate limits are applied at multiple scopes. The strictest match wins:

Request
  ↓
Per-Session (access token) → Smallest
  ↓
Per-Account (your identity) → Primary authenticated cap
  ↓
Per-Workspace (tenant-scoped) → Automation cap
  ↓
Per-IP (source address) → Backstop (MUST be ≥ Per-Workspace)
  ↓
Per-Endpoint Class → Feature-specific limits

Why this hierarchy?

• Prevents a single leaked token from overwhelming the system (Per-Session)
• Prevents multiplying quota across multiple Free Workspaces (Per-Account below Per-Workspace)
• Ensures single-IP users never trip IP before Workspace (Per-IP above Per-Workspace)

Default Per-Plan Ceilings

Per-Account (Authenticated)

Per-Workspace (Authenticated, Secondary)

Per-IP (Authed + Anonymous Backstop)

Per-Session (Safety Net)

Mutation Window (Separate Bucket)

Endpoint Class Limits

Specific high-cost endpoints have their own quotas:

Rate Limit Headers

Every API response includes:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1736500800
X-RateLimit-Scope: account

Error Responses

429 Too Many Requests

{
  "errors": [{
    "message": "Rate limit exceeded for scope 'account'. Try again in 12 seconds.",
    "extensions": {
      "code": "rate_limited",
      "scope": "account",
      "scopeId": "acc_...",
      "retryAfterSeconds": 12,
      "resetAt": "2026-07-07T13:50:00Z",
      "limit": 100,
      "window": "minute"
    }
  }]
}

423 Locked (Workspace Suspended)

{
  "errors": [{
    "message": "Workspace is suspended. Contact the Workspace Owner or Aether support.",
    "extensions": {
      "code": "workspace_suspended",
      "workspaceStatus": "Suspended"
    }
  }]
}

Bypass Lanes

Some traffic is NOT subject to user-scope limits:

GraphQL API

Aether’s primary API is GraphQL-based, providing flexible querying for all data.

Schema Overview

The GraphQL schema includes:

# Root types
type Query {
  # Product Development
  ingredient(id: ID!): Ingredient
  ingredients(filter: IngredientFilter, pagination: Pagination): IngredientConnection
  vessel(id: ID!): Vessel
  vessels(filter: VesselFilter, pagination: Pagination): VesselConnection
  mixture(id: ID!): Mixture
  mixtures(filter: MixtureFilter, pagination: Pagination): MixtureConnection
  productTemplate(id: ID!): ProductTemplate
  productTemplates(filter: ProductTemplateFilter, pagination: Pagination): ProductTemplateConnection
  product(id: ID!): Product
  products(filter: ProductFilter, pagination: Pagination): ProductConnection
  
  # Inventory
  stockItem(id: ID!): StockItem
  stockItems(filter: StockItemFilter, pagination: Pagination): StockItemConnection
  supplier(id: ID!): Supplier
  suppliers(filter: SupplierFilter, pagination: Pagination): SupplierConnection
  
  # Compliance
  sds(id: ID!): SafetyDataSheet
  allergenSheet(id: ID!): AllergenSheet
  
  # Ecommerce
  shopifyProduct(id: ID!): ShopifyProduct
  orders(filter: OrderFilter, pagination: Pagination): OrderConnection
  
  # Platform
  workspace(id: ID!): Workspace
  account: Account
  seats: [Seat!]!
}

type Mutation {
  # Product Development
  createIngredient(input: CreateIngredientInput!): Ingredient!
  updateIngredient(id: ID!, input: UpdateIngredientInput!): Ingredient!
  deleteIngredient(id: ID!): Boolean!
  
  createVessel(input: CreateVesselInput!): Vessel!
  updateVessel(id: ID!, input: UpdateVesselInput!): Vessel!
  deleteVessel(id: ID!): Boolean!
  
  createMixture(input: CreateMixtureInput!): Mixture!
  updateMixture(id: ID!, input: UpdateMixtureInput!): Mixture!
  deleteMixture(id: ID!): Boolean!
  
  createProductTemplate(input: CreateProductTemplateInput!): ProductTemplate!
  updateProductTemplate(id: ID!, input: UpdateProductTemplateInput!): ProductTemplate!
  deleteProductTemplate(id: ID!): Boolean!
  
  createProduct(input: CreateProductInput!): Product!
  updateProduct(id: ID!, input: UpdateProductInput!): Product!
  deleteProduct(id: ID!): Boolean!
  
  # Inventory
  createStockItem(input: CreateStockItemInput!): StockItem!
  updateStockItem(id: ID!, input: UpdateStockItemInput!): StockItem!
  adjustStock(id: ID!, quantity: Float!, reason: String): StockItem!
  
  # Compliance
  generateSDS(productId: ID!): SafetyDataSheet!
  generateAllergenSheet(productId: ID!): AllergenSheet!
  generateIngredientList(productId: ID!, targetMarket: Market!): IngredientList!
  
  # Ecommerce
  syncToShopify(productId: ID!): ShopifySyncResult!
  importOrders(channel: Channel!, since: DateTime): ImportResult!
}

type Subscription {
  # Real-time updates
  ingredientUpdated: Ingredient!
  stockLevelChanged: StockItem!
  orderCreated: Order!
}

Query Complexity Limits

To prevent expensive queries, Aether implements a 5-layer defense:

Layer 1: Static Query Cost Ceiling (Parse Time)

Every field has a cost. Queries over the limit are rejected before execution.

Cost Factors:

Layer 2: Depth Limit (Parse Time)

Layer 3: Aliasing & Batch Defense (Parse Time)

Aliased repetitions count as lists. Max batch operations:

Layer 4: Cost-Based Token Bucket (Execution Time)

Cumulative cost per time window:

Layer 5: Result-Size Cap (Post-Execution)

Responses exceeding the cap are truncated with a warning.

Mutation Cost Overrides

Some mutations have higher costs:

GraphQL Endpoint

POST https://api.aether.com/graphql

Example Query

query GetProduct($id: ID!) {
  product(id: $id) {
    id
    name
    description
    vessel {
      id
      name
      volume
    }
    components {
      ingredient {
        id
        name
        inciName
      }
      percentage
    }
    cogs {
      total
      breakdown {
        item
        cost
      }
    }
  }
}

Example Mutation

mutation CreateIngredient($input: CreateIngredientInput!) {
  createIngredient(input: $input) {
    id
    name
    inciName
    casNumber
    density
    cost
  }
}

REST API

For simpler integrations and webhook receivers.

Endpoints

Stripe Webhook

Receive Stripe events for subscription management.

Endpoint: POST /webhooks/stripe

Headers:

Stripe-Signature: <signature>
Content-Type: application/json

Supported Events:

• invoice.payment_succeeded
• invoice.payment_failed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• checkout.session.completed

Shopify Webhook

Receive Shopify events for order and product updates.

Endpoint: POST /webhooks/shopify

Headers:

X-Shopify-Hmac-Sha256: <signature>
X-Shopify-Shop-Domain: <shop>.myshopify.com
Content-Type: application/json

Supported Topics:

• orders/create
• orders/updated
• orders/paid
• orders/fulfilled
• products/create
• products/update
• products/delete
• inventory_levels/update

Webhooks

Aether can send webhooks to your endpoints for various events.

Configuration

Configure webhooks in your Workspace settings:

• URL - Your endpoint URL
• Secret - Secret key for HMAC verification
• Events - Which events to subscribe to
• Active - Enable/disable the webhook

Outbound Webhooks

Aether sends webhooks for:

Webhook Format

{
  "event": "product.created",
  "timestamp": "2026-07-09T10:00:00Z",
  "workspaceId": "ws_...",
  "data": {
    "id": "prod_...",
    "name": "Lavender Body Spray",
    "...": "..."
  },
  "signature": "sha256=..."
}

Verification

Verify webhook signatures:

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  
  const received = signature.split('=')[1];
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

SDKs

JavaScript/TypeScript SDK

Coming soon - Official SDK for browser and Node.js.

Rust SDK

Coming soon - Official SDK for Rust backend integrations.

OpenAPI Spec

The complete API specification is available for generating client libraries:

# Swagger/OpenAPI 3.0
openapi: 3.0.0
info:
  title: Aether API
  version: 1.0.0
servers:
  - url: https://api.aether.com
    description: Production
  - url: https://staging-api.aether.com
    description: Staging

Best Practices

Rate Limiting

• Honor Retry-After - Always wait the specified time before retrying
• Exponential Backoff - Use exponential backoff with jitter for retries
• Idempotency Keys - Always include for mutations to prevent double-execution
• Monitor Headers - Track X-RateLimit-Remaining and back off proactively when < 20%
• Batch Requests - Combine multiple operations into one request when possible

Authentication

• Store Tokens Securely - Never commit tokens to version control
• Refresh Proactively - Refresh tokens before they expire
• Handle 401s - Automatically refresh and retry on token expiration
• Per-Request Workspace - Specify the Workspace header for each request

Error Handling

• 429 Retry - Retry after Retry-After or exponential backoff
• 403 Check - Verify permissions and plan limits
• 423 Handle - Workspace is suspended, limited functionality available
• 400 Validate - Check query/mutation syntax

Testing

• Sandbox Environment - Use staging for development
• Test Tokens - Use test accounts and workspaces
• Mock Data - Test with realistic data volumes
• Rate Limit Testing - Verify your handling of rate limits

Support

API Support

• Entrepreneur Plan - Email support for API questions
• Enterprise Plan - Priority support with SLA
• Custom Plans - Dedicated API support available

Status Page

Check API status at: https://status.aether.com

Changelog

API changes are documented in the API Changelog.

Next Steps

• Review Platform Concepts for understanding workspaces
• Explore Product Development for creating products
• View Rate Limits in Detail for integration planning