# API Reference

Provon exposes separate HTTP surfaces instead of one monolithic API page. Use this page as the
entry point for the current public contracts.

| Surface              | Base URL                        | Reference                                                                                                  |
| -------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Control and read API | `https://api.provon.dev/v1`     | [Gateway API](./gateway-api.md), [Trace read API](./trace-api.md), [Diagnostics API](./diagnostics-api.md) |
| Gateway inference    | `https://gateway.provon.dev/v1` | [Gateway API](./gateway-api.md)                                                                            |
| OTLP ingest          | `https://otel.provon.dev/v1`    | [OTLP/HTTP API](./otlp-api.md)                                                                             |

Project API keys authenticate automation and service clients:

```http
Authorization: Bearer <PROVON_API_KEY>
```

Capabilities are checked per surface:

| Capability          | Used for                                                         |
| ------------------- | ---------------------------------------------------------------- |
| `telemetry:ingest`  | OTLP writes                                                      |
| `telemetry:read`    | Trace, log, metric, conversation, and user reads                 |
| `gateway:invoke`    | Gateway inference                                                |
| `workspace:read`    | Gateway discovery and Provider Key reads                         |
| `gateway:manage`    | Provider Key and model-binding writes                            |
| `diagnostics:read`  | Finding, Rule, and settings reads                                |
| `diagnostics:write` | Rule updates, Run scheduling, Finding review, and repair handoff |

Signed-in Workbench sessions can call project-qualified application routes according to project
permissions. Public service clients should prefer project API keys.

## Reference Pages

- [Gateway API](./gateway-api.md) — inference base URLs, context headers, discovery, Provider Key
  management, endpoint families, streaming, errors, and limits.
- [Trace read API](./trace-api.md) — trace lists, stats, spans, overviews, attachments,
  conversations, users, and pagination.
- [OTLP/HTTP API](./otlp-api.md) — ingest endpoints, encodings, asynchronous acceptance, errors,
  limits, and retry behavior.
- [Diagnostics API](./diagnostics-api.md) — Findings, diagnostic settings, Rules, backfills,
  on-demand Runs, and repair handoff.
- [Authentication](./authentication.md) — API keys, browser sessions, AuthJS providers, OIDC, SAML,
  and self-hosting secrets.