Skip to content

Schemas and discovery

Use the registered contracts to construct requests and retain the identities needed to understand their results.

The OpenAPI 3.1 document contains endpoint contracts and generated request, response and item schemas. The definitions below use that same builder, so their fields follow the service implementation.

Discover a use case

curl https://openauditor.ai/api/v1/use-cases
curl https://openauditor.ai/api/v1/use-cases/financial-audit

The catalog provides use-case IDs and item types. A detail response includes each item’s schema and assertions, context record types, reference schemas, parameters, example requests and the running model’s question qualifications.

Use case	Item types	Complete definition
Agent actions	`action`	Read JSON
AI output verification	`extracted_field`, `statement`	Read JSON
Contract compliance	`invoice`, `invoice_line`	Read JSON
Financial audit	`expense`, `approve_expense`, `vendor`, `create_vendor`, `change_vendor_bank`, `invoice`, `approve_invoice`, `payment`, `release_payment`	Read JSON
Insurance claims	`claim`, `pay_claim`	Read JSON

Validate the envelope and the item data

The top-level request defines the use case, item or items, context and options. The item.data schema comes from the chosen use case and item type. Checking only the common envelope does not validate a particular expense, contract line or action.

Related records have their own context schemas and require IDs. Reference sets use the pack’s declared schemas. Unknown record types, reference names and parameter names are rejected, so discover these names instead of inventing new context fields.

Request schemas

VerifyRequest

Read the generated JSON Schema

{
  "type": "object",
  "required": ["use_case", "item"],
  "properties": {
    "use_case": {
      "type": "string",
      "enum": [
        "agent-actions",
        "ai-output-verification",
        "contract-compliance",
        "financial-audit",
        "insurance-claims",
        "agent-actions@1",
        "agent-actions@2",
        "ai-output-verification@1",
        "contract-compliance@1",
        "financial-audit@1",
        "financial-audit@2",
        "financial-audit@3",
        "financial-audit@4",
        "insurance-claims@1",
        "insurance-claims@2"
      ],
      "description": "A use case alone runs its latest version. A pinned version past the latest two may be deprecated (it runs, with Deprecation and Sunset headers) or retired (410 version_retired); GET /v1/use-cases gives each version's status."
    },
    "item": {
      "type": "object",
      "required": ["type", "id", "data"],
      "additionalProperties": false,
      "properties": {
        "type": {"type": "string", "minLength": 1, "maxLength": 100},
        "id": {"type": "string", "minLength": 1, "maxLength": 200},
        "data": {"type": "object"}
      }
    },
    "context": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "records": {
          "type": "object",
          "additionalProperties": {"type": "array", "items": {"type": "object"}}
        },
        "references": {"type": "object"},
        "engagement": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "entity": {"type": "string", "maxLength": 200},
            "period": {
              "type": "object",
              "required": ["start", "end"],
              "additionalProperties": false,
              "properties": {
                "start": {"type": "string", "format": "date"},
                "end": {"type": "string", "format": "date"}
              }
            }
          }
        }
      }
    },
    "options": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "questions": {"type": "string", "enum": ["auto", "none"]},
        "skip": {"type": "array", "items": {"type": "string", "maxLength": 100}, "maxItems": 50},
        "certainty_target": {"type": "string", "pattern": "^0\\.9[0-9]{1,3}$"},
        "parameters": {"type": "object"}
      }
    }
  }
}

AuditRequest

Read the generated JSON Schema

