03 / DOCUMENTATION

Small surface. Clear contract.

One discovery request, a company shortlist, and traceable filing evidence.

Service origin: https://etsquare.ai. Use Authorization: Bearer YOUR_SEV_API_KEY for REST/MCP. Create and revoke keys in Account. View your discovery allowance in Account. A successful empty response counts; failures do not. Passage reads consume no discovery unit and are rate-limited. Optional Idempotency-Key identifies an attempt: duplicates return 409 without starting another search; responses are not replayed. Do not retry automatically.

01Request fields

POST /v1/sec/discover-companies

FIELD	TYPE	BEHAVIOR
question	string · required	Nonempty research question; maximum 4,000 characters.
tickers	string[] · optional	Up to 50 tickers. Alternative to sic_codes.
sic_codes	string[] · optional	Up to 50 four-digit SIC codes. Preserve leading zeroes. Alternative to tickers.
filed_since	string · optional	Inclusive SEC filing-date cutoff, YYYY-MM-DD. Playground starts with a visible, editable 15-month window; clear it for all indexed history. API/MCP add no hidden default.
max_companies	integer · optional	1–50 companies; defaults to 10.

Explicit filters are authoritative and never relaxed. Unknown fields, invalid dates, unresolved scope and conflicting ticker/SIC lists produce errors. Numerical conditions in a question are research signals, not validated financial screens.

02Response structure

Companies are grouped by CIK, with one to three original SEC passage references each. Previews are optional exact excerpts, up to 450 characters. Fewer companies, including zero, are valid.

STRUCTURE ONLY / NOT A SEARCH RESULT

{
  "status": "ok",
  "question": "Your research question",
  "effective_filters": {
    "tickers": [],
    "sic_codes": [],
    "filed_since": null
  },
  "companies": [],
  "data_freshness": {},
  "limitations": []
}

Company: rank · company_name · ticker · cik · passages
Passage: passage_id · accession_number · form · filing_date · section · source_url · preview · preview_char_start/end · context_url · resource_uri

Inspect a source-checked saved response in Playground ↗

03Source retrieval

Use GET /v1/sec/passages/{passage_id}, or MCP tool get_sec_passage with the returned passage_id, to retrieve the full original passage and available adjacent passages from the same filing section. The response includes text, chunk_index and adjacent_passages. Open source_url for the original SEC filing.

Preview offsets count Unicode characters in the original passage. Saved examples include only their explicitly stored context; missing saved context is labelled. Reading live context does not restart discovery.

04Limits & errors

A failed request is an error, not an empty result. There is no completeness or fixed-latency guarantee. The console never retries discovery automatically. A request that succeeds on the server can use allowance even if you stop waiting or lose the connection.

For API examples and MCP availability, see Build.

HTTP	EXAMPLES	NEXT STEP
400	invalid_passage_id, unresolved_filter, ambiguous_ticker	Review the supplied scope or reference.
401	authentication_required, authentication_failed	Sign in or replace the expired/revoked API key.
403 / 409	agreement_required, interactive_signin_required, request_already_recorded	Use Account for setup; a reused Idempotency-Key never starts another discovery.
429	allowance_exhausted, anonymous_allowance_exhausted, rate_limited	Sign in, check your allowance, or wait for the rate window.
404	passage_not_found	Use the original SEC filing link.
413	request_too_large	Keep the JSON request within 32 KiB.
422	invalid_request	Correct the question or field values.
504	request_timeout	Retry deliberately or refine the question.
502 / 503	Upstream error, service_busy, live_unavailable	Try again when the service is available.

ERROR ENVELOPE / ILLUSTRATIVE

{"status":"error","error":{"code":"request_timeout","message":"The discovery time budget was exhausted."}}

05Coverage & freshness

The initial corpus policy is each supported issuer’s latest original 10-K and original 10-Qs filed afterward. 8-Ks, amendments, and broader history are outside that refresh policy. Coverage must be verified from completed, indexed filings; a refresh plan is not loaded coverage.

SEV searches its supported indexed SEC corpus. The response separates catalog_latest_filing_date (the prepared inventory) from latest_returned_filing_date (the newest source in this shortlist). The older latest_filing_date_reported field remains an alias for the catalog date. Catalog timestamps are snapshot metadata, not a claim of complete or current market coverage. A shortlist can omit relevant companies. Historical disclosures provide research leads rather than proof of a new event's economic impact.