Skip to content
VeraFrame Docs

REST API

Integration deployments expose a REST API that covers the current VeraFrame capabilities available in the integrated application: validation and generation, document templates, source groups, validation history, audit exports, and tenant admin actions. The UI is one consumer of this API; your backend can be another.

This page is a practical reference to the currently implemented routes. Treat the deployed API itself as the source of truth for request and response shapes.

Base URL

The base URL for your deployment is of the form:

https://<your-deployment>.veraframe.io/api/v1

Or, for self-hosted deployments, whatever hostname you assign to the API Gateway in your cloud.

Authentication

Two authentication methods are supported:

Bearer token (users)

Obtained either through local login or through your deployment’s OIDC/JWT flow.

POST /auth/login
{ "email": "...", "password": "...", "customer_id": "..." }

POST /auth/login is available only in deployments that use local login. JWT/OIDC deployments do not expose local login and expect the bearer token to come from the identity provider.

Successful login returns a token field to use in subsequent requests:

Authorization: Bearer <token>

The same bearer token is used for POST /auth/me and all authenticated API calls.

In enterprise JWT/OIDC deployments, the token can also carry:

  • VeraFrame app-role mapping — for example, mapping customer roles such as vf_admins into VeraFrame’s own admin / user / viewer role model.
  • Data-access roles — used to decide which source groups the current user is allowed to use.

API key (integrations)

For service-to-service integrations where you do not use an end-user bearer token. Configure the key per tenant and send it in the request body together with customer_id:

{
  "customer_id": "your-tenant-id",
  "api_key": "..."
}

The unified /validate endpoint

The integrated API uses one authenticated validation endpoint:

POST /api/v1/validate

The mode field selects the behavior:

modeRequired fieldsDescription
validatequestion, chatbot_response, plus configured sources via source_groups, urls, or inline_textValidate an existing answer against sources.
generatequestion, plus configured sources via source_groups, urls, or inline_textGenerate a new answer and validate it.
validate_and_fixquestion, chatbot_response, plus configured sources via source_groups, urls, or inline_textValidate an answer and produce a corrected version when needed.

The integrated handler expects source material from configured source groups, optional inline text, and optional URLs. Upload-based s3_keys / asset_keys flows belong to the separate upload-oriented app API, not this integrated handler.

Responses are synchronous in the current integrated handler. A successful call returns 200 with the mode-specific payload.

Document templates

Templates are managed through authenticated admin endpoints. All require the document_templates feature.

  • POST /api/v1/templates — list all templates, including inactive ones.
  • POST /api/v1/templates/{id} — get template detail with schema.
  • POST /api/v1/templates/upload-url — get a presigned S3 URL to upload a new template file.
  • POST /api/v1/templates/{id}/scan — run placeholder detection and build the initial schema.
  • POST /api/v1/templates/{id}/save — save the schema definition and active flag.
  • POST /api/v1/templates/{id}/delete — delete the template.

Source groups

  • POST /api/v1/sources — list all source groups with file inventory.
  • POST /api/v1/sources/upload-url — get a presigned URL for uploading a file into a group.
  • POST /api/v1/sources/group/save — create or update a source group.
  • POST /api/v1/sources/group/delete — delete a group, optionally purging its files.
  • POST /api/v1/sources/file/delete — delete a single file.

POST /api/v1/sources/group/save supports the current source-group access-control fields:

  • allowed_roles — optional list of identity-provider roles/claims that are allowed to use the group.
  • For API-backed endpoints, endpoints[].authz_forwarding — optional booleans that control whether VeraFrame forwards:
    • user_id
    • customer_id
    • data_access_roles
    • original_jwt

If allowed_roles is omitted or empty, the group is available to all users in the tenant.

Source-group enforcement

When /validate uses source_groups, VeraFrame enforces source-group access server-side before retrieval:

  • groups the user is allowed to use are fetched normally
  • groups the user is not allowed to use are skipped
  • the response metadata can indicate that source access was filtered

This means a caller cannot bypass source-group restrictions simply by passing a forbidden source_groups list in the request body.

Downstream REST API context forwarding

For API-backed source groups, VeraFrame can optionally forward selected user context to the downstream REST API:

  • X-VeraFrame-User-Id
  • X-VeraFrame-Customer-Id
  • X-VeraFrame-Data-Access-Roles
  • X-VeraFrame-Original-JWT

This forwarding is configured per endpoint and is off by default. It does not replace VeraFrame’s own inbound authentication, and it does not replace the downstream service’s own technical authentication. Treat it as additional context for your downstream authorization logic.

This is also the recommended pattern when your organization needs document-level or record-level authorization that is more fine-grained than VeraFrame’s own source-group controls. VeraFrame respects the customer’s existing access-control process instead of trying to take ownership of it:

  • VeraFrame decides whether the caller may use the source group at all.
  • The downstream REST API decides whether that same caller may access the specific document, case, contract, or record.

In other words, VeraFrame integrates into the authorization model you already run. It does not try to replace your existing rights-management layer.

Validation history and review

  • POST /api/v1/history — query validation history (filters: user, mode, date range, confidence).
  • POST /api/v1/history/{id}/review — apply a review action (approve, reject, edit, handoff, external_approve, external_reject).
  • POST /api/v1/stats — tenant-level usage counters.
  • POST /api/v1/analytics — full analytics payload.
  • POST /api/v1/analytics/csv — CSV export.

Audit

  • POST /api/v1/audit — query audit events.
  • POST /api/v1/audit/export — export audit events as JSON or CSV for a date range.
  • POST /api/v1/system-card — the current system card.

The default audit export profile is enterprise_v1. It is intended to be the standard pull-based integration point for VeraFrame business and audit logs.

Example:

POST /api/v1/audit/export
{
  "date_from": "2026-04-01",
  "date_to": "2026-04-17",
  "format": "json"
}

Supported request fields:

  • format — json or csv
  • days — rolling export window when explicit dates are not provided
  • date_from — YYYY-MM-DD
  • date_to — YYYY-MM-DD
  • profile — enterprise_v1 or raw

enterprise_v1 returns a normalized, sanitized event structure with a stable schema version and pseudonymized actor reference. raw is available for backwards compatibility if you need the earlier low-level event shape.

SaaS user management

For shared SaaS tenants:

  • POST /api/v1/saas/users — list users.
  • POST /api/v1/saas/users/save — create or update a user.
  • POST /api/v1/saas/users/delete — remove a user.
  • POST /api/v1/saas/billing-portal — get the Stripe billing portal URL.
  • POST /api/v1/account/export — export tenant account data as a ZIP bundle.
  • POST /api/v1/account/delete — terminate the tenant account after confirmation.

Rate limits

Rate limits are configurable per tenant. In the integrated handler, rate limit information is returned together with validation responses and enforced on authenticated calls.