> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insighthread.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Insighthread News API: Full Response Schema Reference

> Complete reference for all Insighthread News API response objects including the Event object, Impact object, Company object, and error response format.

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](/api/events) and embedded within company responses. It represents a single market event extracted from an SEC filing.

<ResponseField name="id" type="string">
  Unique identifier for this event. Stable across requests — the same event always returns the same `id`. Example: `evt_8k103_iobt_mar31`.
</ResponseField>

<ResponseField name="ticker" type="string">
  Ticker symbol of the company associated with this event. Always uppercase. Example: `NVDA`.
</ResponseField>

<ResponseField name="event_type" type="string">
  Category of the event. One of 35+ possible string values. See the [Event Categories](/api/event-categories) reference for the complete enumeration. Example: `Bankruptcy/Liquidation`.
</ResponseField>

<ResponseField name="headline" type="string">
  Short, one-sentence headline summarizing the event. Written in plain English. Example: `"IO Biotech files Chapter 7, ceases all operations"`.
</ResponseField>

<ResponseField name="summary" type="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.
</ResponseField>

<ResponseField name="primary_filing" type="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.
</ResponseField>

<ResponseField name="secondary_filing" type="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.
</ResponseField>

<ResponseField name="filing_url" type="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`.
</ResponseField>

<ResponseField name="impact" type="object">
  The impact signal for this event. Contains a numerical score, directional assessment, human-readable label, and bar count.

  <Expandable title="Impact object fields">
    <ResponseField name="impact.score" type="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    |
    </ResponseField>

    <ResponseField name="impact.direction" type="string">
      The directional assessment of the event's likely market impact. One of: `positive`, `negative`, `neutral`.
    </ResponseField>

    <ResponseField name="impact.label" type="string">
      Human-readable severity label corresponding to `score`. One of: `Minor`, `Moderate`, `Significant`, `Major`, `Critical`.
    </ResponseField>

    <ResponseField name="impact.bars" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="published_at" type="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`.
</ResponseField>

## Impact Object

The Impact object appears nested inside every Event object. Refer to the [Event Object](#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](/api/companies) endpoints.

<ResponseField name="ticker" type="string">
  The company's ticker symbol as listed on its primary stock exchange. Always uppercase.
</ResponseField>

<ResponseField name="name" type="string">
  Full legal name of the company. Example: `NVIDIA Corporation`.
</ResponseField>

<ResponseField name="exchange" type="string">
  The primary exchange on which the company's equity is listed. Common values: `NYSE`, `NASDAQ`, `AMEX`.
</ResponseField>

<ResponseField name="sector" type="string">
  Industry sector classification. Example: `Technology`, `Healthcare`, `Energy`, `Financials`.
</ResponseField>

<ResponseField name="description" type="string">
  Short prose description of the company's primary business operations.
</ResponseField>

## 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.

```json theme={null}
{
  "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.        |

<Warning>
  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.
</Warning>

## Pagination

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

<ResponseField name="data" type="array">
  Array of result objects (Event or Company). May be empty if no records match the query.
</ResponseField>

<ResponseField name="next_cursor" type="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.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of records matching the query across all pages, when available. May be omitted from some responses.
</ResponseField>

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:

```json theme={null}
{
  // 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"
}
```


## Related topics

- [Insighthread News API: All Event Categories Reference](/api/event-categories.md)
- [Insighthread News API: Real-Time SEC Event Intelligence](/api/overview.md)
- [API Authentication — Insighthread News API Bearer Tokens](/api/authentication.md)
- [GET /events — Retrieve Real-Time SEC Market Events](/api/events.md)
- [GET /companies — List and Look Up Covered Companies](/api/companies.md)