Insighthread News API: Full Response Schema Reference

This page documents all response object schemas returned by the Insighthread News API. Use this reference when building your integration, writing deserialization logic, or validating the shape of API responses in your test suite. Every field is described with its type, nullability, and expected values.

Event Object

The Event object is the primary data structure returned by GET /events and embedded within company responses. It represents a single market event extracted from an SEC filing.

string

Unique identifier for this event. Stable across requests — the same event always returns the same id. Example: evt_8k103_iobt_mar31.

ticker

string

Ticker symbol of the company associated with this event. Always uppercase. Example: NVDA.

event_type

string

Category of the event. One of 35+ possible string values. See the Event Categories reference for the complete enumeration. Example: Bankruptcy/Liquidation.

headline

string

Short, one-sentence headline summarizing the event. Written in plain English. Example: "IO Biotech files Chapter 7, ceases all operations".

summary

string

AI-generated summary of the event, typically 1–3 sentences in length. Grounded in the content of the originating SEC filing. Suitable for display in financial news feeds, research dashboards, or LLM context windows.

primary_filing

string

The primary SEC form type and item section that triggered this event. Example: 8-K (1.03), 10-Q, Form 4. Use this to direct users to the correct section of the underlying filing.

secondary_filing

string | null

A secondary SEC filing associated with the same event, where applicable. Example: 15-12B. Returns null when there is no associated secondary filing.

filing_url

string

Full URL to the original filing on SEC EDGAR. Use this field to provide a direct citation link. Example: https://sec.gov/Archives/edgar/data/1834585/000183458526000008/0001834585-26-000008-index.htm.

impact

object

The impact signal for this event. Contains a numerical score, directional assessment, human-readable label, and bar count.

Show Impact object fields

impact.score

integer

Numerical impact score from 1 to 5. Maps to the following severity levels:

Score	Label
1	Minor
2	Moderate
3	Significant
4	Major
5	Critical

impact.direction

string

The directional assessment of the event’s likely market impact. One of: positive, negative, neutral.

impact.label

string

Human-readable severity label corresponding to score. One of: Minor, Moderate, Significant, Major, Critical.

impact.bars

integer

Visual bar count from 1 to 5. Numerically identical to score. Maps directly to the 5-bar impact indicator displayed in the Insighthread application UI.

published_at

string

ISO 8601 timestamp indicating when Insighthread published this event. Delivery is within 90 seconds of the SEC filing being accepted on EDGAR. Example: 2026-03-31T14:22:08Z.

Impact Object

The Impact object appears nested inside every Event object. Refer to the Event Object section above for the full field-level documentation with score-to-label mapping.

Company Object

The Company object is returned by the GET /companies endpoints.

ticker

string

The company’s ticker symbol as listed on its primary stock exchange. Always uppercase.

name

string

Full legal name of the company. Example: NVIDIA Corporation.

exchange

string

The primary exchange on which the company’s equity is listed. Common values: NYSE, NASDAQ, AMEX.

sector

string

Industry sector classification. Example: Technology, Healthcare, Energy, Financials.

description

string

Short prose description of the company’s primary business operations.

Error Responses

When the API cannot fulfill a request, it returns an appropriate HTTP status code and a JSON body with machine-readable error details. The error body always contains at least an error field.

{
  "error": "unauthorized",
  "message": "API key is missing or invalid. Pass your key in the Authorization header as a Bearer token.",
  "request_id": "req_01J9XKTZM8P3WNFQ4R7V"
}

HTTP Status	Error Code	Description
`400`	`bad_request`	One or more query parameters are invalid, malformed, or out of range. Check the `message` field for details.
`401`	`unauthorized`	The `Authorization` header is missing or the API key is not valid.
`403`	`forbidden`	The API key is valid but does not have permission to access the requested resource. Contact your account manager.
`404`	`not_found`	The requested resource (e.g., a specific ticker on `/companies/{ticker}`) was not found.
`429`	`rate_limit_exceeded`	Your API key has exceeded its rate limit. Implement exponential backoff and retry after the `Retry-After` header value (in seconds).
`500`	`internal_error`	An unexpected server-side error occurred. Retry the request with exponential backoff. If the issue persists, contact support.

Always check the HTTP status code before parsing the response body. A 200 response guarantees a valid data payload, but any 4xx or 5xx response may return an error body instead of the expected schema.

Pagination

All list endpoints (/events, /companies) use cursor-based pagination with a consistent response envelope. The full envelope structure is:

data

array

Array of result objects (Event or Company). May be empty if no records match the query.

next_cursor

string | null

Opaque string cursor pointing to the next page of results. Pass this as the cursor query parameter on the next request. Returns null when the current page is the last page.

total

integer

Total number of records matching the query across all pages, when available. May be omitted from some responses.

Cursors are deterministic for a given query — the same cursor value against the same filter parameters always returns the same next page.

Annotated Full Event Response

The following is a complete, annotated example of a single event response as returned inside the data array:

{
  // Unique stable event identifier
  "id": "evt_8k103_iobt_mar31",

  // Company ticker symbol
  "ticker": "IOBT",

  // One of 35+ structured event categories
  "event_type": "Bankruptcy/Liquidation",

  // One-sentence headline
  "headline": "IO Biotech files Chapter 7, ceases all operations",

  // AI-generated 1-3 sentence summary grounded in the filing
  "summary": "IO Biotech has filed for Chapter 7 bankruptcy protection and will cease all operations immediately. The company's assets are to be liquidated under the supervision of a court-appointed trustee following the failure of its lead oncology program.",

  // Primary SEC form type and item section
  "primary_filing": "8-K (1.03)",

  // Secondary filing, or null if none
  "secondary_filing": "15-12B",

  // Direct link to the original EDGAR filing
  "filing_url": "https://sec.gov/Archives/edgar/data/1834585/000183458526000008/0001834585-26-000008-index.htm",

  // 5-bar impact signal
  "impact": {
    "score": 5,          // 1 (Minor) through 5 (Critical)
    "direction": "negative",  // positive | negative | neutral
    "label": "Critical",      // human-readable severity
    "bars": 5             // maps to UI bar display, same as score
  },

  // ISO 8601 publish timestamp — within 90s of EDGAR filing
  "published_at": "2026-03-31T14:22:08Z"
}

​Event Object

​Impact Object

​Company Object

​Error Responses

​Pagination

​Annotated Full Event Response

Event Object

Impact Object

Company Object

Error Responses

Pagination

Annotated Full Event Response