apitube-news-api

Files (1)

• SKILL.md

SKILL.md (first lines)

# APITube News API

APITube is a worldwide News API. Use it to search and filter news articles in real time
or historically, then read structured fields (title, body, source, sentiment, entities).

- Base URL: `https://api.apitube.io/v1`
- Full docs: https://docs.apitube.io/
- OpenAPI spec: https://api-reference.apitube.io/openapi.json
- Get an API key: https://apitube.io/

## Authentication

Read the key from the environment variable `APITUBE_API_KEY` and reference it as `$APITUBE_API_KEY`.
Never write the key itself into a command, a file or a code sample: a literal key ends up in shell
history, logs and version control. If the variable is unset, ask the user to export it — do not ask
them to paste the key into the chat.

```bash
# 1. Authorization header (most secure)
curl -H "Authorization: Bearer $APITUBE_API_KEY" \
  "https://api.apitube.io/v1/news/everything?per_page=10"

# 2. X-API-Key header
curl -H "X-API-Key: $APITUBE_API_KEY" \
  "https://api.apitube.io/v1/news/everything?per_page=10"

# 3. Query parameter — accepted, but it leaks the key into server logs,
#    browser history and referrer headers. Use a header instead.
curl "https://api.apitube.io/v1/news/everything?per_page=10&api_key=$APITUBE_API_KEY"
```

Keys prefixed `api_test_` run against the same data and do not consume quota, so use one while
wiring up an integration. Only `body` and `body_html` are truncated, and the cut is marked with
`[Test mode — use a live key for full content]`; title, description, entities, sentiment,
categories and source come through in full. The Free plan truncates the same two fields, with
the marker `[Upgrade subscription plan]`. Check for those strings to detect a truncated body
instead of guessing from its length.
See https://docs.apitube.io/platform/news-api/authentication.

## Endpoints

| Endpoint | Methods | Purpose |
|----------|---------|---------|
| `/news/everything` | GET · POST | Search all articles with full filtering |
| `/news/top-headlines` | GET · POST | Breaking and important news from sources with OPR rank >= 5 |
| `/news/count` | GET · POST | Number of matching articles only — one `count(*)`, no article payload |
| `/news/article` | GET · POST | A single article — pass `id=<articleId>`, not `article.id` (`400 ER0232` without it) |
| `/news/story/{articleId}` | GET · POST | The cluster of articles covering the same story |
| `/news/category/{taxonomy}/{categoryId}` · `/news/topic/{topicId}` · `/news/industry/{industryId}` · `/news/entity/{entityId}` | GET · POST | Articles by taxonomy |
| `/news/trends` | GET · POST | Aggregations: top values of a field, growth, time buckets |
| `/news/local` | GET · POST | Geo search — `lat` + `lng` + `radius` in km |
| `/news/raw` | GET · POST | Unenriched articles: `id`, `title`, `href`, `created_at`, `description`, `body`, `body_html`, `author`, `keywords`, `source` only — no sentiment, entities or taxonomy |
| `/news/event-types` | **GET only** | The 44 classified event types and their categories |
| `/people` · `/companies` · `/journalists` | **GET only** | Reference profiles, not articles: `id`, `name`, `links`, `profile` (`outlets` for journalists) |
| `/suggest/entities` · `/suggest/categories` · `/suggest/topics` · `/suggest/industries` | **GET only** | Autocomplete an ID from a name prefix |
| `/balance` | **GET only** | Remaining quota for the key |
| `/news/stream` | **GET only** | Live Server-Sent Events feed |

The article and aggregation endpoints take the same parameters either as a query string on
`GET` or as a JSON body on `POST` — use `POST` when a long filter set would blow past URL
length limits. The endpoints marked GET-only answer `404` to a `POST`, not `405`, so a wrong
method looks like a wrong path.

`/news/stream` answers `200` with `content-type: text/event-stream` and takes the same filters.
Between matches it emits SSE **comment** lines — the literal bytes `: heartbeat\n\n` — not
events. A parser that assumes every frame is `event:`/`data:` will choke on them, so drop lines
beginning with `:`. A stream whose filters match nothing sends only heartbeats and delivers no
articles. Streaming is billed per delivered article, so narrow the filters rather than opening
a second connection.

## Key parameters for `/news/everything`

Filters combine with AND. Comma-separated values inside one parameter combine with OR.

**The per-parameter value cap is enforced by silent truncation, not by an error.** Most list
filters take at most 3 comma-separated values; `event.type` and `article.id` take 5. Pass more
and the extras are dropped with no warning — the request still returns `200`:

```
entity.id=1297647                              → 126 957
entity.id=1580517,474,1223812                  →   2 110
entity.id=1580517,474,1223812,1297647          →   2 110   ← 4th ignored
entity.id=1297647,1580517,474,1223812          → 127 040   ← now the 4th is the ignored one

event.type=ipo,layoffs,bankruptcy,recall,data-breach              → 26 511
event.type=ipo,layoffs,bankruptcy,recall,data-breach,earthquake   → 26 511   ← 6th ignored
event.type=earthquake                                             →  9 536   ← it does match on its own
```

Only the first N are applied, where N is that parameter's cap, so **order decides which value
you lose**. Split larger sets across several requests and merge on article `id`.

- `title` — keyword search in article titles, 2–100 chars; outside that range it is
  `400 ER0007`, whose message reads "between 1 and 100 characters" but rejects a single
  character anyway. Quotes for an exact phrase, `"climate change"~2` for proximity. Percent-
  encode the value. **Title search is limited to a 31-day `published_at`
  window**: with no dates the last 31 days are searched (`200` plus warning `ER0366` in
  `meta.warnings`); an explicit wider range returns `400 ER0110`. Variants:
  `title_starts_with`, `title_ends_with`, `title_pattern`.
- `published_at.start`, `published_at.end` — `YYYY-MM-DD`, ISO 8601, or Solr-style date math:
  `NOW-7DAY`, `NOW-1WEEK`, `NOW/DAY`, `NOW-1DAY/DAY`. Relative values are resolved per request,
  so a stored query never goes stale.
- `language.code` — ISO 639-1, up to 3 comma-separated (`en`, `en,fr,de`).
- `category.id`, `topic.id`, `industry.id`, `entity.id` — taxonomy IDs, up to 3 each.
  **Resolve them with `/suggest/*` first — do not guess.** The ID types differ: entities and
  industries are integers (`1580517`), topics are dotted slugs (`industry.technology_news`),
  categories are IPTC MediaTopic codes (`medtop:04000000`). A guessed value returns
  `400 ER0208`, not an empty result — `topic.id=technology`, for instance, does not exist.
- `person.name`, `organization.name`, `location.name`, `brand.name`, `event.name`,
  `disease.name`, `disaster.name`, `sport.name` — filter by entity name instead of an ID.
  The name must match the dictionary exactly, and a miss is a **`400` error, not an empty
  result**: `location.name=New York` → `ER0218`, `brand.name=iPhone` → `ER0222`,
  `sport.name=football` → `ER0250`, `event.name=Olympics` → `ER0228`,
  `disaster.name=flood` → `ER0224`. `person.name=Elon Musk` and
  `organization.name=Google` do resolve. Confirm a name with `/suggest/entities` before
  relying on it, or filter by `entity.id`.
- `source.domain`, `source.id`, `source.country.code`, `source.bias` (`left`, `center`, `right`),
  `source.rank.opr.min` / `.max` — Open PageRank authority. In practice the data tops out at 8:
  over a two-day window `min=6` matched 39 431 articles, `min=7` matched 3 940, `min=8` matched

From apitube/news-api-skills, MIT.