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.

View as Markdown Open the plain-text version of this page.

Choose An API#

Goal	API
Send a model request through Provon	Gateway API
Export OpenTelemetry signals	OTLP/HTTP API
Search traces or inspect complete spans	Trace Read API
Query normalized logs and metrics	Telemetry Read API
Review Findings or schedule diagnostic Runs	Findings API
Manage Datasets and Examples	Datasets API
Extract and manage project Knowledge	Knowledge API
Resolve or override model token prices	Model Pricing API
Manage self-hosted models and runtime	Model Runtime API
Train and export fine-tuned checkpoints	Model Fine-Tuning API
Build and query project dashboards	Dashboards API
Manage organizations, projects, and keys	Workspace API
Run model comparison Playgrounds	Playground API
Check service health	Health endpoint
Look up normalized evidence fields	Attribute reference

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:

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 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:

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, and connector OAuth callbacks 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.

The Workspace API documents the project-qualified control-plane routes that are stable for both browser sessions and API-key callers where noted. The Playground API documents the project-scoped comparison canvas routes.

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:

{
  "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#

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.

Health Check#

All deployments expose a health endpoint:

GET /healthz

Response:

{
  "status": "ok",
  "version": "...",
  "deploymentTarget": "...",
  "accessContext": "..."
}