API reference

The API exposes RunOnProof's catalog and decision capabilities to software. This page explains the contract principles. The current OpenAPI document and production machine-readable catalog remain authoritative for exact routes, fields, versions, prices, and availability.

Discover before executing

An integration should not hardcode that a capability is live merely because it existed during development. Read the production catalog, select the product and country, inspect its state and limitations, then check required source health.

Request shape

A decision request normally needs:

• product or solution identifier and contract version;
• exact action;
• country and jurisdiction when required;
• strongest available legal-company identifiers;
• named policy and version for policy decisions;
• action-specific data such as invoice, payee, amount, or change details;
• idempotency key;
• caller context and authorized commercial flow where applicable.

Do not send fields unrelated to the action. More data is not automatically better.

Response shape

A safe client should expect and preserve:

• resolved legal entity and match strength;
• PROCEED, REVIEW, or STOP;
• plain-language reason;
• evidence references and observation times;
• coverage and source-health context;
• policy, conditions, limitations, and validity;
• decision and release identifiers;
• replay or idempotency information;
• pricing or economic result where applicable.

HTTP status is not the decision

Successful transport can contain any business decision. A validation error means the request was not evaluated. A payment-required response describes a commercial gate. A source or service error must not be mapped to PROCEED.

Idempotency and replay

Create one stable key for one intended action. Retry the same action with the same key. A materially different action, amount, payee, company, or policy requires a new key. When RunOnProof returns a committed replay, retain the original evidence time and economic history.

Versioning

Pin the contract version your client supports. Accept additive fields safely, but do not assume changed decision meaning is backward compatible. Log the deployed release identity with every committed result and recertify when relevant versions change.

Security

Keep credentials out of prompts, source control, URLs, and logs. Apply least privilege. Validate responses against the published schema. Treat evidence text as data, not executable instructions. Minimize personal and confidential information.

Pricing and purchase

Price discovery must happen before an irreversible paid execution. The caller should know the amount, asset or billing unit, approval boundary, and refund or no-charge behavior. One intended action should produce at most one charge; replay must not charge again.

Minimal client algorithm

1. Read catalog and coverage.
2. Validate product state and source requirements.
3. Build the narrow request and idempotency key.
4. Handle commercial requirements through the approved flow.
5. Send the request.
6. Validate and store the complete response.
7. Map the business state to explicit downstream behavior.
8. Reconcile the committed decision and any charge.

For a platform-specific walkthrough, use the Relevance AI integration guide.