API reference

Use the runtime API for SDK telemetry and governed actions. Use customer operations for authorized queries, configuration, and evidence exports. These paths use different credentials. An application key does not grant a person’s portal permissions.

Choose the API

Purpose	Starting point	Authentication
Record application activity or request a policy decision	Configured VeriProof runtime endpoint	Application SDK key
Query or manage customer records	Customer Portal API for the deployment	Supported authenticated user or workload flow
Automate supported customer operations	CLI or MCP	User sign-in or registered workload identity

Hosted runtime defaults to https://ingest.veriproof.app. For Customer-managed Azure, use the ingest base URL supplied for that environment. The portal address and ingest endpoint are not interchangeable.

Runtime authentication

Pass the complete issued application key to the SDK. It sets the protected-request headers required by the endpoint.


vp_cust_<customer-slug>.<functions-key>.<application-key>

The application-key segment belongs in X-API-Key; the Functions segment belongs in x-functions-key where required. The customer slug is not an authorization claim. Services resolve scope from validated credentials.

Direct HTTP clients must follow the endpoint’s authentication contract. Do not assume a local development configuration describes the Azure deployment.

Keep credentials out of browser code, source control, command history, logs, and examples. Package access and application runtime calls do not use the same credentials.

Customer operations

The portal uses its supported sign-in flow and authenticated session. For automation, prefer the documented CLI or MCP flow for the operation. Do not script a presumed email-and-password token endpoint or assume a fixed token lifetime.

Confirm tenant, role, application, and audit-engagement scope before sending a request. A valid identity can still be denied access to a specific record.

Read the response

Status	First check
`200`	Inspect the operation result; HTTP success is not necessarily a policy allowance or completed business action.
`400` or `422`	Read the returned validation code and field details. Their meaning depends on the endpoint.
`401`	Check the credential, expiry or revocation state, and intended endpoint.
`403`	Check the caller’s scope and permission for the operation.
`413`	Compare the request size with the endpoint’s configured limit.
`429`	Follow the retry instructions and the SDK’s bounded retry contract.
`503`	Read the returned error code and service state. Do not infer one cause from the status alone. `platform_write_freeze` means VeriProof has paused writes on every tenant: nothing was saved, reads still work, and you can resend the same request after `Retry-After`.

Never treat an unavailable policy service as permission to execute a protected action. For an uncertain business outcome, reconcile the original request before attempting another action.

Payloads and retries

Use the endpoint contract for body size, supported media, attachment handling, and batch limits. A batch limit applies to the entire request, not each item independently.

Where staged uploads are supported, use the returned attachment reference in telemetry instead of embedding a large binary. Keep uploaded content within the application’s approved data-handling scope.

Honor Retry-After when the operation permits a retry. Preserve the original semantic request and idempotency key. Authentication failures, policy denials, and changed-input conflicts are not ordinary transport retries.

Sandbox and test data

The shared portal demo uses example records. It is not an SDK ingest destination or a substitute for testing your own integration. Use a development application for write tests, with its assigned key and endpoint. See Explore the demo.

Versions and endpoint coverage

Versioned routes identify a contract family. Use the selected release record for compatibility and supported fields; do not infer a support period from the URL.

The HTTP endpoint catalog is generated from declared routes. It is an inventory, not proof of permissions or completed runtime qualification. Check the request and response contract and the relevant workflow guide before implementation.

API authentication: store and rotate application credentials.
SDK reference: configure supported client packages.
Human Review callbacks: verify review delivery and preserve replay safety.
Review events: event types, fields, and the catch-up read for review webhooks.
Release compatibility: check the versions being deployed.