API Reference (v1.0)

Authentication

Sandbox and production will use Bearer tokens. OAuth 2.0 client credentials will follow for partner and multi-tenant apps. Send your key on every request. Never embed keys in client-side code or public repositories.

Authorization: Bearer YOUR_API_KEY

Example request:

curl https://api.proventen.com/v1/system/status \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.proventen.com/v1/system/status', {
  headers: {
    Authorization: `Bearer ${process.env.PROVENTEN_API_KEY}`,
  },
});

import os
import requests

response = requests.get(
    "https://api.proventen.com/v1/system/status",
    headers={"Authorization": f"Bearer {os.environ['PROVENTEN_API_KEY']}"},
)

Errors

Failed responses will use a consistent JSON error object so you can branch on code rather than parsing message text. This shape is upcoming and may gain fields before public launch.

{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required.",
    "request_id": "req_0b17c4"
  }
}

Rate limits

Sandbox traffic will be throttled per key. Exact quotas are still being set. Responses will include standard headers such as X-RateLimit-Limit and X-RateLimit-Remaining. Treat 429 as retryable with backoff.

Health and connection check. Use this first when you wire a new key: it confirms the host, environment, and that your token is accepted. Query include_checks=true when you want dependency detail.

Request parameters

Response payload

{
  "ok": true,
  "environment": "sandbox",
  "version": "v1.0",
  "checked_at": "2026-08-16T10:04:12Z"
}

• 200 OK — Service is reachable and the key is valid.
• 401 Unauthorized — Missing or invalid Bearer token.
• 422 Unprocessable Entity — Query parameters failed validation.

curl https://api.proventen.com/v1/system/status \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://api.proventen.com/v1/system/status', {
  headers: {
    Authorization: `Bearer ${process.env.PROVENTEN_API_KEY}`,
  },
});

const status = await res.json();
console.log(status.environment, status.ok);

import os
import requests

res = requests.get(
    "https://api.proventen.com/v1/system/status",
    headers={"Authorization": f"Bearer {os.environ['PROVENTEN_API_KEY']}"},
)
print(res.json())

Register an HTTPS endpoint for webhook events. ProvenTen will POST signed JSON when subscribed events occur. Rotate the returned secret if it is ever exposed.

Request parameters

Response payload

{
  "id": "sub_8f2c1a",
  "url": "https://example.com/webhooks/proventen",
  "events": ["workflow.completed", "reference.matched"],
  "status": "active",
  "created_at": "2026-08-16T10:05:41Z"
}

• 200 OK — Subscription created or updated.
• 401 Unauthorized — Missing or invalid Bearer token.
• 422 Unprocessable Entity — Invalid URL, empty events list, or unsupported event type.

curl -X POST https://api.proventen.com/v1/events/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/proventen",
    "events": ["workflow.completed", "reference.matched"]
  }'

const res = await fetch('https://api.proventen.com/v1/events/subscribe', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PROVENTEN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/webhooks/proventen',
    events: ['workflow.completed', 'reference.matched'],
  }),
});

import os
import requests

res = requests.post(
    "https://api.proventen.com/v1/events/subscribe",
    headers={"Authorization": f"Bearer {os.environ['PROVENTEN_API_KEY']}"},
    json={
        "url": "https://example.com/webhooks/proventen",
        "events": ["workflow.completed", "reference.matched"],
    },
)

Create and inspect reference workflows. The resource list, filters, and write methods will land here. Schema details will be published with the first sandbox build.

Read-only access to workspace members who can act on references. Intended for admin tooling, not for end-user login. Coming soon.