# REST API overview

A small, predictable JSON API over HTTPS.

## Base URL

```
https://api.marketnewsapi.com/v1
```

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | [/news](/docs/news) | Search and filter stock news, press releases and legal notices, newest first. |
| GET | [/news/{id}](/docs/article) | Fetch one article by id, including the latest enrichment. |
| GET | [/trending](/docs/trending) | The stock tickers with the most coverage right now. |
| GET | [/sources](/docs/sources) | Every publisher and wire service in the feed, with 30-day volume. |
| GET | [/tickers](/docs/tickers) | Every ticker tagged on at least one article. |
| GET | [/usage](/docs/usage) | Your plan, today's request count and WebSocket allowance. |
| GET | [/status](/docs/status-endpoint) | Public health check with the latest ingestion time per category. No API key needed. |

## Conventions

- Only `GET` requests. Parameters go in the query string.
- Lists of values are comma-separated: `tickers=AAPL,MSFT`.
- Timestamps are ISO 8601 in UTC with a `Z` suffix.
- Responses are gzip-compressed if you send `Accept-Encoding: gzip`.
- CORS is enabled, but don't expose your key in browsers. See [keeping keys safe](/docs/authentication#security).

## Response envelope

```json
{
 "data": [
 "..."
 ],
 "meta": {
 "count": 20,
 "next_cursor": "eyJ0Ijo...",
 "plan": "pro",
 "delayed_minutes": 0
 }
}
```

`meta.notice` appears when we adjusted your request, for example when the Free plan's history window was applied.

## Versioning

The API is versioned in the path (`/v1`). Within v1 we only make additive changes: new endpoints, parameters and fields. Breaking changes would ship as `/v2` with at least 6 months' notice. Changes are listed in the [changelog](/changelog).