Skip to content

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

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