API Reference

The core of ae.app is the unified proxy endpoint. It allows you to call any supported provider using their native request format, just by pointing to our base URL.

The Proxy Endpoint

GEThttps://api.ae.app/v1/call/:provider/:api/*

POSThttps://api.ae.app/v1/call/:provider/:api/*

Path Parameters

:provider — The provider slug (e.g. open-meteo, coingecko, hackernews)
:api — The specific API within that provider (e.g. forecast, prices, stories)
* — The remaining path forwarded to the upstream API (e.g. v1/forecast, simple/price)

Query Parameters

All query parameters are passed through to the upstream provider. ae.app does not consume or modify any query parameters. This means you can use provider-specific query params as documented in their APIs.

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token with your ae.app API key
Content-Type	Yes (POST)	Usually `application/json`

Any additional headers you include are forwarded to the upstream provider as-is. ae.app only consumes the Authorization header for authentication — everything else passes through.

Examples

Weather Forecast (Open-Meteo)

curl "https://api.ae.app/v1/call/open-meteo/forecast/v1/forecast?latitude=40.71&longitude=-74.00&current=temperature_2m,wind_speed_10m" \
  -H "Authorization: Bearer YOUR_AE_API_KEY"

Crypto Prices (CoinGecko)

curl "https://api.ae.app/v1/call/coingecko/prices/simple/price?ids=bitcoin,ethereum&vs_currencies=usd" \
  -H "Authorization: Bearer YOUR_AE_API_KEY"

Hacker News Top Stories

curl "https://api.ae.app/v1/call/hackernews/stories/topstories.json" \
  -H "Authorization: Bearer YOUR_AE_API_KEY"

Response Headers

Every proxy response includes custom X-AE-* headers to help you track usage and debug issues:

Header	Description
X-AE-Request-Id	Unique identifier for the proxy request (use for support tickets)
X-AE-Calls-Remaining	Remaining API calls for the current billing cycle
X-AE-Calls-Limit	Total API call limit for your current plan
X-AE-Plan	Your current plan tier (free, pro, max, or enterprise)
X-AE-Latency-Ms	Upstream request latency in milliseconds

Status Codes

200 OK: Request succeeded — response body from the upstream provider
400 Bad Request: Malformed request or invalid provider path
401 Unauthorized: Invalid or missing API key
402 Payment Required: Monthly quota exceeded — upgrade your plan or wait for reset
429 Too Many Requests: Rate limit exceeded — retry after the specified delay
502 Bad Gateway: Error communicating with the upstream provider

Rate Limiting (429)

When you exceed your plan's rate limit, the proxy returns a 429 status with a Retry-After header indicating how many seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 2 seconds."
  }
}

Quota Exceeded (402)

When your monthly call limit is reached, the proxy returns 402 Payment Required. You can upgrade your plan or wait for the monthly reset on the 1st.

HTTP/1.1 402 Payment Required
X-AE-Calls-Remaining: 0
Content-Type: application/json

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly call limit reached. Upgrade your plan at https://ae.app/settings/billing"
  }
}