# 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](https://ivytrace.dev/api/openapi.json) and browsable at [/api/docs](https://ivytrace.dev/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](https://ivytrace.dev/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](https://ivytrace.dev/api/docs) 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.

---

Source: https://ivytrace.dev/docs/api · Updated 2026-11-14