API Reference

API Reference

Base URL: https://api.prova.cobound.dev
Authentication: Authorization: Bearer <api_key>
Content-Type: application/json

↓ OpenAPI JSON↓ Postman Collection
POST/verify

Analyze a reasoning chain and return a formal validity certificate.

Request body

fieldtypereqdescription
reasoningstringyesThe reasoning chain to analyze. 20-32,000 characters.
formatstringno"auto" | "structured" | "prose". Default: "auto".
retainbooleannoStore reasoning text with certificate. Default: true.
metadataobjectnoArbitrary key-value pairs attached to the certificate.
n_extraction_samplesintegerno1-5. Number of parallel extraction passes for consensus. Default: 1 (single call). Higher values improve reliability on ambiguous reasoning at proportional API cost.

Response (200 OK)

fieldtypereqdescription
certificate_idstringyesPRV-YYYY-XXXX format. Unique, permanent.
timestampstringyesISO 8601 UTC timestamp of certificate generation.
verdictstringyes"VALID" or "INVALID".
confidence_scoreintegeryes0-100. Extraction quality score. Adjusted by consensus agreement when n_extraction_samples > 1.
prova_versionstringyesProva version that generated this certificate.
validator_versionstringyescobound-validator version used for analysis.
extraction_prompt_versionstringyesExtraction prompt version (e.g. "v1").
argument_graphobjectyes{ nodes: [...], edges: [...] }. See Certificate Guide.
failureobjectyesFailure detail object, or null if VALID.
original_reasoningstringnoOriginal reasoning text, or null if retain=false.
metadataobjectyesCaller-provided metadata, echoed back.
certificate_urlstringyesPermanent public URL for this certificate.
sha256stringyesSHA-256 hash for independent verification. Includes consensus metadata when present.
extraction_consensusobjectnoConsensus metadata. Present only when n_extraction_samples > 1. null otherwise.

Extraction consensus (optional)

By submitting n_extraction_samples greater than 1, Prova runs multiple parallel extraction passes and takes the majority consensus graph. This improves reliability on ambiguous reasoning chains at proportional API cost. Recommended for production pipelines where extraction accuracy is critical.

extraction_consensus object (when n_extraction_samples > 1)

fieldtypereqdescription
samples_requestedintegeryesNumber of extraction passes requested.
samples_successfulintegeryesNumber of passes that returned a parseable graph.
node_agreement_ratefloatyesMean pairwise node F1 across all sample pairs. 0.0-1.0.
edge_agreement_ratefloatyesMean pairwise edge F1 across all sample pairs. 0.0-1.0.
verdict_agreement_ratefloatyesFraction of samples agreeing with chosen on extractable and ambiguous flags. 0.0-1.0.
chosen_sample_indexintegeryesIndex of the chosen (medoid) sample within the successful samples.
divergentbooleanyesTrue if node_agreement_rate < 0.7 or edge_agreement_rate < 0.6. Divergent extractions are rejected as EXTRACTION_AMBIGUOUS.

failure object (when verdict=INVALID)

fieldtypereqdescription
typestringyes"CIRCULAR" | "CONTRADICTION" | "UNSUPPORTED_LEAP".
failure_idstringnoRegistry entry ID (e.g. "CIRC-001").
locationstringyesPlain English description of where failure occurs.
descriptionstringyesFull failure description.
affected_nodesarrayyesNode IDs involved in the failure.
affected_edgesarrayyesEdge pairs {from, to} involved in the failure.
known_consequenceobjectnoKnown downstream consequence from the registry.
POST/verify/structured

Analyze a pre-built argument graph and return a formal validity certificate. Skips extraction entirely.

When to use this vs. POST /verify

Use /verify when your AI system produces natural language reasoning that needs to be parsed into a graph. Use /verify/structured when your agent framework (LangGraph, CrewAI, custom orchestrators) already maintains an explicit graph of claims and dependencies. The structured path is faster, has no extraction ambiguity, and always returns confidence_score: 100.

Request body

fieldtypereqdescription
nodesarrayyesArray of graph nodes. Minimum 2. Each node must have id (unique), text, and type.
edgesarrayyesArray of directed edges. Minimum 1. Each edge must have from and to referencing valid node IDs.
retainbooleannoStore the serialized graph as original_reasoning. Default: true.
metadataobjectnoArbitrary key-value pairs attached to the certificate.

nodes array item

fieldtypereqdescription
idstringyesUnique within the request. Used in edge from/to references.
textstringyesHuman-readable claim text.
typestringyes"premise" | "claim" | "conclusion". At least one of each required.

edges array item

fieldtypereqdescription
fromstringyesID of the source node.
tostringyesID of the target node.

