API Reference

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

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

Choose An API#

Inference and ingest#

Gateway API

Send a model request through Provon.

OTLP/HTTP API

Export OpenTelemetry signals.

Read and observe#

Trace Read API

Search traces or inspect complete spans.

Telemetry Read API

Query normalized logs and metrics.

Dashboards API

Build and query project dashboards.

Attribute reference

Look up normalized evidence fields.

Diagnose and improve#

Findings API

Review Findings or schedule diagnostic Runs.

Model Pricing API

Resolve or override model token prices.

Control and tools#

Workspace API

Manage organizations, projects, and keys.

MCP API

Govern MCP tools, servers, credentials, and policies.

Playground API

Run model comparison Playgrounds.

Health endpoint

Check service health.

Base URLs#

Route group	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
`mcp:invoke`	Connect to the MCP tool gateway and call tools
`mcp:manage`	MCP management reads and writes (servers, tools, policies)
`model-pricing:read`	Resolved model price reads and match checks
`model-pricing:write`	Project model price overrides
`diagnostics:read`	Finding and Rule 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`	Playground canvas, Agent column, and Execution writes

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, and connector OAuth callbacks are documented in their user guides rather than as service APIs.

The Workspace API documents the project-qualified management 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.
Global request-body limit. Every POST/PUT/PATCH/DELETE under /v1/ is capped at 1 MiB by the platform-wide body middleware (no runtime override), except the OTLP ingest signals (/v1/traces, /v1/logs, /v1/metrics) which set their own limits. Larger bodies receive 413 PAYLOAD_TOO_LARGE. The Gateway's dedicated /gateway/v1/* origin does not sit under this /v1/ middleware and uses its own larger limits; see Gateway API.

Authentication and common adapter errors use:

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

Some domain endpoints predate the common error 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 shape.

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": "..."
}