developers

One endpoint. Every model.

Point your code at one REST API and stop writing a client per provider. The reference is generated from the running service, so it always describes exactly what is deployed.

API reference OpenAPI document

authentication

One key is all
you carry.

Every call uses a project API key, sent as a bearer token. A key belongs to one project, so requests never need to name it. Create separate live and test keys and your staging environment can never spend your production budget.

Base URL: https://app.aethergridlabs.com/v1
Authorization: Bearer ag_live_… · or the X-API-Key header
Environments: live and test, issued separately, so staging cannot spend production budget.

POST /v1/chat/completions

curl https://app.aethergridlabs.com/v1/chat/completions \
  -H "Authorization: Bearer $AETHERGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Summarise this incident."}],
    "strategy": "cost",
    "max_tokens": 512
  }'

response200 · application/jsonIllustrative data

{
  "request_id": "req_01j9r2m8k4x7v3p6q1w5e8t2y0",
  "content": "Two services lost quorum at 09:41 after…",
  "finish_reason": "stop",

  "model": "llama-3.3-70b-instruct",
  "provider": "self-hosted",
  "routing_strategy": "cost",
  "routing_reason": "cheapest eligible candidate at $0.12/M input",
  "did_fallback": false,
  "attempt_count": 1,

  "usage": {
    "input_tokens": 1840,
    "output_tokens": 212,
    "is_estimated": false
  },
  "latency_ms": 318.4,
  "cost_usd": 0.000284,
  "cost_is_estimated": true,
  "customer_cost_usd": 0.000341
}

Every field above comes back on every call. cost_usd is the provider's price; customer_cost_usd is what you pay, with the service markup added. An unknown cost is null, never zero.

project / keys4 activeIllustrative data

name	key	scopes	last_used	state
support-agent	ag_live_••••••••3f9c	inference:runrequests:read	2s ago	active
search-rerank	ag_live_••••••••a71e	inference:run	4s ago	active
triage	ag_live_••••••••c204	inference:runrouting:read	9s ago	active
eval-runner	ag_test_••••••••8d1b	inference:runevaluations:write	1m ago	active
ci-smoke	ag_test_••••••••5e77	inference:run	revoked 3d ago	revoked

Every action is checked twice: against the key's permissions and against the role of the person who owns it (viewer, member, admin or owner). Both must allow it. A lost key is revoked and reissued; it cannot be recovered, because it was never stored.

Every action is checked against both the key's permissions and the role of the person who created it. Keys are stored hashed and shown once, when created. If you lose one, revoke it and create another.

api surface

What you
can call.

Grouped by what they do. The reference has the full request and response format for each, generated from the running service.

GET /openapi.json always matches what is deployed. Two health probes, /health and /ready, need no key.

/v111 groups

Chat and routing

/v1/chat/completions · /v1/chat/stream · /v1/chat/route-preview

Get a completion, stream one, or ask which model would be chosen without calling a provider.

Models and providers

/v1/models · /v1/models/{slug} · /v1/providers · /v1/providers/health

The models you can reach, and which providers are connected and healthy right now.

Agents

/v1/agents · /v1/agents/{id}/runs · /v1/agents/{id}/tools

Define agents that use tools, attach the tools, start runs and read the results.

Workflows

/v1/workflows · /v1/workflows/validate · /v1/workflows/{id}/runs

Build workflows with several steps, check them before saving, run them and inspect the runs.

Knowledge

/v1/knowledge · /v1/knowledge/{id}/documents · /v1/knowledge/{id}/query

Create knowledge bases, ingest documents and run similarity queries.

Evaluations

/v1/evaluations · /v1/evaluations/{id}/cases · /v1/evaluations/{id}/runs

Test sets with versions, five ways to score answers, and runs you can compare against a baseline.

Observability

/v1/observability/requests · /series · /latency

Every request through the gateway, retrievable by id, plus time series and latency distributions.

Usage and cost

/v1/usage · /v1/usage/budget

Spend by model, provider or day, and the monthly budget with its enforcement state.

Conversations

/v1/conversations · /v1/conversations/{id}/messages

Saved conversation threads, if you would rather not keep the history yourself.

Organisation and keys

/v1/organization · /v1/project · /v1/keys

Plan and limits, project settings and budget, and API key issue and revocation.

Health

/health · /ready

The two health checks that need no key.

Streaming

POST /v1/chat/stream returns tokens as they arrive. Routing, fallback and cost work exactly as they do for a normal request, and a streamed request is recorded and priced like any other.

Cost on every call

Cost comes from the provider whenever it reports one, and is estimated from list prices otherwise; cost_is_estimated says which. A cost that could not be determined is null never zero, because zero would read as free.

Long running calls

Agent, workflow and evaluation runs happen while your request is open. Give those calls a generous timeout: a run over a large test set can take minutes, and a client that gives up early does not stop the run.

Create a free account Models and routing