{
  "type": "object",
  "required": ["use_case"],
  "oneOf": [{"required": ["items"]}, {"required": ["source"]}],
  "properties": {
    "use_case": {
      "type": "string",
      "enum": [
        "agent-actions",
        "ai-output-verification",
        "contract-compliance",
        "financial-audit",
        "insurance-claims",
        "agent-actions@1",
        "agent-actions@2",
        "ai-output-verification@1",
        "contract-compliance@1",
        "financial-audit@1",
        "financial-audit@2",
        "financial-audit@3",
        "financial-audit@4",
        "insurance-claims@1",
        "insurance-claims@2"
      ],
      "description": "A use case alone runs its latest version. A pinned version past the latest two may be deprecated (it runs, with Deprecation and Sunset headers) or retired (410 version_retired); GET /v1/use-cases gives each version's status."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["type", "id", "data"],
        "additionalProperties": false,
        "properties": {
          "type": {"type": "string", "minLength": 1, "maxLength": 100},
          "id": {"type": "string", "minLength": 1, "maxLength": 200},
          "data": {"type": "object"}
        }
      },
      "minItems": 1,
      "maxItems": 10000
    },
    "source": {
      "type": "object",
      "required": ["id", "mapping"],
      "additionalProperties": false,
      "description": "Build the items from an uploaded CSV or XLSX source; mapping.use_case must equal use_case. A PDF source is 409 source_not_tabular. documents and mapping.documents go together",
      "properties": {
        "id": {"type": "string"},
        "mapping": {"$ref": "#/components/schemas/Mapping"},
        "documents": {
          "type": "array",
          "minItems": 1,
          "maxItems": 100,
          "uniqueItems": true,
          "items": {"type": "string"},
          "description": "The PDF sources mapping.documents links rows to: the account's own, at most 100, 2,000 pages and 16 MiB of kept text (compressed) in all. Each is re-hashed and judged from the text kept at upload"
        }
      }
    },
    "context": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "records": {
          "type": "object",
          "additionalProperties": {"type": "array", "items": {"type": "object"}}
        },
        "references": {"type": "object"},
        "engagement": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "entity": {"type": "string", "maxLength": 200},
            "period": {
              "type": "object",
              "required": ["start", "end"],
              "additionalProperties": false,
              "properties": {
                "start": {"type": "string", "format": "date"},
                "end": {"type": "string", "format": "date"}
              }
            }
          }
        }
      }
    },
    "options": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "questions": {"type": "string", "enum": ["auto", "none"]},
        "skip": {"type": "array", "items": {"type": "string", "maxLength": 100}, "maxItems": 50},
        "certainty_target": {"type": "string", "pattern": "^0\\.9[0-9]{1,3}$"},
        "parameters": {"type": "object"}
      }
    }
  }
}

Response schemas

A single request returns a Verification. A batch status request returns an Audit; its paged items are Verification objects. AssertionResult describes the individual checks inside a verification. Error describes unsuccessful HTTP responses, which are separate from false or uncertain business verdicts.

Verification

Read the generated JSON Schema

{
  "type": "object",
  "required": [
    "id",
    "object",
    "use_case",
    "item",
    "verdict",
    "assertions",
    "risk",
    "configuration"
  ],
  "properties": {
    "id": {"type": "string"},
    "object": {"const": "verification"},
    "created_at": {"type": "string", "format": "date-time"},
    "use_case": {"type": "string"},
    "item": {
      "type": "object",
      "properties": {"type": {"type": "string"}, "id": {"type": "string"}}
    },
    "verdict": {"type": "string", "enum": ["true", "false", "uncertain"]},
    "probability_true": {"type": ["string", "null"]},
    "probability_basis": {"type": ["string", "null"]},
    "certainty": {
      "type": ["object", "null"],
      "properties": {
        "value": {"type": ["string", "null"]},
        "basis": {"type": "string"},
        "stratum": {"type": "string"},
        "bound": {"type": "string"},
        "measured_on": {"type": "integer"},
        "errors": {"type": "integer"},
        "note": {"type": "string"}
      }
    },
    "undecided": {"type": "array", "items": {"type": "object"}},
    "assertions": {"type": "array", "items": {"$ref": "#/components/schemas/AssertionResult"}},
    "indicators": {"type": "array", "items": {"type": "object"}},
    "risk": {"type": "object"},
    "scope": {"type": "object"},
    "configuration": {"type": "string"},
    "input_sha256": {"type": "string"},
    "manifest_sha256": {
      "type": "string",
      "description": "SHA-256 of this run's manifest (see /v1/audits/{id}/manifest); a verification's manifest is not stored"
    },
    "usage": {"type": "object"}
  }
}

