# Endpoints

Read what bullpen.news publishes: stories, X posts, videos and investor letters about listed companies, and its daily recap. Every endpoint is GET, and limit goes up to 100. New fields and enum values may appear; ignore the ones you don't use.

## [Search companies and letters](/docs/reference/search)

`GET /v1/search`
Find companies by ticker or name, and the investor letters that match the same query. Use it when you aren't sure of a company's ticker. Any other parameter is refused.

## [Front page](/docs/reference/latest)

`GET /v1/latest`
What bullpen.news shows on its front page now, or on a past day: stories and videos, X posts, and investor letters, each list in the page's order. sector narrows the stories and X posts by their topic tags; it doesn't narrow letters. mincap and maxcap narrow all three by the market cap of the companies they're about. Any other parameter is refused.

## [Company](/docs/reference/companies)

`GET /v1/companies/{ticker}`
Everything bullpen.news has on one company, by its ticker: its sector and market cap, the stories and X posts that mention it, and the investor letters that discuss it. days narrows the stories and X posts to the last N days, today included; it doesn't narrow letters. Any other parameter is refused.

## [Investor letters](/docs/reference/letters)

`GET /v1/letters`
Investor letters (fund and partnership letters) bullpen.news has read, newest first: all of them, only those that discuss a ticker, or only one firm's. Any other parameter is refused.

## [Daily recap](/docs/reference/recap)

`GET /v1/recap`
The daily recap email for a day, in full: every story, X post, video and investor letter it listed, by section. Without day, the newest recap, ordinarily yesterday's. Any other parameter is refused.

## [Result detail](/docs/reference/items)

`GET /v1/items/{id}`
Full detail for one result, by the id another endpoint returned: story:, x:, video: or letter:. A letter names every company it mentions, where lists name only the ones it is mainly about. Any other parameter is refused.

## [Firms](/docs/reference/firms)

`GET /v1/firms`
Every firm with an investor letter on bullpen.news, by name, for the letters endpoint's firm. It takes no parameters, and refuses any.

## [Feed](/docs/reference/feed)

`GET /v1/feed`
What went live on bullpen.news, oldest first: stories, X posts, videos and investor letters in one list. Poll it with the last nextCursor. It runs two minutes behind. Any other parameter is refused.

## `Story`

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Its id, such as story:123. |
| `kind` | `story` |  |
| `title` | string |  |
| `summary` | string or null | Our summary. Null until we have written one. |
| `source` | string | The publication. |
| `author` | string | The writer, when the publication names one. |
| `published` | string (date-time) | When it was published, in UTC. |
| `wentLive` | string (date-time) or null | When it went live on bullpen.news, in UTC. |
| `url` | string | The story at its publisher. |
| `companies` | array of string | The companies it is about, by ticker. tickers says what each one is. |

## `XPost`

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Its id, such as x:456. |
| `kind` | `x_post` |  |
| `postId` | string | The post's id on X. |
| `url` | string | The post on X. |
| `published` | string (date-time) | When it was published, in UTC. |
| `wentLive` | string (date-time) or null | When it went live on bullpen.news, in UTC. |
| `companies` | array of string | The companies it is about, by ticker. tickers says what each one is. |

## `Video`

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Its id, such as video:789. |
| `kind` | `video` |  |
| `url` | string | The video on YouTube. |
| `published` | string (date-time) | When it was published, in UTC. |
| `wentLive` | string (date-time) or null | When it went live on bullpen.news, in UTC. |
| `companies` | array of string | The companies it is about, by ticker. tickers says what each one is. |

## `Letter`

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Its id, such as letter:532. |
| `kind` | `letter` |  |
| `title` | string |  |
| `firm` | string | The firm that wrote it. |
| `period` | string or null | The period it covers, such as Q2 2026. |
| `published` | string (date-time) | When it was published, in UTC. |
| `wentLive` | string (date-time) or null | When it went live on bullpen.news, in UTC. |
| `summary` | string or null | Our summary. Null until we have written one. |
| `url` | string | The letter itself. |
| `companies` | array of string | The companies it is about, by ticker. tickers says what each one is. |

## `TickerEntry`

| Field | Type | Description |
| --- | --- | --- |
| `name` | string |  |
| `sector` | string or null | Its GICS sector, such as Technology. Null when we don't know it. |
| `marketCapUsd` | integer or null | Its market cap in whole US dollars. Null when we don't know it. |
| `bullpenUrl` | string | Its page on bullpen.news. |