{
  "openapi": "3.1.0",
  "info": {
    "title": "FiledProof Agent Research API",
    "version": "0.8.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,
            "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,
            "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,
            "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,
            "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,
            "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,
            "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,
            "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,
            "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": "Check topic-specific disclosure changes since an optional filing checkpoint",
        "description": "Returns monitor-check.v1. Save checkpoint.accession and pass it as sinceAccession on the next call. Backlogs are processed oldest-first and failed comparisons do not advance the checkpoint.",
        "parameters": [
          {
            "name": "identifier",
            "in": "path",
            "required": true,
            "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": {
                  "sinceAccession": {
                    "type": "string",
                    "description": "Checkpoint accession from the prior monitor-check.v1 result."
                  },
                  "topic": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256
                  },
                  "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"
          },
          "409": {
            "description": "Checkpoint not found in bounded filing history"
          }
        }
      }
    },
    "/v1/research/changes/scan": {
      "post": {
        "operationId": "scanDisclosureChanges",
        "summary": "Scan recurring disclosure changes across up to 10 companies",
        "description": "Returns disclosure-scan.v1 with per-company results, failure isolation, and updated checkpoints.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "identifiers",
                  "topic"
                ],
                "properties": {
                  "identifiers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 10
                  },
                  "checkpoints": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Map of exact requested identifier to prior checkpoint accession."
                  },
                  "topic": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256
                  },
                  "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": "disclosure-scan.v1"
          }
        }
      }
    },
    "/v1/research/compare/{identifier}": {
      "get": {
        "operationId": "compareFilings",
        "summary": "Create a source-backed structural comparison pack",
        "parameters": [
          {
            "name": "identifier",
            "in": "path",
            "required": true,
            "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"
          }
        }
      }
    }
  }
}