AssertionResult

Read the generated JSON Schema

{
  "type": "object",
  "required": ["id", "test", "outcome", "evidence"],
  "properties": {
    "id": {"type": "string"},
    "test": {
      "type": "string",
      "description": "procedure:<id>@<version> or question:<id>@<version>"
    },
    "outcome": {
      "type": "string",
      "enum": [
        "holds",
        "fails",
        "insufficient_evidence",
        "not_applicable",
        "abstained",
        "unqualified",
        "not_asked",
        "skipped",
        "context_too_long",
        "model_unavailable"
      ]
    },
    "error_bound": {"type": "string"},
    "message": {"type": "string"},
    "facts": {"type": "object"},
    "answer": {
      "type": "object",
      "description": "The model's probability and the thresholds applied."
    },
    "facts_given": {"type": "object", "description": "Computed facts the model received."},
    "evidence": {
      "type": "array",
      "items": {"type": "string"},
      "description": "JSON pointers into the request."
    }
  }
}

Audit

Read the generated JSON Schema

{
  "type": "object",
  "properties": {
    "id": {"type": "string"},
    "object": {"const": "audit"},
    "status": {
      "type": "string",
      "enum": ["queued", "running", "canceling", "completed", "failed", "canceled"]
    },
    "use_case": {"type": "string"},
    "progress": {"type": "object"},
    "summary": {"type": ["object", "null"]},
    "usage": {
      "type": ["object", "null"],
      "description": "Once completed: the model questions the audit asked and answered from the cache, and its model time. Reported, not charged; an audit is charged by its items",
      "properties": {
        "questions_asked": {"type": "integer", "minimum": 0},
        "questions_cached": {"type": "integer", "minimum": 0},
        "model_ms": {"type": "integer", "minimum": 0}
      }
    },
    "configuration": {"type": ["string", "null"]},
    "created_at": {"type": "string"},
    "started_at": {"type": ["string", "null"]},
    "completed_at": {"type": ["string", "null"]},
    "expires_at": {"type": ["string", "null"]},
    "input_sha256": {"type": ["string", "null"]},
    "manifest_sha256": {
      "type": ["string", "null"],
      "description": "SHA-256 of the run manifest, once completed"
    },
    "source": {
      "type": ["string", "null"],
      "description": "The source the items were built from, or null for items sent inline"
    },
    "evidence_sha256": {
      "type": ["string", "null"],
      "description": "SHA-256 of the evidence index kept with an audit built from a source"
    },
    "error": {"type": "string", "description": "Why a failed audit failed."},
    "verifications": {"type": "object"},
    "links": {"type": "object"}
  }
}

Error

Read the generated JSON Schema

{
  "type": "object",
  "required": ["error"],
  "properties": {
    "error": {
      "type": "object",
      "required": ["type", "code", "message"],
      "properties": {
        "type": {"type": "string"},
        "code": {"type": "string"},
        "message": {"type": "string"},
        "param": {"type": "string"}
      }
    }
  }
}

Use schema and result identities together

The OpenAPI document reports the engine version. Returned verifications also identify the versioned use case, engine configuration and input hash. The configuration identifier excludes caller parameter overrides and skipped checks, so retain the full request and its options too. Keep those records when comparing runs: the same shape of request can produce different evidence if rules, models or qualification change.

Schema validation checks structure and field types. It does not establish that a receipt is authentic, a contract term is complete or the supplied comparison population covers every relevant record. Those boundaries remain part of your integration and review process.

Continue reading

Verify an item — build a request from the discovered schema.
Verification results — interpret the response fields.
Running configuration — inspect model and question qualifications.