{ "openapi": "3.1.0", "info": { "title": "FiledProof Agent Research API", "version": "0.9.0", "description": "Agent-native specialist research over official SEC filings, served from a durable evidence store first." }, "servers": [ { "url": "/" } ], "x-filedproof-agent-strategy": { "primaryCustomer": "AI agents", "humanSurfaceRole": "trust, documentation, evidence review, developer evaluation", "mcp": { "endpoint": "/mcp", "protocolVersion": "2026-07-28" }, "dataPlane": "durable_store_first", "moat": "reusable filing-grounded disclosure intelligence" }, "paths": { "/v1/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Discover FiledProof agent fit, operations, protocols, data plane, limits, and trust semantics", "responses": { "200": { "description": "capabilities.v2" } } } }, "/v1/data-plane/status": { "get": { "operationId": "getDataPlaneStatus", "summary": "Inspect durable SEC catalog, ingest freshness, and derived-intelligence availability", "responses": { "200": { "description": "Durable data-plane status" } } } }, "/v1/resolve/{identifier}": { "get": { "operationId": "resolveIssuer", "summary": "Resolve a ticker, CIK, or exact company name", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." } ], "responses": { "200": { "description": "Resolved issuer" }, "409": { "description": "Ambiguous identifier" } } } }, "/v1/company/{identifier}/filings": { "get": { "operationId": "listFilings", "summary": "List recent or bounded historical SEC filings", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." }, { "name": "forms", "in": "query", "schema": { "type": "string" } }, { "name": "history", "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Filing metadata with data-plane provenance" } } } }, "/v1/filing/{identifier}/{accession}/evidence": { "get": { "operationId": "getFilingEvidence", "summary": "Retrieve normalized source evidence from one filing", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." }, { "name": "accession", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "item", "in": "query", "schema": { "type": "string" } }, { "name": "section", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "evidence.v1 records" } } } }, "/v1/research/search/{identifier}": { "get": { "operationId": "searchFilingEvidence", "summary": "Rank source evidence across a bounded set of filings", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "forms", "in": "query", "schema": { "type": "string" } }, { "name": "filings", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 6 } }, { "name": "history", "in": "query", "schema": { "type": "boolean" } }, { "name": "item", "in": "query", "schema": { "type": "string" } }, { "name": "section", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "search.v1 ranked evidence with explicit scope" } } } }, "/v1/research/evidence-pack/{identifier}": { "get": { "operationId": "buildEvidencePack", "summary": "Build compact answer-ready primary-source evidence for an upstream AI agent", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "forms", "in": "query", "schema": { "type": "string" } }, { "name": "filings", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 6 } }, { "name": "history", "in": "query", "schema": { "type": "boolean" } }, { "name": "item", "in": "query", "schema": { "type": "string" } }, { "name": "section", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30 } } ], "responses": { "200": { "description": "evidence-pack.v1" } } } }, "/v1/research/timeline/{identifier}": { "get": { "operationId": "buildDisclosureTimeline", "summary": "Build a chronological timeline of relevant source evidence", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 256 } }, { "name": "forms", "in": "query", "schema": { "type": "string" } }, { "name": "filings", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 6 } }, { "name": "history", "in": "query", "schema": { "type": "boolean" } }, { "name": "item", "in": "query", "schema": { "type": "string" } }, { "name": "section", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "timeline.v1" } } } }, "/v1/research/verify/{identifier}": { "post": { "operationId": "verifyClaimAgainstFilings", "summary": "Conservatively verify a claim against official SEC filing evidence", "description": "POST-only so claim text does not appear in the request URL. Returns verification.v2 with evidence.v1 provenance and deterministic support/contradiction signals.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "claim" ], "properties": { "claim": { "type": "string", "minLength": 1, "maxLength": 512 }, "forms": { "type": "array", "items": { "type": "string" }, "maxItems": 8, "default": [ "10-K", "10-Q", "8-K" ] }, "filings": { "type": "integer", "minimum": 1, "maximum": 6, "default": 6 }, "history": { "type": "boolean", "default": false }, "item": { "type": "string" }, "section": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 30, "default": 24 }, "maxArchiveFiles": { "type": "integer", "minimum": 1, "maximum": 20 } } } } } }, "responses": { "200": { "description": "verification.v2" }, "400": { "description": "Invalid claim or verification request" }, "422": { "description": "No retrievable filing evidence in scope" } } } }, "/v1/research/lineage/{identifier}": { "post": { "operationId": "buildDisclosureLineage", "summary": "Build or reuse historical topic-specific disclosure lineage", "description": "POST-only so topic text does not appear in the request URL. Returns disclosure-lineage.v1 with reusable disclosure-fingerprint.v1 nodes and same-form disclosure-transition.v1 edges. Persisted derived state is reused only when source-document fingerprints and extractor identity still match.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "topic" ], "properties": { "topic": { "type": "string", "minLength": 1, "maxLength": 256 }, "forms": { "type": "array", "items": { "type": "string" }, "maxItems": 8, "default": [ "10-K", "10-Q" ] }, "filings": { "type": "integer", "minimum": 2, "maximum": 6, "default": 6 }, "history": { "type": "boolean", "default": true }, "item": { "type": "string" }, "section": { "type": "string" }, "fingerprintLimit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 }, "comparisonLimit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 250 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "maxArchiveFiles": { "type": "integer", "minimum": 1, "maximum": 20 } } } } } }, "responses": { "200": { "description": "disclosure-lineage.v1" }, "409": { "description": "Derived-state concurrency conflict; retryable" }, "422": { "description": "No filings available in lineage scope" } } } }, "/v1/research/disclosure-matrix": { "post": { "operationId": "buildDisclosureMatrix", "summary": "Align a disclosure topic across two to six companies using reusable filing-grounded lineage", "description": "POST-only cross-company evidence operation. Returns disclosure-matrix.v1 with current SEC evidence, latest same-form transition evidence, per-company lineage state, and aggregate reuse metrics. It does not rank companies or infer materiality.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "identifiers", "topic" ], "properties": { "identifiers": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 2, "maxItems": 6 }, "topic": { "type": "string", "minLength": 1, "maxLength": 256 }, "forms": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 4, "default": [ "10-K" ] }, "filings": { "type": "integer", "minimum": 2, "maximum": 6, "default": 4 }, "history": { "type": "boolean", "default": true }, "item": { "type": "string" }, "section": { "type": "string" }, "fingerprintLimit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 30 }, "comparisonLimit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 }, "currentEvidenceLimit": { "type": "integer", "minimum": 1, "maximum": 12, "default": 6 }, "transitionEvidenceLimit": { "type": "integer", "minimum": 1, "maximum": 12, "default": 6 }, "maxArchiveFiles": { "type": "integer", "minimum": 1, "maximum": 20 } } } } } }, "responses": { "200": { "description": "disclosure-matrix.v1" }, "400": { "description": "Invalid or out-of-bounds matrix request" }, "422": { "description": "Fewer than two company lineages were available" } } } }, "/v1/research/changes/{identifier}": { "post": { "operationId": "checkDisclosureChanges", "summary": "Prioritize new SEC disclosure changes", "description": "Compare new same-form SEC filings since an optional checkpoint and return the topic-relevant changes that deserve attention first, with deterministic categories and attention signals, compact before/after evidence, uncertainty, exact SEC provenance, and retry-safe checkpoint state. The attention ranking is deterministic triage, not a materiality judgment. Use free issuer resolution and filing listing when coverage is uncertain; production payment preflight also prevents payment when there is no new filing work or no same-form baseline. A delivery retry repeats the identical authorized request with the same payment credential. Changing sinceAccession or any other payment-bound argument starts a new invocation and requires a new authorization when commerce is active.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." }, { "name": "Payment-Authorization", "in": "header", "required": false, "description": "MPP payment credential selected from the WWW-Authenticate challenge. Retry the exact same method, path, raw JSON body, and payment-bound arguments. Authorization is also accepted as a compatibility fallback.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "topic" ], "properties": { "sinceAccession": { "type": "string", "description": "Checkpoint accession from the prior monitor-check.v1 result." }, "topic": { "type": "string", "minLength": 1, "maxLength": 256, "example": "cybersecurity" }, "forms": { "type": "array", "items": { "type": "string" }, "maxItems": 8, "default": [ "10-K", "10-Q" ] }, "history": { "type": "boolean", "default": false }, "item": { "type": "string" }, "maxNewFilings": { "type": "integer", "minimum": 1, "maximum": 6, "default": 3 }, "comparisonLimit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 250 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "maxArchiveFiles": { "type": "integer", "minimum": 1, "maximum": 20 } } } } } }, "responses": { "200": { "description": "monitor-check.v1 paid specialist result. A 200 response can still report partial_failure or truncated backlog state; inspect status, haltedOnFailure, truncated, remainingNewFilings, and checkpoint.", "headers": { "Payment-Receipt": { "description": "Base64url-encoded payment receipt metadata when commerce is active and the paid operation was authorized.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$id": "https://filedproof.davisvillelabs.com/schemas/monitor-check.v1", "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "purpose", "issuer", "topic", "forms", "mode", "status", "changeDetected", "checkpoint", "priorCheckpoint", "latestAvailable", "newFilingsDetected", "events", "truncated", "remainingNewFilings", "haltedOnFailure", "changeCount", "highPriorityChangeCount", "overallAttention", "attentionCounts", "scope", "agentGuidance" ], "properties": { "schemaVersion": { "const": "monitor-check.v1" }, "purpose": { "type": "string" }, "issuer": { "type": "object", "additionalProperties": true }, "topic": { "type": "string", "minLength": 1 }, "forms": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "initial_snapshot", "incremental" ] }, "status": { "type": "string", "enum": [ "no_new_filing", "checked", "change_detected", "partial_failure" ] }, "changeDetected": { "type": "boolean" }, "checkpoint": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "accession", "form", "filingDate", "reportDate" ], "properties": { "accession": { "type": "string", "minLength": 1 }, "form": { "type": [ "string", "null" ] }, "filingDate": { "type": [ "string", "null" ] }, "reportDate": { "type": [ "string", "null" ] } } } ] }, "priorCheckpoint": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "accession", "form", "filingDate", "reportDate" ], "properties": { "accession": { "type": "string", "minLength": 1 }, "form": { "type": [ "string", "null" ] }, "filingDate": { "type": [ "string", "null" ] }, "reportDate": { "type": [ "string", "null" ] } } } ] }, "latestAvailable": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "accession", "form", "filingDate", "reportDate" ], "properties": { "accession": { "type": "string", "minLength": 1 }, "form": { "type": [ "string", "null" ] }, "filingDate": { "type": [ "string", "null" ] }, "reportDate": { "type": [ "string", "null" ] } } } ] }, "newFilingsDetected": { "type": "integer", "minimum": 0 }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "status", "current", "baseline", "change" ], "properties": { "schemaVersion": { "const": "monitor-event.v1" }, "status": { "type": "string", "enum": [ "topic_change_detected", "no_detected_topic_change", "insufficient_baseline", "comparison_failed" ] }, "current": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "accession", "form", "filingDate", "reportDate" ], "properties": { "accession": { "type": "string", "minLength": 1 }, "form": { "type": [ "string", "null" ] }, "filingDate": { "type": [ "string", "null" ] }, "reportDate": { "type": [ "string", "null" ] } } } ] }, "baseline": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "accession", "form", "filingDate", "reportDate" ], "properties": { "accession": { "type": "string", "minLength": 1 }, "form": { "type": [ "string", "null" ] }, "filingDate": { "type": [ "string", "null" ] }, "reportDate": { "type": [ "string", "null" ] } } } ] }, "change": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": true, "required": [ "schemaVersion", "changed", "changes" ], "properties": { "schemaVersion": { "const": "disclosure-change.v1" }, "changed": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "kind", "category", "attention", "confidence", "signals", "before", "after" ], "properties": { "kind": { "type": "string", "enum": [ "addition", "removal", "revised_disclosure", "moved_equivalent" ] }, "category": { "type": "string", "minLength": 1 }, "attention": { "type": "object", "additionalProperties": true, "required": [ "level", "score" ], "properties": { "level": { "type": "string", "enum": [ "high", "medium", "low" ] }, "score": { "type": "number" } } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "signals": { "type": "array", "items": { "type": "string" } }, "before": { "type": [ "object", "null" ], "additionalProperties": true }, "after": { "type": [ "object", "null" ], "additionalProperties": true } } } }, "changeCount": { "type": "integer", "minimum": 0 }, "highPriorityChangeCount": { "type": "integer", "minimum": 0 }, "overallAttention": { "type": "string", "enum": [ "high", "medium", "low", "none" ] }, "attentionCounts": { "type": "object", "additionalProperties": false, "required": [ "high", "medium", "low" ], "properties": { "high": { "type": "integer", "minimum": 0 }, "medium": { "type": "integer", "minimum": 0 }, "low": { "type": "integer", "minimum": 0 } } }, "limitations": { "type": "array", "items": { "type": "string" } } } } ] }, "limitation": { "type": "string" }, "searchScope": { "type": "object", "additionalProperties": true }, "error": { "type": "object", "additionalProperties": true, "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "truncated": { "type": "boolean" }, "remainingNewFilings": { "type": "integer", "minimum": 0 }, "haltedOnFailure": { "type": "boolean" }, "changeCount": { "type": "integer", "minimum": 0 }, "highPriorityChangeCount": { "type": "integer", "minimum": 0 }, "overallAttention": { "type": "string", "enum": [ "high", "medium", "low", "none" ] }, "attentionCounts": { "type": "object", "additionalProperties": false, "required": [ "high", "medium", "low" ], "properties": { "high": { "type": "integer", "minimum": 0 }, "medium": { "type": "integer", "minimum": 0 }, "low": { "type": "integer", "minimum": 0 } } }, "scope": { "type": "object", "additionalProperties": true }, "limitations": { "type": "array", "items": { "type": "string" } }, "agentGuidance": { "type": "object", "additionalProperties": true, "required": [ "nextAction", "invocationBoundary" ], "properties": { "reviewOrder": { "type": "string" }, "nextAction": { "type": "string" }, "invocationBoundary": { "type": "string" } } } } }, "examples": { "noNewFiling": { "summary": "Checkpoint is already current", "value": { "schemaVersion": "monitor-check.v1", "purpose": "checkpointed recurring SEC disclosure monitoring for an upstream AI agent", "issuer": { "cik": "0000789019", "ticker": "MSFT", "name": "MICROSOFT CORP" }, "topic": "cybersecurity", "forms": [ "10-K", "10-Q" ], "mode": "incremental", "status": "no_new_filing", "changeDetected": false, "checkpoint": { "accession": "0000789019-26-000100", "form": "10-Q", "filingDate": "2026-07-30", "reportDate": "2026-06-30" }, "priorCheckpoint": { "accession": "0000789019-26-000100", "form": "10-Q", "filingDate": "2026-07-30", "reportDate": "2026-06-30" }, "latestAvailable": { "accession": "0000789019-26-000100", "form": "10-Q", "filingDate": "2026-07-30", "reportDate": "2026-06-30" }, "newFilingsDetected": 0, "events": [], "truncated": false, "remainingNewFilings": 0, "haltedOnFailure": false, "changeCount": 0, "highPriorityChangeCount": 0, "overallAttention": "none", "attentionCounts": { "high": 0, "medium": 0, "low": 0 }, "scope": { "history": false, "dataPlane": "durable_store" }, "agentGuidance": { "nextAction": "Retain checkpoint.accession and call again after the issuer files a new monitored form.", "invocationBoundary": "A delivery retry repeats the identical authorized request with the same credential. Changing sinceAccession or any other bound argument starts a new invocation and, when commerce is active, requires a new authorization." } } }, "partialFailure": { "summary": "Earlier work is preserved but a later filing was not consumed", "value": { "schemaVersion": "monitor-check.v1", "purpose": "checkpointed recurring SEC disclosure monitoring for an upstream AI agent", "issuer": { "cik": "0000789019", "ticker": "MSFT", "name": "MICROSOFT CORP" }, "topic": "cybersecurity", "forms": [ "10-Q" ], "mode": "incremental", "status": "partial_failure", "changeDetected": true, "checkpoint": { "accession": "0000789019-26-000100", "form": "10-Q", "filingDate": "2026-07-30", "reportDate": "2026-06-30" }, "priorCheckpoint": { "accession": "0000789019-26-000050", "form": "10-Q", "filingDate": "2026-04-30", "reportDate": "2026-03-31" }, "latestAvailable": { "accession": "0000789019-26-000150", "form": "10-Q", "filingDate": "2026-10-30", "reportDate": "2026-09-30" }, "newFilingsDetected": 2, "events": [ { "schemaVersion": "monitor-event.v1", "status": "topic_change_detected", "current": { "accession": "0000789019-26-000100", "form": "10-Q", "filingDate": "2026-07-30", "reportDate": "2026-06-30" }, "baseline": { "accession": "0000789019-26-000050", "form": "10-Q", "filingDate": "2026-04-30", "reportDate": "2026-03-31" }, "change": { "schemaVersion": "disclosure-change.v1", "changed": true, "changes": [] } }, { "schemaVersion": "monitor-event.v1", "status": "comparison_failed", "current": { "accession": "0000789019-26-000150", "form": "10-Q", "filingDate": "2026-10-30", "reportDate": "2026-09-30" }, "baseline": { "accession": "0000789019-26-000100", "form": "10-Q", "filingDate": "2026-07-30", "reportDate": "2026-06-30" }, "change": null, "error": { "code": "comparison_failed", "message": "Comparison could not be completed.", "retryable": true } } ], "truncated": true, "remainingNewFilings": 1, "haltedOnFailure": true, "changeCount": 0, "highPriorityChangeCount": 0, "overallAttention": "none", "attentionCounts": { "high": 0, "medium": 0, "low": 0 }, "scope": { "history": false, "dataPlane": "durable_store" }, "limitations": [ "A failed comparison never advances the checkpoint past the failed filing." ], "agentGuidance": { "reviewOrder": "Review high-attention changes first, then medium and low.", "nextAction": "Start a new invocation with sinceAccession=checkpoint.accession to retry the unconsumed filing.", "invocationBoundary": "A delivery retry repeats the identical authorized request with the same credential. Changing sinceAccession or any other bound argument starts a new invocation and, when commerce is active, requires a new authorization." } } } } } } }, "402": { "description": "MPP payment challenge when FiledProof commerce is enabled and applicability preflight confirms paid work is available.", "headers": { "WWW-Authenticate": { "description": "One or more MPP Payment challenges. Select a supported method, create the credential, and retry the identical request using Payment-Authorization.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "status", "detail", "payment" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "const": 402 }, "detail": { "type": "string" }, "payment": { "type": "object", "required": [ "protocol", "operation", "priceCents", "currency", "methods" ], "properties": { "protocol": { "const": "MPP" }, "operation": { "const": "check_disclosure_changes" }, "priceCents": { "const": 1500 }, "currency": { "const": "USD" }, "methods": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "409": { "description": "Checkpoint is invalid or already current; no payment challenge is issued." }, "422": { "description": "Requested monitoring scope has no comparable same-form baseline; no payment challenge is issued." }, "503": { "description": "Specialist operation or payment provider temporarily unavailable." } }, "x-filedproof-outcome": { "decisionCompression": true, "returns": [ "ranked changes", "category", "attention", "signals", "before/after evidence", "uncertainty", "SEC provenance", "recommended follow-up", "checkpoint" ], "resultContract": { "schemaVersion": "monitor-check.v1", "topLevelStatus": [ "no_new_filing", "checked", "change_detected", "partial_failure" ], "changePath": "events[].change.changes[]", "evidencePaths": [ "events[].change.changes[].before", "events[].change.changes[].after" ], "checkpointPath": "checkpoint.accession", "incompleteSignals": [ "status=partial_failure", "haltedOnFailure=true", "truncated=true", "remainingNewFilings>0" ], "schemaSource": "OpenAPI 200 response and MCP tool outputSchema" }, "doesNotConclude": [ "legal materiality", "accounting materiality", "economic significance", "investment recommendation", "semantic equivalence", "motive", "causation" ] }, "x-filedproof-commerce": { "paymentsRequired": true, "protocol": "MPP", "priceCents": 1500, "currency": "USD", "methods": [ "stripe", "tempo" ], "paymentMethods": [ { "id": "stripe", "protocol": "MPP", "method": "stripe", "provider": "stripe", "intents": [ "charge" ], "paymentMethodTypes": [ "card", "link" ] }, { "id": "stripe-mpp-tempo", "protocol": "MPP", "method": "tempo", "provider": "stripe", "asset": "USDC.e", "network": "tempo", "intents": [ "charge" ], "merchantSettlement": "stripe-balance-fiat" } ], "stablecoin": { "method": "tempo", "provider": "stripe", "network": "tempo", "asset": "USDC.e", "merchantSettlement": "stripe-balance-fiat" }, "preflightBeforeChallenge": true, "handoff": { "mcp": { "challengeLocation": "JSON-RPC error.data.challenges", "credentialLocation": "params._meta['org.paymentauth/credential']", "receiptLocation": "result._meta['org.paymentauth/receipt']" }, "http": { "challengeHeader": "WWW-Authenticate", "credentialHeader": "Payment-Authorization", "credentialHeaderFallback": "Authorization", "receiptHeader": "Payment-Receipt" }, "identicalRequestRetry": "A delivery retry repeats the identical authorized request with the same payment credential. Changing sinceAccession or any other payment-bound argument starts a new invocation and requires a new authorization when commerce is active.", "settledRecoveryTtlSeconds": 86400, "humanCheckoutRequired": false } }, "x-davisville-proof": { "field": "davisvilleProof", "schema": "davisville-proof.v1", "evidenceKernel": "davisville-evidence-kernel.v1", "kernelUrl": "https://davisvillelabs.com/agents/evidence-kernel.json", "primitivesUrl": "https://davisvillelabs.com/agents/evidence-kernel-primitives.v1.json", "schemaUrl": "https://davisvillelabs.com/agents/davisville-proof.v1.schema.json", "conformanceUrl": "https://davisvillelabs.com/agents/evidence-kernel-conformance-v1.json", "trustContractUrl": "https://davisvillelabs.com/agents/trust.json", "manifestUrl": "https://filedproof.davisvillelabs.com/.well-known/davisville-proof.json", "deliveredOn": [ { "operation": "filedproof.reconcile_financial_fact", "http": "POST /v1/research/financial-fact", "resultSchema": "financial-fact-reconciliation.v1" }, { "operation": "filedproof.check_disclosure_changes", "http": "POST /v1/research/changes/{identifier}", "resultSchema": "monitor-check.v1" } ], "productResultAuthority": "The FiledProof product-specific result remains authoritative; davisvilleProof is an additive portable evidence envelope and cannot strengthen the underlying SEC-grounded conclusion.", "integritySemantics": "The SHA-256 digest detects canonical-content mutation and supports reproducibility. It is not a signature, source authentication, factual truth attestation, or materiality judgment." } } }, "/v1/research/compare/{identifier}": { "get": { "operationId": "compareFilings", "summary": "Create a source-backed structural comparison pack", "parameters": [ { "name": "identifier", "in": "path", "required": true, "example": "MSFT", "schema": { "type": "string" }, "description": "Ticker, CIK, or exact SEC company name." }, { "name": "left", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "right", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "item", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "comparison-pack.v1 with evidence.v1 records" } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "MCP 2026-07-28 stateless endpoint", "responses": { "200": { "description": "JSON-RPC MCP response" }, "400": { "description": "Protocol or header mismatch" } } } }, "/v1/research/financial-fact/preflight": { "post": { "operationId": "preflightFinancialFact", "summary": "Check whether a quarterly SEC financial fact can be safely reconciled before payment", "description": "Free. Validates the issuer, anchor filing, metric, requested fiscal quarter, and required SEC Company Facts contexts. Does not reveal the reconciled value, source values, or arithmetic.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cik": { "type": "string", "pattern": "^(?:CIK)?\\d{1,10}$", "description": "SEC Central Index Key for one issuer." }, "anchor_accession": { "type": "string", "pattern": "^\\d{10}-\\d{2}-\\d{6}$", "description": "One non-amended 10-Q or 10-K accession that anchors the requested fiscal quarter." }, "metric": { "type": "string", "enum": [ "revenue", "net_income", "operating_cash_flow" ], "description": "Financial metric to reconcile: revenue, net income, or operating cash flow." }, "period_start": { "type": "string", "format": "date", "description": "Standalone fiscal-quarter start date." }, "period_end": { "type": "string", "format": "date", "description": "Standalone fiscal-quarter end date." } }, "required": [ "cik", "anchor_accession", "metric", "period_start", "period_end" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "financial-fact-preflight.v1", "content": { "application/json": { "schema": { "type": "object", "required": [ "schemaVersion", "operation", "canonicalRequest", "status", "eligible", "checks", "price", "paymentMethods", "disclosureBoundary" ], "properties": { "schemaVersion": { "const": "financial-fact-preflight.v1" }, "operation": { "const": "filedproof.reconcile_financial_fact" }, "canonicalRequest": { "type": "object" }, "status": { "enum": [ "eligible", "ineligible" ] }, "eligible": { "type": "boolean" }, "checks": { "type": "object" }, "price": { "type": "object" }, "paymentMethods": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" }, "disclosureBoundary": { "type": "string" } }, "additionalProperties": true } } } } } } }, "/v1/research/financial-fact": { "post": { "operationId": "reconcileFinancialFact", "summary": "Reconcile one quarterly SEC financial fact", "description": "Reconcile one standalone-quarter revenue, net income, or operating cash flow fact from official SEC reporting context and return the normalized value, direct/derived basis, reproducible subtraction when required, validation checks, and exact SEC evidence, or explicitly abstain. Free applicability work occurs before any payment challenge.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cik": { "type": "string", "pattern": "^(?:CIK)?\\d{1,10}$", "description": "SEC Central Index Key for one issuer." }, "anchor_accession": { "type": "string", "pattern": "^\\d{10}-\\d{2}-\\d{6}$", "description": "One non-amended 10-Q or 10-K accession that anchors the requested fiscal quarter." }, "metric": { "type": "string", "enum": [ "revenue", "net_income", "operating_cash_flow" ], "description": "Financial metric to reconcile: revenue, net income, or operating cash flow." }, "period_start": { "type": "string", "format": "date", "description": "Standalone fiscal-quarter start date." }, "period_end": { "type": "string", "format": "date", "description": "Standalone fiscal-quarter end date." } }, "required": [ "cik", "anchor_accession", "metric", "period_start", "period_end" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "financial-fact-reconciliation.v1", "headers": { "Payment-Receipt": { "description": "Existing FiledProof MPP receipt convention when commerce is active.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "schemaVersion", "operation", "resultId", "status", "canonicalRequest", "resolvedMetric", "period", "scope", "source", "anchorFiling", "value", "currency", "resultBasis", "derivation", "evidence", "validation", "limitations" ], "properties": { "schemaVersion": { "const": "financial-fact-reconciliation.v1" }, "operation": { "const": "filedproof.reconcile_financial_fact" }, "resultId": { "type": "string" }, "status": { "enum": [ "resolved", "ambiguous", "unsupported", "unavailable" ] }, "canonicalRequest": { "type": "object" }, "resolvedMetric": { "type": "object" }, "value": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "period": { "type": "object" }, "scope": { "type": "object" }, "resultBasis": { "type": [ "string", "null" ], "enum": [ "direct", "derived", null ] }, "derivation": { "type": [ "object", "null" ] }, "evidence": { "type": "array" }, "validation": { "type": "object" }, "limitations": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object" }, "anchorFiling": { "type": "object" } }, "additionalProperties": true } } } }, "402": { "description": "MPP payment challenge only after deterministic eligibility is established." }, "409": { "description": "Ambiguous/recast context; no payment challenge." }, "422": { "description": "Unsupported or unavailable context; no payment challenge." }, "503": { "description": "Payment provider/runtime unavailable." } }, "x-filedproof-commerce": { "operation": "reconcile_financial_fact", "tool": "filedproof.reconcile_financial_fact", "http": "/v1/research/financial-fact", "preflight": "/v1/research/financial-fact/preflight", "priceCents": 100, "currency": "USD", "methods": [ "tempo", "stripe" ], "protocol": "MPP", "paymentRule": "Only an eligible, deterministically resolvable request reaches the payment challenge.", "preflightBeforeChallenge": true }, "x-filedproof-examples": { "direct": { "metric": "revenue", "resultBasis": "direct" }, "derived": { "metric": "operating_cash_flow", "derivation": "9-month YTD minus 6-month YTD" }, "abstention": { "reason": "conflicting recast values or incompatible context" } }, "x-davisville-proof": { "field": "davisvilleProof", "schema": "davisville-proof.v1", "evidenceKernel": "davisville-evidence-kernel.v1", "kernelUrl": "https://davisvillelabs.com/agents/evidence-kernel.json", "primitivesUrl": "https://davisvillelabs.com/agents/evidence-kernel-primitives.v1.json", "schemaUrl": "https://davisvillelabs.com/agents/davisville-proof.v1.schema.json", "conformanceUrl": "https://davisvillelabs.com/agents/evidence-kernel-conformance-v1.json", "trustContractUrl": "https://davisvillelabs.com/agents/trust.json", "manifestUrl": "https://filedproof.davisvillelabs.com/.well-known/davisville-proof.json", "deliveredOn": [ { "operation": "filedproof.reconcile_financial_fact", "http": "POST /v1/research/financial-fact", "resultSchema": "financial-fact-reconciliation.v1" }, { "operation": "filedproof.check_disclosure_changes", "http": "POST /v1/research/changes/{identifier}", "resultSchema": "monitor-check.v1" } ], "productResultAuthority": "The FiledProof product-specific result remains authoritative; davisvilleProof is an additive portable evidence envelope and cannot strengthen the underlying SEC-grounded conclusion.", "integritySemantics": "The SHA-256 digest detects canonical-content mutation and supports reproducibility. It is not a signature, source authentication, factual truth attestation, or materiality judgment." } } } }, "x-filedproof-commerce": { "enabled": true, "paidOperation": "check_disclosure_changes", "paidHttp": "/v1/research/changes/{identifier}", "priceCents": 1500, "currency": "USD", "methods": [ "stripe", "tempo" ], "preflightBeforeChallenge": true, "handoff": { "mcp": { "challengeLocation": "JSON-RPC error.data.challenges", "credentialLocation": "params._meta['org.paymentauth/credential']", "receiptLocation": "result._meta['org.paymentauth/receipt']" }, "http": { "challengeHeader": "WWW-Authenticate", "credentialHeader": "Payment-Authorization", "credentialHeaderFallback": "Authorization", "receiptHeader": "Payment-Receipt" }, "identicalRequestRetry": "A delivery retry repeats the identical authorized request with the same payment credential. Changing sinceAccession or any other payment-bound argument starts a new invocation and requires a new authorization when commerce is active.", "settledRecoveryTtlSeconds": 86400, "humanCheckoutRequired": false }, "resultContract": { "schemaVersion": "monitor-check.v1", "topLevelStatus": [ "no_new_filing", "checked", "change_detected", "partial_failure" ], "changePath": "events[].change.changes[]", "evidencePaths": [ "events[].change.changes[].before", "events[].change.changes[].after" ], "checkpointPath": "checkpoint.accession", "incompleteSignals": [ "status=partial_failure", "haltedOnFailure=true", "truncated=true", "remainingNewFilings>0" ], "schemaSource": "OpenAPI 200 response and MCP tool outputSchema" }, "paidOperations": [ { "operation": "reconcile_financial_fact", "tool": "filedproof.reconcile_financial_fact", "http": "/v1/research/financial-fact", "preflight": "/v1/research/financial-fact/preflight", "priceCents": 100, "currency": "USD", "methods": [ "tempo", "stripe" ], "protocol": "MPP", "paymentRule": "Only an eligible, deterministically resolvable request reaches the payment challenge." } ] }, "x-davisville-evidence-kernel": { "field": "davisvilleProof", "schema": "davisville-proof.v1", "evidenceKernel": "davisville-evidence-kernel.v1", "kernelUrl": "https://davisvillelabs.com/agents/evidence-kernel.json", "primitivesUrl": "https://davisvillelabs.com/agents/evidence-kernel-primitives.v1.json", "schemaUrl": "https://davisvillelabs.com/agents/davisville-proof.v1.schema.json", "conformanceUrl": "https://davisvillelabs.com/agents/evidence-kernel-conformance-v1.json", "trustContractUrl": "https://davisvillelabs.com/agents/trust.json", "manifestUrl": "https://filedproof.davisvillelabs.com/.well-known/davisville-proof.json", "deliveredOn": [ { "operation": "filedproof.reconcile_financial_fact", "http": "POST /v1/research/financial-fact", "resultSchema": "financial-fact-reconciliation.v1" }, { "operation": "filedproof.check_disclosure_changes", "http": "POST /v1/research/changes/{identifier}", "resultSchema": "monitor-check.v1" } ], "productResultAuthority": "The FiledProof product-specific result remains authoritative; davisvilleProof is an additive portable evidence envelope and cannot strengthen the underlying SEC-grounded conclusion.", "integritySemantics": "The SHA-256 digest detects canonical-content mutation and supports reproducibility. It is not a signature, source authentication, factual truth attestation, or materiality judgment." } }