# API Reference

Provon separates model inference, telemetry ingest, and project-scoped control/read APIs. Start
here to choose the correct surface, credential capability, and domain reference.

## Choose An API

| Goal                                        | API                                            |
| ------------------------------------------- | ---------------------------------------------- |
| Send a model request through Provon         | [Gateway API](./gateway.md)                    |
| Export OpenTelemetry signals                | [OTLP/HTTP API](./otlp.md)                     |
| Search traces or inspect complete spans     | [Trace Read API](./traces.md)                  |
| Query normalized logs and metrics           | [Telemetry Read API](./telemetry.md)           |
| Review Findings or schedule diagnostic Runs | [Findings API](./findings.md)                  |
| Manage Datasets and Examples                | [Datasets API](./datasets.md)                  |
| Extract and manage project Knowledge        | [Knowledge API](./knowledge.md)                |
| Resolve or override model token prices      | [Model Pricing API](./model-pricing.md)        |
| Manage self-hosted models and runtime       | [Model Runtime API](./models.md)               |
| Train and export fine-tuned checkpoints     | [Model Fine-Tuning API](./fine-tuning.md)      |
| Build and query project dashboards          | [Dashboards API](./dashboards.md)              |
| Look up normalized evidence fields          | [Attribute reference](./tracing-attributes.md) |

## Base URLs

| Surface              | Hosted base URL                 | Local Node base URL                |
| -------------------- | ------------------------------- | ---------------------------------- |
| Control and read API | `https://api.provon.dev/v1`     | `http://127.0.0.1:3000/v1`         |
| Gateway inference    | `https://gateway.provon.dev/v1` | `http://127.0.0.1:3000/gateway/v1` |
| OTLP ingest          | `https://otel.provon.dev/v1`    | `http://127.0.0.1:3000/v1`         |

Set each origin independently. Do not derive the Gateway or OTLP origin by rewriting the API host;
self-hosted and split Cloudflare deployments can place them on different services.

## Authentication

Project API keys authenticate service clients:

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

Each key belongs to exactly one project. Public `/v1/*` routes infer the organization and project
from the key; they do not accept a caller-selected project ID.

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

See [Authentication](./authentication.md) for key capabilities, browser-session boundaries, and
self-hosted identity settings.

## Capabilities

Grant only the capabilities required by the client:

| Capability            | Used for                                                        |
| --------------------- | --------------------------------------------------------------- |
| `telemetry:ingest`    | OTLP trace, log, and metric writes                              |
| `telemetry:read`      | Trace, log, metric, conversation, and observed-user reads       |
| `gateway:invoke`      | Gateway inference                                               |
| `gateway:manage`      | Provider Key and model-binding writes                           |
| `model-pricing:read`  | Resolved model price reads and match checks                     |
| `model-pricing:write` | Project model price overrides                                   |
| `diagnostics:read`    | Finding, Rule, and diagnostic settings reads                    |
| `diagnostics:write`   | Rule updates, Runs, Finding review, and repair handoff          |
| `workspace:read`      | Project discovery, Gateway discovery, and dashboard definitions |
| `workspace:write`     | Project-level configuration writes where supported              |
| `models:manage`       | Dataset writes, fine-tuning, and Node-only model management     |

The default project key contains the common ingest and read capabilities. Mutation capabilities
must be granted explicitly.

## Public And Workbench Routes

Several domains expose paired paths:

```text
Public service client:  GET /v1/traces
Signed-in Workbench:    GET /v1/projects/:projectId/traces
```

The public form requires a project API key and derives scope from it. The project-qualified form
also verifies that the credential or session can access the requested project.

Not every mounted Workbench route is a public integration contract. Account setup, organization
membership, billing, connector OAuth callbacks, Playground state, and session-backed project
settings are intentionally documented in their user guides rather than as service APIs.
Node-only self-hosted model management is runtime-specific and is not part of the hosted API
surface.

## Request And Response Conventions

- JSON request bodies use `Content-Type: application/json`.
- Timestamps in control and read APIs are Unix milliseconds unless a page says otherwise.
- List APIs use `pagination.nextCursor`; pass cursors through unchanged.
- Unknown JSON fields should not be used as an extension mechanism.
- A successful OTLP response means asynchronous acceptance, not immediate query visibility.
- Mutation retry behavior is domain-specific.

Authentication and common adapter errors use:

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing capability: telemetry:read",
    "details": {}
  }
}
```

Some domain endpoints predate the shared envelope and return a shorter
`{ "error": "...", "message": "..." }` body. Use the HTTP status as the primary control signal and
the domain page for its exact error contract.

## First Read Request

```bash
export PROVON_API_URL="https://api.provon.dev/v1"
export PROVON_API_KEY="..."

curl "$PROVON_API_URL/traces?limit=10" \
  -H "Authorization: Bearer $PROVON_API_KEY"
```

A `401` means the credential is missing or invalid. A `403` means the key is valid but lacks the
required capability.

## Reference By Domain

- [Gateway API](./gateway.md) — inference base URLs, context headers, discovery, Provider Key
  management, endpoint families, streaming, errors, and limits.
- [Trace read API](./traces.md) — trace lists, stats, spans, overviews, attachments,
  conversations, users, and pagination.
- [Telemetry Read API](./telemetry.md) — normalized log and metric queries, ranges, filters,
  and cursor pagination.
- [OTLP/HTTP API](./otlp.md) — ingest endpoints, encodings, asynchronous acceptance, errors,
  limits, and retry behavior.
- [Findings API](./findings.md) — Findings, diagnostic settings, Rules, backfills,
  on-demand Runs, and repair handoff.
- [Datasets API](./datasets.md) — Dataset collection policies and directly owned Examples.
- [Knowledge API](./knowledge.md) — extraction settings, Learning Goals, items, and backfills.
- [Model Pricing API](./model-pricing.md) — model matching, unit prices, tiers, project
  overrides, and cost-resolution behavior.
- [Model Runtime API](./models.md) — runtime status, catalog import, engine installation,
  model downloads, service lifecycle, and trial endpoints.
- [Model Fine-Tuning API](./fine-tuning.md) — tuning jobs, checkpoints, lineage, and export
  to Hugging Face Hub.
- [Dashboards API](./dashboards.md) — project dashboards, default dashboard, and streaming
  widget queries.
- [Authentication](./authentication.md) — API keys, browser sessions, AuthJS providers, OIDC, and
  self-hosting secrets.
- [Tracing attribute reference](./tracing-attributes.md) — normalized OTel and GenAI fields used
  across ingest, read, diagnostics, and connectors.