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

# News & analyst notes

> Company and market news with sentiment, entities, and event lineage, plus analyst notes.

News articles and analyst notes are *grounded artifacts*: David generates them from the structured records of the scenario, so the numbers in the text match the numbers in the data, and each carries lineage back to the event that produced it. News is point-in-time, only articles visible by date are returned.

## Company & market news

```http theme={null}
GET /news
```

Returns company news (`news_article`) and market news (`market_news_article`). With no `ticker`, both are returned. With a `ticker`, only that company's news is returned by default — set `include_market=true` to fold scenario-level market headlines into the same call.

| Parameter                 | Type    | Required | Default | Description                                                                                                                      |
| ------------------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `scenario_id`             | string  | Yes      | -       | The world to read from.                                                                                                          |
| `ticker`                  | string  | No       | all     | Restrict to one ticker.                                                                                                          |
| `as_of`                   | date    | No       | -       | Point-in-time cutoff, only articles visible on or before this date.                                                              |
| `start_date` / `end_date` | date    | No       | -       | Inclusive window.                                                                                                                |
| `market_only`             | boolean | No       | false   | Return only market/macro news (no per-company articles). Overrides `ticker`.                                                     |
| `include_market`          | boolean | No       | false   | When a `ticker` is set, also include scenario-level market news. No effect without a `ticker` (market news is already included). |
| `limit`                   | integer | No       | 100     | Page size (max 500).                                                                                                             |
| `offset`                  | integer | No       | 0       | Pagination offset.                                                                                                               |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/news?scenario_id=<id>&ticker=AAPL&as_of=2026-03-20" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.news.list(scenario_id="<id>", ticker="AAPL", as_of="2026-03-20")
  ```
</CodeGroup>

```json theme={null}
{
  "news": [
    {
      "artifact_id": "news_...",
      "ticker": "AAPL",
      "artifact_type": "news_article",
      "title": "Apple beats on revenue, trims full-year guidance",
      "source": "Market Wire",
      "author": "staff",
      "date": "2026-03-18",
      "visible_from": "2026-03-18",
      "url": "https://.../",
      "summary": "Apple reported revenue above consensus ...",
      "sentiment": "mixed",
      "entities": ["AAPL"],
      "mentioned_tickers": ["AAPL"],
      "mentioned_metrics": ["revenue", "eps", "guidance"],
      "source_event_id": "evt_...",
      "event_lineage": { "...": "..." },
      "article_format": "earnings_recap"
    }
  ]
}
```

## News article detail

```http theme={null}
GET /news/{artifact_id}
```

Returns a single article with the full multi-paragraph `text` and validation metadata.

| Parameter     | Type   | Required | Description                      |
| ------------- | ------ | -------- | -------------------------------- |
| `scenario_id` | string | Yes      | The world to read from.          |
| `artifact_id` | string | No       | The article id (path parameter). |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/news/news_abc123?scenario_id=<id>" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.news.get("news_abc123", scenario_id="<id>")
  ```
</CodeGroup>

```json theme={null}
{ "news_article": { "artifact_id": "news_abc123", "text": "Apple today reported ...", "validation": { "...": "..." } } }
```

Returns `404` if the id is not a news article.

## Analyst notes

```http theme={null}
GET /analyst-notes
```

Full-text sell-side notes (`analyst_note`), including the body text.

| Parameter                 | Type    | Required | Default | Description             |
| ------------------------- | ------- | -------- | ------- | ----------------------- |
| `scenario_id`             | string  | Yes      | -       | The world to read from. |
| `ticker`                  | string  | No       | all     | Restrict to one ticker. |
| `as_of`                   | date    | No       | -       | Point-in-time cutoff.   |
| `start_date` / `end_date` | date    | No       | -       | Inclusive window.       |
| `limit`                   | integer | No       | 10      | Page size (max 500).    |
| `offset`                  | integer | No       | 0       | Pagination offset.      |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/analyst-notes?scenario_id=<id>&ticker=AAPL&as_of=2026-03-20" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.analyst.notes(scenario_id="<id>", ticker="AAPL", as_of="2026-03-20")
  ```
</CodeGroup>

```json theme={null}
{ "analyst_notes": [ { "artifact_id": "note_...", "ticker": "AAPL", "title": "Reiterate Overweight", "text": "...", "sentiment": "positive" } ] }
```

<Info>
  Every artifact carries a `date` and a `visible_from` timestamp. Passing `as_of` enforces point-in-time visibility so future articles never leak into an agent's information set. See [Date semantics](/concepts/date-semantics).
</Info>