Developer docs

Build on the Provance API.

Everything you do in the Provance web app goes through one REST API. Use it with an API key from your own code, and check the evidence it produces with provance-verify.

Quick start Ask an API question

Base URL

One host, one path per module.

Every endpoint is under https://api.provancelabs.org/v1/<module> and speaks JSON over HTTPS.

https://api.provancelabs.org/v1/<module>/...

/v1/engine: Engine projects, from a Concept Prompt to a signed delivery package
/v1/knowledge: Ontologies, scenarios and gold standards for a domain
/v1/synthetic: Synthetic generation runs and batches
/v1/qa: Quality checks, safety review and Compliance Pack checks
/v1/format: Exports in training formats, and sending them to destinations
/v1/domains: Your organisation's domains
/v1/config: Versioned configuration
/v1/platform: API keys, webhooks, LLM provider keys and other organisation settings
/v1/billing: Plans, checkout and allowances
/v1/auth: Sign-in and account management for people

Authentication

Send your API key in X-API-Key.

Owners and admins create API keys in the web app. A key starts with prov_, is shown once, and acts on behalf of the member who created it, with that member's role. Your organisation comes from the key, never from a value in the request.

curl https://api.provancelabs.org/v1/engine/projects \
  -H "X-API-Key: $PROVANCE_API_KEY"

Scopes

Knowledge, Synthetic and QA have module scopes, such as synthetic:read and qa:write.
Engine, Format, Config, Domains and platform calls need the global read or write scope, or admin.
Creating API keys, managing webhooks and adding LLM provider keys need a signed-in owner or admin, and refuse API keys.

SDKs

Python and TypeScript clients.

Both clients send your key, retry rate-limited and briefly unavailable requests with backoff, turn error responses into typed errors, and include helpers to wait for long-running work and verify webhook signatures.

The SDKs are in beta and are not yet published to PyPI or npm. This page will give the install commands when they are. Until then, call the REST API directly as shown above. Both clients read PROVANCE_API_KEY, and use https://api.provancelabs.org unless you pass a base URL or set PROVANCE_BASE_URL.

Python 3.12+

Package provance

from provance import ProvanceClient

client = ProvanceClient()  # reads PROVANCE_API_KEY
for project in client.engine.list_projects():
    print(project["id"], project["status"])

TypeScript (Node 20+)

Package @provance/sdk

import { ProvanceClient } from '@provance/sdk';

const client = new ProvanceClient(); // reads PROVANCE_API_KEY
for (const project of await client.engine.listProjects()) {
  console.log(project.id, project.status);
}

Errors and limits

Every error has the same shape.

An error response carries a stable snake_case code you can branch on, one readable sentence, and the request ID to quote to support.

{
  "error": "llm_provider_required",
  "message": "...",
  "detail": { ... },
  "request_id": "..."
}

Requests are rate limited per organisation, by plan. A limited request gets 429 with a Retry-After header in seconds. The SDKs raise a typed error for each status and for known codes, for example LlmProviderRequiredError (402) and RateLimitError (429).

400: The request is not valid for this resource
401: No credentials, or the API key or token is not valid
402: A plan, allowance or model key is needed, for example llm_provider_required or quota_exceeded
403: Your role or key scope does not allow this
404: Not found in your organisation
409: The resource's current state does not allow this action
422: The request body or parameters failed validation
429: Rate limited; wait for Retry-After seconds
503: A service the request needs is unavailable; retry, honouring Retry-After

Checking evidence

Verify evidence bundles offline.

provance-verify is open source (Apache-2.0) and checks an evidence bundle, and the export it covers, without calling Provance.

How the evidence works

Install it with Python 3.12 or later from GitHub:

pip install git+https://github.com/kobe-finance/provance-verify

provance-verify ds_evidence.zip \
  --keys provance-keys.json \
  --tsa-cert tsa.pem \
  --export ds_export.zip

Exit code 0 means verified.

Help

Questions about the API?

Email [email protected] with the request ID from the error response.