# Finance news (SBX-FNEWS)

Financial news from official sources: the Fed, the ECB, US companies' 8-K filings and Türkiye's Official Gazette, summarised by AI in Turkish and English with tags and importance.

Version: v1.0

## Authentication

Send your API key on every request, either as a Bearer token or as the `apikey` query parameter:

```
Authorization: Bearer <YOUR_API_KEY>
https://api.servicebox.io/v1/finance-news/...?apikey=<YOUR_API_KEY>
```

Get a key: sign up at https://servicebox.io/en/signup and create one on the dashboard. An agent can sign up itself with `POST https://api.servicebox.io/v1/accounts` and `{"email": "...", "apis": ["finance-news"]}`: the owner of the mailbox approves by email and the agent collects a short-lived key by polling the returned `poll_url`.

## Base URL

`https://api.servicebox.io`

## Endpoints

### GET /v1/finance-news/articles

**List articles**

Summarised news items, newest first: each official document (a Fed or ECB release, a listed US company's 8-K, a Resmî Gazete text) with a headline and 2–4 sentence summary in Turkish and English written by AI from that document only, its category, tags, companies, countries, sentiment and importance, and the link to the original. Filters combine; list filters match any of their values.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `source` | query | string | no | Comma-separated source ids from /finance-news/sources. |
| `category` | query | string (`monetary-policy`, `macro-data`, `regulation`, `banking`, `capital-markets`, `corporate`, `earnings`, `m-and-a`, `management`, `debt`, `fiscal`, `trade`, `energy`, `other`) | no | One category. |
| `tag` | query | string | no | Comma-separated tags, e.g. interest-rates,dividend. |
| `ticker` | query | string | no | Comma-separated US tickers (8-K filers), e.g. AAPL,MSFT. |
| `country` | query | string | no | Comma-separated ISO 3166-1 alpha-2 codes. |
| `minImportance` | query | integer | no | 1–5. |
| `sentiment` | query | string (`positive`, `negative`, `neutral`, `mixed`) | no | positive, negative, neutral or mixed. |
| `confident` | query | boolean | no | true or false. |
| `since` | query | string | no | YYYY-MM-DD or an ISO 8601 UTC time. |
| `until` | query | string | no | YYYY-MM-DD or an ISO 8601 UTC time. |
| `limit` | query | integer | no | Items per page, 1–200. |
| `cursor` | query | string | no | The `next_cursor` of the previous page, with the same filters. |

**Example**

```bash
curl "https://api.servicebox.io/v1/finance-news/articles" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/finance-news/articles/{id}

**Get an article**

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

**Example**

```bash
curl "https://api.servicebox.io/v1/finance-news/articles/<id>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/finance-news/sources

**List sources**

The sources, their licence, and how many summarised articles each has. Free.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/finance-news/sources" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Errors

Errors are RFC 9457 `application/problem+json` bodies with a machine-readable `type`.

- `401` — the key is missing, unknown, expired or revoked.
- `402` — not enough credits: the body carries `credits_required` and `upgrade_url` (https://servicebox.io/en/pricing).
- `403` — the key is not allowed to call this API.
- `429` — rate limited: wait `retry_after` seconds (also sent as the `Retry-After` header); `upgrade_url` points to a larger plan.

## Links

- OpenAPI document: https://api.servicebox.io/v1/finance-news/openapi.json
- Pricing: https://servicebox.io/en/pricing?api=SBX-FNEWS
- API page: https://servicebox.io/en/apis/finance-news