Example request (3-node loan approval graph)

json
{
  "nodes": [
    { "id": "claim-1", "type": "premise",    "text": "The applicant has stable income" },
    { "id": "claim-2", "type": "claim",      "text": "They can make payments" },
    { "id": "claim-3", "type": "conclusion", "text": "Approve the loan" }
  ],
  "edges": [
    { "from": "claim-1", "to": "claim-2" },
    { "from": "claim-2", "to": "claim-3" }
  ],
  "retain": true,
  "metadata": { "pipeline": "loan-approvals-v2" }
}

Response (200 OK)

fieldtypereqdescription
certificate_idstringyesPRV-YYYY-XXXX format. Unique, permanent.
verdictstringyes"VALID" or "INVALID".
confidence_scoreintegeryesAlways 100 for structured input -- no extraction ambiguity.
extraction_prompt_versionstringyesAlways "structured-input-v1" for certificates from this endpoint.
argument_graphobjectyes{ nodes: [...], edges: [...] } derived from your submitted graph.
failureobjectyesFailure detail object, or null if VALID.
original_reasoningstringnoSerialized text representation of the submitted graph, or null if retain=false.
POST/repair

Verify a reasoning chain and auto-repair it if INVALID. Runs the full verify-suggest-apply-re-verify loop server-side.

How repair works

POST /repair runs the full pipeline in a single call: verify the original reasoning, generate Claude-powered repair suggestions, apply them, and re-verify. Up to max_iterations repair-verify cycles are run. Each iteration logs its own usage record. If the original is already VALID, returns immediately with iterations_used: 0.

Request body

fieldtypereqdescription
reasoningstringyesThe reasoning chain to verify and repair. 20-32,000 characters.
formatstringno"auto" | "structured" | "prose". Default: "auto".
retainbooleannoStore reasoning text with certificates. Default: true.
metadataobjectnoArbitrary key-value pairs attached to all certificates.
max_iterationsintegernoMaximum repair-verify cycles. 1-3. Default: 1.
fail_openbooleannoIf false, returns 422 when repair is unsuccessful. Default: true.

Response (200 OK)

fieldtypereqdescription
original_certificateobjectyesCertificate from the first (unrepaired) verification.
repaired_certificateobjectyesCertificate from the final repair iteration, or null if already VALID.
repaired_reasoningstringyesThe repaired reasoning text, or null if no repair was needed.
diffobjectyesLine-level diff between original and repaired reasoning, or null if no repair was needed.
iterations_usedintegeryesNumber of repair iterations run (0 if original was already VALID).
suggestions_appliedintegeryesTotal number of repair suggestions applied across all iterations.
repair_successfulbooleanyesTrue if the final certificate is VALID.

diff object

fieldtypereqdescription
lines_changedintegeryesNumber of lines that were modified.
lines_addedintegeryesNumber of lines added.
lines_removedintegeryesNumber of lines removed.
changesarrayyesArray of change objects: { type, line_number, before, after }.
GET/certificate/{id}

Retrieve a stored certificate by ID. Public -- no authentication required.

Path parameters

fieldtypereqdescription
idstringyesCertificate ID in PRV-YYYY-XXXX format.

Returns the same schema as POST /verify. Returns 404 if the certificate does not exist. Certificates are permanent -- they are never deleted.

GET/health

Health check. Returns current version information.

Response (200 OK)

fieldtypereqdescription
statusstringyes"ok"
versionstringyesProva version.
validator_versionstringyescobound-validator version.

Error codes

INPUT_TOO_SHORT422Reasoning chain is fewer than 20 characters.
INPUT_TOO_LONG422Reasoning chain exceeds 32,000 characters.
NO_STRUCTURE_DETECTED422No logical dependency structure found in input.
EXTRACTION_AMBIGUOUS422Multiple possible structures, confidence below threshold.
EXTRACTION_FAILED500Internal extraction error.
ANALYSIS_FAILED500Internal analysis error.
CERTIFICATE_NOT_FOUND404No certificate found with the given ID.
UNAUTHORIZED401Invalid or missing API key.
RATE_LIMITED429Monthly or burst rate limit reached.
DEMO_LIMIT_REACHED429Demo key IP limit reached (10 requests).
NO_REPAIR_POSSIBLE422Repair suggestions could not be generated for this reasoning chain.
REPAIR_UNSUCCESSFUL422Repair completed but reasoning remains INVALID (only when fail_open=false).

Rate limits

Free500 / month10 / min
Team10,000 / month60 / min
EnterpriseUnlimited / monthCustom
Demo key10 / IP (lifetime) / month5 / min