SECPROBE · RESEARCH API v1
Research API documentation
Retrieve evidence packages in batches and ask questions that require judgment about SEC correspondence.
Filing pulls are enabled. Paid research answers are enabled. Both endpoints are publicly available with email and agent identification headers.
OpenAPI 3.0 JSON specification · Back to SecProbe
Access
Privacy notice · Usage terms · Support
Base URL: https://secprobe.io/api/v1/. Both endpoints need no signup, API key, or email verification. Send JSON with both identification headers:
X-SecProbe-Email: researcher@example.com X-SecProbe-Agent: MyResearchAgent/1.0 Content-Type: application/json
Use a personal or business contact email and identify your agent or application. These values are self-reported, not verified identity. SecProbe stores contact and agent details, request/rejection totals, and opaque network identifiers for usage administration. Individual request logs include applied filters, status, duration, and response sizes; they exclude API keys, document bodies, and research question text. Request logs older than 30 days are removed in bounded batches during traffic. Supplying an address does not subscribe it to marketing.
Use the same email and agent headers for research answers. Leave Postman Authorization set to No Auth. Both endpoints have independent operator shutdown switches; server-side model credentials are managed by SecProbe.
Connect SecProbe to ChatGPT or another MCP client
Remote MCP server URL: https://secprobe.io/mcp. Transport: Streamable HTTP. Authentication: None. The endpoint supports JSON responses and does not hold sessions or provide an SSE subscription stream.
In ChatGPT's custom MCP connection flow, use the server URL above and select no authentication. Client features and directory access depend on your account and workspace. The tools are batch_filings and research_answer.
Each tool accepts contact_email explicitly supplied by the user and an optional agent name (default: SecProbe MCP client). The MCP adapter maps these to the same identification, quotas, and administrator logs used by REST requests. Do not invent a contact email. Connection initialization and tool discovery do not require contact information.
MCP filing pulls default to five records and 2,000 characters per record, with maxima of ten records and 4,000 characters to keep model context bounded. Use continuation cursors or text offsets for larger pulls. Research retains its normal limits. Tool failures include isError; quota failures include retry_after_seconds.
{
"type": "mcp",
"server_label": "secprobe",
"server_url": "https://secprobe.io/mcp",
"allowed_tools": ["batch_filings", "research_answer"],
"require_approval": "always"
}
This configuration can be included in an OpenAI Responses API request's tools array. Provide the user's explicitly supplied contact in the request context so the model can populate the tool argument. Account integration and public directory approval are separate from endpoint availability.
1. Batch filing retrieval
POST /api/v1/filings/batch/
Returns stored SEC comment letters (UPLOAD) and company responses (CORRESP), extracted text, citation links, and clearly labeled derived summaries and tags. It does not initiate SEC ingestion or new model analysis.
{
"filters": {
"tickers": ["NVDA", "AMD"],
"date_from": "2024-01-01",
"date_to": "2026-10-31",
"topic": "revenue recognition"
},
"page_size": 20,
"text_chars": 20000
}
| Parameter | Behavior |
|---|---|
filters | Optional scope; omitted means all stored correspondence. See shared filters below. |
filing_ids | Optional list of 1–500 positive SecProbe filing IDs. Intersects with filters. Unmatched IDs appear in the manifest. |
page_size | 1–50 records; default 20. Ordered by increasing filing ID, not relevance. |
text_chars | 0–100,000 characters per document; default 20,000. Zero retrieves metadata only. |
text_offset | Character offset into extracted text; default zero, maximum 10,000,000. |
cursor | Signed continuation token; expires after 24 hours. Repeat the same filters and filing_ids. |
Completing a batch
Read manifest.next_cursor and repeat the request with that cursor until it is null. matched_filings counts all stored matches within the continuation boundary; returned_filings counts this page. page_complete means no further filing pages remain, not that all document text was returned.
Each record includes filing_id, CIK, accession, company, ticker, form, filing date, original SEC URL, SecProbe URL, text and extraction timestamp. derived contains existing AI summary, issue tags, and analysis timestamp. Summaries are capped at 8,000 characters and may be absent or stale.
Inspect text_available, text_characters, text_truncated, and next_text_offset. To retrieve remaining text, request that single filing_id with its next offset. A null next offset means no more text after this chunk; a nonzero offset still means the response is a partial document.
Cursors exclude newly inserted filings; updates or deletions can affect later pages. This is not an immutable database snapshot. The manifest reports missing text and IDs; absent data never proves no SEC correspondence exists.
2. Evidence-backed answers
POST /api/v1/research/answer/
{
"question": "Which revenue disclosure concerns appear most significant, and why?",
"filters": {
"tickers": ["NVDA", "AMD"],
"date_from": "2024-01-01",
"topic": "revenue recognition"
},
"max_documents": 6
}
question is required (1–2,000 characters). Optional filters override inferred scope; explicit company identifiers replace inferred companies. Research accepts up to four companies. max_documents is 1–10, default six, further bounded by the operator's research limit.
Without explicit filters, SecProbe infers scope from the question. Inspect scope.filters before relying on the answer. Supplying a topic explicitly gives you control over retrieval terms.
| Response | Meaning |
|---|---|
status | completed or insufficient_evidence. Both use HTTP 200; insufficient evidence is not a substantive answer. |
answer | Readable synthesis of accepted findings. |
findings[] | Each has kind (observation, assessment, counterevidence), text, basis, source_ids, and evidence_quote. Assessments require stated criteria and reasoning. |
sources[] | Retrieved excerpts with IDs, company metadata, dates, and database-derived citation links. Match finding source_ids to source id. |
scope | Applied filters, coverage counts, dates of selected evidence, and a non-exhaustive sampling declaration. Coverage counts precede topic filtering. |
validation | Rejected finding count and applied checks. Present for completed answers. |
limitations | Explicit constraints on coverage and interpretation. |
Every accepted finding cites a retrieved source and contains a 20–300 character quote found in a cited excerpt (whitespace and case normalized). These checks verify source references and quote presence; they do not prove that the source supports the entire conclusion. SEC questions are not confirmed violations. Related letters and responses are not automatically treated as a resolved review thread.
Research uses paid model calls, bounded evidence selection, and temporary answer caching. It does not provide exhaustive analysis of all matching filings. Counterevidence is returned when supported, not guaranteed in every response.
Shared filters
| Field | Meaning |
|---|---|
ciks / tickers | Choose one list. CIKs accept 1–10 digits and normalize to ten digits; tickers normalize to uppercase. Batch accepts up to 100, research up to four. |
forms | Nonempty list of UPLOAD and/or CORRESP; both by default. |
date_from / date_to | Inclusive filing dates in YYYY-MM-DD format. |
topic | Full-text query against extracted text, up to 240 characters. Production PostgreSQL uses English web-search syntax. Batch local SQLite uses phrase substring matching; research local SQLite uses token matching. |
sector | Exact, case-insensitive active company classification name, up to 120 characters. |
sec_letter_division / sec_letter_author | Case-insensitive substring matching, up to 120 characters. |
Errors and limits
Errors use {"error":{"code":"…","details":…}}. Unknown request fields are rejected. Use JSON bodies up to 32 KB. Pull limits: 30/minute and 1,000/day per email; 60/minute and 2,000/day per network address; six identical requests/minute per email or address; two active pulls per address. Windows are fixed UTC intervals. Limits may be operator-adjusted. Rotating agent names or contact emails does not reset network limits.
Daily text capacity is reserved before retrieval: page_size × text_chars, up to 20 million characters per email and 40 million per address. Reservations count even if a query returns fewer records, fails, or finds no matches. Set text_chars to zero for metadata-only pulls. Requests are also counted when later validation or another allowance fails.
Honor Retry-After on HTTP 429. Continue through cursors rather than polling the same page repeatedly. Research allows six requests/minute and 50/day per email by default; network limits are twice the per-email limits. A global daily allowance of 200 research requests bounds model-call volume. These allowances count attempts, including cached answers and requests that later fail. Research shares concurrency with the website assistant.
400 invalid input/cursor; 403 contact blocked; 404 disabled API; 405 unsupported method; 413 oversized body; 415 unsupported content type; 429 capacity/quota; 503 configuration, database, or research-provider failure. Narrow expensive queries before retrying.
Requests are synchronous: consume filing pages for large pulls. There are no asynchronous export jobs or comparison endpoint in this release.