Skip to content
Aether Documentation
API Reference
API Changelog

API Changelog

All notable changes to the Aether API are documented in this file.

Versioning

Aether uses date-based versioning for the API. Breaking changes are announced at least 30 days in advance.

Unreleased

Added

  • Initial API documentation structure
  • GraphQL schema overview
  • Rate limiting documentation
  • Authentication documentation

2026-07-09

Added

  • GraphQL API - Primary API for all data operations

    • Full CRUD for Product Development entities (Ingredients, Vessels, Mixtures, Templates, Products)
    • Full CRUD for Inventory entities (StockItems, Suppliers)
    • Compliance document generation (SDS, Allergen Sheets, Ingredient Lists)
    • Shopify sync operations
    • Order import operations

  • REST API - Webhook receivers

    • Stripe webhook endpoint
    • Shopify webhook endpoint
    • Health check endpoints

  • Rate Limiting - Comprehensive rate limit implementation

    • Per-Session, Per-Account, Per-Workspace, Per-IP scopes
    • Mutation-specific limits
    • Endpoint class limits
    • GraphQL query complexity limits

  • Authentication - JWT-based authentication

    • Magic link support
    • OAuth support (Google, etc.)
    • SSO support (SAML/OIDC) for Enterprise
    • Workspace binding via X-Aether-Workspace header

2026-06-XX (Planned)

Planned Additions

  • Subscriptions - Real-time updates via GraphQL subscriptions
  • Batch Operations - Bulk operations for large datasets
  • Export APIs - Enhanced data export capabilities
  • Square Integration - Square ecommerce integration
  • Etsy Integration - Etsy marketplace integration

Migration Guide

From v1.0 to v1.1

No breaking changes. All existing queries and mutations continue to work.

From Beta to v1.0

The following changes were made for the v1.0 release:

  • Authentication: Migrated from session-based to JWT-based authentication
  • Workspace Binding: Added X-Aether-Workspace header (previously inferred from session)
  • Rate Limiting: Added comprehensive rate limiting (previously unlimited)
  • Pagination: Standardized pagination arguments across all list queries

Breaking Changes

  1. Authentication Header

    • Old: Session cookie
    • New: Authorization: Bearer <token>

  2. Workspace Selection

    • Old: Session-scoped workspace
    • New: X-Aether-Workspace: ws_<uuid> header

  3. Pagination

    • Old: Inconsistent arguments
    • New: Standard first, after, last, before arguments

Migration Steps

  1. Update your authentication to use JWT tokens
  2. Add X-Aether-Workspace header to all requests
  3. Update pagination arguments in list queries

Deprecations

Deprecated Fields

The following fields are deprecated and will be removed in a future version:

Field Type Replacement Removal Date
Ingredient.legacyId String Ingredient.id 2026-12-01
Product.oldSku String Product.sku 2026-12-01

Deprecated Queries/Mutations

The following operations are deprecated:

Operation Replacement Removal Date
createIngredientLegacy createIngredient 2026-12-01
oldProductList products 2026-12-01

Support Policy

Version Support

  • Current Version: Full support
  • Previous Version: Limited support (security fixes only)
  • Older Versions: No support

Breaking Changes

  • Notice Period: 30 days minimum for breaking changes
  • Announcement: Via email, dashboard notification, and this changelog
  • Migration Guides: Provided for all breaking changes

End of Life

  • Announcement: 90 days before EOL
  • Migration Period: 90 days after EOL announcement
  • Shutdown: API calls to EOL versions will fail with 410 Gone

Feedback

Have questions or feedback about the API?

Previous Versions

Beta (2026-01-XX to 2026-06-XX)

Initial beta version with limited functionality and no rate limiting.