API Reference

VeriProof exposes two primary REST APIs: the Ingest API for submitting AI governance sessions from your application, and the Customer Portal API for querying, managing, and exporting compliance data from the portal.

APIs at a glance

API	Base URL	Auth	Primary use
Ingest API	`https://veriproof-api.rjrlabs.com`	`X-API-Key`	SDK span export, session submission
Customer Portal API	`https://portal-api.rjrlabs.com`	JWT session cookie	Portal queries, exports, webhooks

Authentication

Ingest API — `X-API-Key` header

All Ingest API requests require an X-API-Key header containing the secondary segment of your compound API key.


POST /v1/ingest/otlp HTTP/1.1
Host: veriproof-api.rjrlabs.com
X-API-Key: 3xQr9pLm8N2vT4wK
Content-Type: application/json

The VeriProof SDK handles this automatically — if you configure the SDK with a full compound key, it parses and routes each segment to the correct header.

For direct REST calls (bypassing the SDK), use only the secondary segment in the X-API-Key header.

Customer Portal API — JWT session

The Customer Portal API authenticates using a JWT session token stored in the veriproof_customer_token cookie, set by the portal’s login flow. API calls made from the Customer Portal web application send this cookie automatically.

For programmatic access (CI/CD, integrations), use the portal’s token endpoint:


POST /auth/token HTTP/1.1
Host: portal-api.rjrlabs.com
Content-Type: application/json
 
{
  "email": "dev@yourcompany.com",
  "password": "..."
}

Returns a JWT token valid for 24 hours.

Compound key format


vp_cust_{customer-slug}.{azure-component}.{secondary-token}

When calling the Ingest API directly, include only the {secondary-token} segment in the X-API-Key header. The full compound key format is consumed by the SDK; individual REST integrations only need the secondary.

See API Authentication for a full explanation of the compound key model.

Environments

Environment	Ingest endpoint	Auth requires
Production	`https://veriproof-api.rjrlabs.com`	Production-scoped key
Sandbox	`https://veriproof-api.rjrlabs.com` + `X-Veriproof-Sandbox: true`	Sandbox-scoped key

Sandbox keys automatically trigger sandbox routing — the X-Veriproof-Sandbox: true header is set by the SDK automatically when a sandbox key is detected. For direct REST calls, add the header manually.

Common response codes

Code	Meaning
`200 OK`	Request processed successfully
`400 Bad Request`	Invalid request body; check the `errors` array in the response
`401 Unauthorized`	Missing or invalid `X-API-Key`; key not found or revoked
`403 Forbidden`	Authenticated but insufficient scope; sandbox write-only keys on mutation endpoints
`422 Unprocessable Entity`	Merkle root mismatch — batch hash validation failed
`429 Too Many Requests`	Rate limit exceeded; see `Retry-After` header
`503 Service Unavailable`	Customer account suspended

Rate limits

Rate limits are enforced per API key and scoped to a rolling 60-second window. Limits vary by plan:

Plan	Requests / minute	Batch size limit
Starter	60	100 spans / batch
Growth	300	500 spans / batch
Enterprise	Custom	Custom

When a rate limit is exceeded, the response includes:


HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678

The SDK handles 429 responses automatically using the Retry-After value.

Interactive API explorers

Use the interactive explorers below to browse endpoints, view request/response schemas, and try authenticated calls:

Ingest API Explorer — span submission, health check, batch endpoints
Customer Portal API Explorer — sessions, decisions, evidence exports, webhooks

Both explorers are powered by @scalar/api-reference and load the published OpenAPI 3.1 specification.

Next steps

Ingest API — interactive reference for the span submission API
Customer Portal API — interactive reference for the portal data API
API Authentication — compound key model deep-dive