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

# Useellis News API: Full Response Schema Reference

> Complete reference for all Useellis 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 Useellis 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](https://docs.useellis.com/api/events.md) and embedded within company responses. It represents a single market event extracted from an SEC filing.

**id** `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](https://docs.useellis.com/api/event-categories.md) 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.

**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 Useellis application UI.

**published\_at** `string`

ISO 8601 timestamp indicating when Useellis 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](#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](https://docs.useellis.com/api/companies.md) 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.

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

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

```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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.