{"openapi": "3.0.3", "info": {"title": "SecProbe Research API", "version": "1.2.0", "description": "Both endpoints accept self-reported email and agent headers without API keys. Research has stricter usage limits."}, "servers": [{"url": "/api/v1"}], "paths": {"/filings/batch/": {"post": {"operationId": "batchFilings", "description": "Pull stored correspondence with source text and labeled derived fields. Follow signed cursors with the same filters and filing_ids. Cursors expire after 24 hours. Chunk text with text_offset.", "security": [], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"filters": {"type": "object", "additionalProperties": false, "properties": {"ciks": {"type": "array", "items": {"type": "string"}, "maxItems": 100}, "tickers": {"type": "array", "items": {"type": "string"}, "maxItems": 100}, "forms": {"type": "array", "items": {"type": "string", "enum": ["UPLOAD", "CORRESP"]}, "maxItems": 2, "minItems": 1}, "date_from": {"type": "string", "format": "date"}, "date_to": {"type": "string", "format": "date"}, "topic": {"type": "string", "maxLength": 240}, "sector": {"type": "string", "maxLength": 120}, "sec_letter_division": {"type": "string", "maxLength": 120}, "sec_letter_author": {"type": "string", "maxLength": 120}}}, "filing_ids": {"type": "array", "items": {"type": "integer", "minimum": 1}, "maxItems": 500, "minItems": 1}, "page_size": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}, "text_chars": {"type": "integer", "minimum": 0, "maximum": 100000, "default": 20000}, "text_offset": {"type": "integer", "minimum": 0, "maximum": 10000000, "default": 0}, "cursor": {"type": "string", "maxLength": 4000}}}}}}, "responses": {"200": {"description": "Successful retrieval or explicitly insufficient evidence.", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"type": "object", "properties": {"filing_id": {"type": "integer"}, "company": {"type": "string"}, "ticker": {"type": "string"}, "cik": {"type": "string"}, "accession": {"type": "string"}, "form": {"type": "string"}, "filing_date": {"type": "string", "format": "date"}, "sec_url": {"type": "string"}, "secprobe_url": {"type": "string"}, "text": {"type": "string"}, "text_available": {"type": "boolean"}, "text_characters": {"type": "integer"}, "text_offset": {"type": "integer"}, "text_truncated": {"type": "boolean"}, "next_text_offset": {"type": "integer", "nullable": true}, "text_extracted_at": {"type": "string", "format": "date-time", "nullable": true}, "derived": {"type": "object", "properties": {"ai_summary": {"type": "string"}, "issue_tags": {"type": "array", "items": {"type": "string"}}, "ai_analyzed_at": {"type": "string", "format": "date-time", "nullable": true}}}}}}, "manifest": {"type": "object", "properties": {"matched_filings": {"type": "integer"}, "returned_filings": {"type": "integer"}, "filters": {"type": "object", "additionalProperties": false, "properties": {"ciks": {"type": "array", "items": {"type": "string"}, "maxItems": 100}, "tickers": {"type": "array", "items": {"type": "string"}, "maxItems": 100}, "forms": {"type": "array", "items": {"type": "string", "enum": ["UPLOAD", "CORRESP"]}, "maxItems": 2, "minItems": 1}, "date_from": {"type": "string", "format": "date"}, "date_to": {"type": "string", "format": "date"}, "topic": {"type": "string", "maxLength": 240}, "sector": {"type": "string", "maxLength": 120}, "sec_letter_division": {"type": "string", "maxLength": 120}, "sec_letter_author": {"type": "string", "maxLength": 120}}}, "unmatched_filing_ids": {"type": "array", "items": {"type": "integer"}}, "selection": {"type": "string"}, "page_complete": {"type": "boolean"}, "next_cursor": {"type": "string", "nullable": true}, "text_truncated_count": {"type": "integer"}, "text_missing_count": {"type": "integer"}, "coverage_note": {"type": "string"}}}}, "required": ["results", "manifest"]}}}}, "400": {"description": "Invalid request or cursor.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Self-reported contact blocked by staff."}, "404": {"description": "API disabled.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Method not supported.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Payload exceeds 32 KB.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "JSON content type required.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate or concurrency limit; observe Retry-After.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "API unconfigured, database unavailable, or research provider failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "X-SecProbe-Email", "in": "header", "required": true, "description": "Self-reported personal or business contact. No registration or email verification. Stored for usage administration, not marketing.", "schema": {"type": "string", "format": "email", "maxLength": 254}}, {"name": "X-SecProbe-Agent", "in": "header", "required": true, "description": "Name/version of the calling application or agent; not an authentication credential.", "schema": {"type": "string", "minLength": 2, "maxLength": 200}}]}}, "/research/answer/": {"post": {"operationId": "answerResearchQuestion", "description": "Answer an open-ended SEC correspondence question using sampled evidence. Explicit filters override inferred scope. Assessments include criteria and source quotes; quote checks do not verify entailment.", "security": [], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"question": {"type": "string", "maxLength": 2000}, "filters": {"type": "object", "additionalProperties": false, "properties": {"ciks": {"type": "array", "items": {"type": "string"}, "maxItems": 100}, "tickers": {"type": "array", "items": {"type": "string"}, "maxItems": 100}, "forms": {"type": "array", "items": {"type": "string", "enum": ["UPLOAD", "CORRESP"]}, "maxItems": 2, "minItems": 1}, "date_from": {"type": "string", "format": "date"}, "date_to": {"type": "string", "format": "date"}, "topic": {"type": "string", "maxLength": 240}, "sector": {"type": "string", "maxLength": 120}, "sec_letter_division": {"type": "string", "maxLength": 120}, "sec_letter_author": {"type": "string", "maxLength": 120}}}, "max_documents": {"type": "integer", "minimum": 1, "maximum": 10, "default": 6}}, "required": ["question"]}}}}, "responses": {"200": {"description": "Successful retrieval or explicitly insufficient evidence.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["completed", "insufficient_evidence"]}, "answer": {"type": "string"}, "findings": {"type": "array", "items": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["observation", "assessment", "counterevidence"]}, "text": {"type": "string"}, "basis": {"type": "string"}, "source_ids": {"type": "array", "items": {"type": "integer"}}, "evidence_quote": {"type": "string"}}, "required": ["kind", "text", "basis", "source_ids", "evidence_quote"]}}, "sources": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "integer"}, "company": {"type": "string"}, "ticker": {"type": "string"}, "cik": {"type": "string"}, "adsh": {"type": "string"}, "form": {"type": "string"}, "file_date": {"type": "string", "format": "date"}, "sec_url": {"type": "string"}, "filing_url": {"type": "string"}, "excerpt": {"type": "string"}}}}, "scope": {"type": "object", "properties": {"filters": {"type": "object"}, "coverage": {"type": "object"}, "selection": {"type": "string"}, "exhaustive": {"type": "boolean"}}}, "limitations": {"type": "array", "items": {"type": "string"}}, "validation": {"type": "object", "properties": {"rejected_findings": {"type": "integer"}, "checks": {"type": "array", "items": {"type": "string"}}, "claim_entailment_verified": {"type": "boolean"}}}}, "required": ["status", "answer", "findings", "sources", "scope", "limitations"]}}}}, "400": {"description": "Invalid request or cursor.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Self-reported contact blocked by staff."}, "404": {"description": "API disabled.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Method not supported.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Payload exceeds 32 KB.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "JSON content type required.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate or concurrency limit; observe Retry-After.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "API unconfigured, database unavailable, or research provider failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "parameters": [{"name": "X-SecProbe-Email", "in": "header", "required": true, "description": "Self-reported personal or business contact. No registration or email verification. Stored for usage administration, not marketing.", "schema": {"type": "string", "format": "email", "maxLength": 254}}, {"name": "X-SecProbe-Agent", "in": "header", "required": true, "description": "Name/version of the calling application or agent; not an authentication credential.", "schema": {"type": "string", "minLength": 2, "maxLength": 200}}]}}}, "components": {"schemas": {"Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "details": {"description": "Field validation errors or failure details."}}}}, "required": ["error"]}}}}