HTTP API
Everything in Ivy's dashboard goes through its HTTP API, which you and your agents can use directly. It is described by an OpenAPI 3.1 document at /api/openapi.json and browsable at /api/docs.
Authentication
Send an OIDC access token as Authorization: Bearer <token>. On ivytrace.dev:
- Coding agents get a token through the OAuth device flow described in llms.txt (section 1). Tokens last an hour and refresh for up to 30 days.
- Scripts can use the same flow, or the authorization code flow with PKCE on a local port.
Ingest keys (IVY_API_KEY) are separate: they only send spans and can't read data.
Routes
Data routes are scoped to a workspace and project:
P=https://ivytrace.dev/api/w/<workspace>/p/<project>| Route | What |
|---|---|
GET /api/workspaces |
Your workspaces |
GET /api/w/<workspace>/projects |
Projects in a workspace |
GET $P/functions?since=24h |
Per-function counts, error rates and latency percentiles |
GET $P/invocations?function=<name>&status=error&since=1h |
Invocations, filtered |
GET $P/errors?since=24h |
Error groups (/api/w/<workspace>/errors covers every project) |
GET $P/traces/<trace_id> |
One trace as JSON |
GET $P/traces/<trace_id>?format=text |
One trace as a compact text tree |
POST $P/keys |
Create an ingest key for the project |
GET /api/w/<workspace>/aws/accounts |
Connected AWS accounts, with POST, verify and function listing under it |
POST /api/w/<workspace>/aws/rules/dry-run |
Preview an auto-trace rule |
The API reference has every route, parameter and response shape.
Traces as text
?format=text returns a trace in a form that is cheap for language models to read:
checkout-createOrder · API Gateway POST /orders → 500 · cold start · 212ms · ERROR
trace 6af84d409a1b… · request 8f1c2d3e-… · eu-west-1 · 96 MB used · 4 spans
+0.0ms 212ms checkout-createOrder [invocation] API Gateway POST /orders → 500 ERROR
! TypeError: Cannot read properties of undefined (reading 'id')
at createPaymentIntent (/var/task/src/payments.js:42:31)
req: {"routeKey":"POST /orders","headers":{"authorization":"[redacted]",…}
+2.0ms log info: Creating order for cart cart_u_8812
+4.0ms 11.6ms DynamoDB.GetItem checkout-users (1 item returned) ok
+36.0ms 135ms POST api.stripe.com/v1/payment_intents → 402 ok
res: {"error":{"code":"card_declined",…}}Add detail=summary for less, or detail=full for every payload and message.
Self-hosted
The same API runs at http://localhost:3000/api on a self-hosted install. Without OIDC configured it needs no token.