Getting Started

Developer documentation: what Aether provides, how to make your first request, and how to integrate with an AI agent.

What Aether provides

Aether is a REST API that returns normalised product data from UK retailers. You send a query — a product name, a category, a price range — and Aether responds with structured JSON containing current prices, stock availability, merchant details, and purchase links from multiple retailers.

Every purchase link in the response includes affiliate tracking. When an end user clicks through and completes a purchase, the retailer pays a commission to Aether. There is no cost to you as a developer, and no cost to the end user. The API is free to use within rate limits.

The API is designed for AI agents — the response format is compact by default to minimise token usage, every field is machine-parseable, and every data point carries freshness metadata so your agent can assess reliability.

What you can do with it

Aether currently covers consumer electronics from major UK retailers. The API supports four core operations:

Search products — Find products by name, brand, category, or price range across all integrated merchants. Results include current prices, availability, and direct purchase links.

Compare prices — Given a specific product's GTIN (barcode number), retrieve every merchant's listing for that exact product, sorted by price. This is the core use case: answering "where's the cheapest place to buy this?"

Get product details — Retrieve full information for a single product, including description, identifiers, attributes, and images.

Browse categories — Discover which product categories Aether covers and how many products are in each.

Quick start

1. Get an API key

API access is currently available by request during the validation phase. Contact hello@aethergraph.io with a brief description of what you're building and we'll issue a key.

Keys follow the format aeth_live_abc123def456 for production and aeth_test_abc123def456 for testing.

2. Make your first request

All requests go to:

https://api.aethergraph.io/v1

Pass your API key in the Authorization header:

curl -H "Authorization: Bearer aeth_test_abc123def456" \
  "https://api.aethergraph.io/v1/products?q=sony+wh-1000xm5&sort=price_asc"

3. Read the response

{
  "status": "ok",
  "count": 3,
  "total": 3,
  "data": [
    {
      "id": "aeth-curry-720702",
      "name": "Sony WH-1000XM5 Wireless Headphones",
      "brand": "Sony",
      "price": {
        "amount": 249.00,
        "currency": "GBP",
        "sale_price": null,
        "sale_active": false
      },
      "availability": "in_stock",
      "condition": "new",
      "merchant": {
        "name": "Currys"
      },
      "purchase_url": "https://api.aethergraph.io/r/aeth-curry-720702",
      "images": {
        "primary": "https://media.currys.co.uk/i/curyspcworld/..."
      },
      "category": {
        "aether": ["electronics", "headphones"]
      }
    }
  ],
  "meta": {
    "query_time_ms": 38,
    "next_cursor": null,
    "has_more": false,
    "freshness_oldest": "2026-03-05T06:00:00Z",
    "freshness_newest": "2026-03-06T08:30:00Z"
  }
}

The data array contains the matching products. Each includes a purchase_url that redirects the user to the retailer's product page with affiliate tracking applied automatically.

The meta object tells you how fresh the data is. freshness_oldest and freshness_newest give the range of when the returned products were last verified against their source feeds.

4. Compare prices for a specific product

If the search response includes a GTIN in the product identifiers (request this with ?fields=identifiers), you can compare that product across all merchants:

curl -H "Authorization: Bearer aeth_test_abc123def456" \
  "https://api.aethergraph.io/v1/compare/4548736132108"

This returns every merchant's listing for that exact product, sorted cheapest first.

Typical integration flow

If you're building an AI agent that helps users find products:

1. User asks a question — "Find me the best deal on noise-cancelling headphones under £300"
2. Your agent calls the search endpoint — GET /v1/products?q=noise+cancelling+headphones&max_price=300&sort=price_asc
3. Your agent reads the response — Structured JSON with prices, availability, and merchants
4. Your agent presents options — Clear prices from real retailers, ranked by the user's criteria
5. User clicks a purchase link — Redirected to the retailer's product page. Affiliate tracking is handled by Aether.

For more precise comparisons, your agent can extract the GTIN from a search result and call the compare endpoint to see every merchant's price for that exact product.

Response format

Every response follows the same envelope structure:

{
  "status": "ok",
  "count": 10,
  "total": 247,
  "data": [...],
  "meta": { ... }
}

status is always "ok" or "error". If "error", the response includes an error object with a machine-readable code and a human-readable message. See the API Reference for the full list of error codes.

Responses are compact by default — only the most commonly needed fields are included. Request additional fields using the fields query parameter. See Field selection for details.

Next steps

• API Reference — Full endpoint documentation with parameters, examples, and error codes
• Authentication — API key management, rate limits, and security
• MCP Integration — Connect Aether to AI agents via the Model Context Protocol