# apitube-news-api

Adopt this skill: https://proskills.md/skills/other/apitube-news-api-skills-skills-apitube-news-api

Page: https://proskills.md/skills/other/apitube-news-api-skills-skills-apitube-news-api
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/apitube-news-api/SKILL.md
size: 8091
upstream: https://github.com/apitube/news-api-skills/blob/main/skills/apitube-news-api/SKILL.md

````text
---
name: apitube-news-api
description: Query the APITube News API — authenticate, search and filter worldwide news articles by keyword, entity, sentiment, source, country and date, and parse the JSON response. Use when an agent needs live or historical news data, media monitoring, or news for a RAG pipeline.
license: MIT
---

# 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
  80, and `min=9` matched none. Use 5 for "mainstream", 7 for "major outlet"; asking f
````

## File: README.md
upstream: https://github.com/apitube/news-api-skills/blob/main/README.md

````text
# APITube News API — skill for AI coding agents

[![skills.sh](https://skills.sh/b/apitube/news-api-skills)](https://skills.sh/apitube/news-api-skills)

The official `SKILL.md` for the [APITube](https://apitube.io) News API. It teaches a coding
agent how to authenticate, search worldwide news, filter by entity, sentiment, source and
date, and read the JSON response — without guessing parameter names.

`SKILL.md` is an open format, so this works in Claude Code, Cursor, Codex, GitHub Copilot,
VS Code, Gemini CLI, Amp, Goose, opencode, Roo Code, Windsurf, JetBrains Junie and every other
skills-compatible agent.

You need an API key: **[get one at apitube.io](https://apitube.io)** — the free tier is 100
requests/day and does not require a card.

## The skill

[`apitube-news-api`](skills/apitube-news-api/SKILL.md) — authentication, endpoints, the
`/news/everything` filters, plain-language `prompt` queries, the response shape, pagination,
rate limits and error codes.

Every parameter, field name, limit and error code in it was executed against the live API at
`api.apitube.io` before being written down.

## Install

### Any agent

```bash
npx skills add apitube/news-api-skills --skill apitube-news-api --agent claude-code
```

This installs into the **current project**, not your home directory: the file lands in
`./.claude/skills/apitube-news-api/SKILL.md` and a `skills-lock.json` is written alongside it,
pinning the source repo and a content hash. Run it from your project root, and commit the lock
file if you want the whole team on the same revision.

`--agent` takes your agent's slug — the [skills.sh](https://skills.sh) registry covers Claude
Code, Cursor, Codex, GitHub Copilot, VS Code, Gemini, Windsurf, opencode, Amp, Goose, Roo,
Cline, Kiro, Trae, Zed and others; run `npx skills add --help` for the current list.

### Claude Code — as a plugin marketplace

```
/plugin marketplace add apitube/news-api-skills
/plugin install news-api-skills@apitube-news-api
```

The first command registers the marketplace, the second installs the plugin at user scope.
Remove them with `/plugin uninstall news-api-skills@apitube-news-api` and
`/plugin marketplace remove apitube-news-api`.

### Manual — copy the folder

```bash
git clone https://github.com/apitube/news-api-skills.git

# Works for Cursor, Codex, VS Code / Copilot and opencode alike
mkdir -p ~/.agents/skills && cp -r news-api-skills/skills/* ~/.agents/skills/

# Claude Code
mkdir -p ~/.claude/skills && cp -r news-api-skills/skills/* ~/.claude/skills/
```

`~/.agents/skills/` (and `.agents/skills/` inside a repo) is the shared location Cursor,
Codex, VS Code, GitHub Copilot and opencode all read, so one copy covers them at once.

| Agent | Personal | Project |
|---|---|---|
| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
| Cursor | `~/.agents/skills/`, `~/.cursor/skills/` | `.agents/skills/`, `.cursor/skills/` |
| Codex | `~/.agents/skills/` | `.agents/skills/` |
| VS Code / GitHub Copilot | `~/.agents/skills/`, `~/.copilot/skills/` | `.agents/skills/`, `.github/skills/` |
| opencode | `~/.agents/skills/`, `~/.config/opencode/skills/` | `.agents/skills/`, `.opencode/skills/` |

Cursor, Codex, VS Code and opencode also read the Claude directories for compatibility.

## Provide the API key

The skill embeds no key. Export it in the environment your agent runs in:

```bash
export APITUBE_API_KEY="your_key"
```

Then pass it as `Authorization: Bearer $APITUBE_API_KEY`, `X-API-Key: $APITUBE_API_KEY`, or
`api_key=` in the query string. Test keys prefixed `api_test_` return masked bodies and do not
consume quota — use one while wiring things up.

## Without installing anything

APITube also serves its skills over HTTP, so an agent can discover them on its own:

- Index: https://docs.apitube.io/.well-known/agent-skills/index.json
- MCP server card: https://docs.apitube.io/.well-known/mcp/server-card.json

There is also a hosted MCP server at `https://mcp.apitube.io/` if you would rather give the
agent tools than instructions — see
https://docs.apitube.io/platform/news-api/ai/mcp-server.

## Links

- Website — https://apitube.io
- Documentation — https://docs.apitube.io
- Pricing — https://apitube.io/pricing
- API reference — https://api-reference.apitube.io
- SDKs and migration kits — https://github.com/apitube
- Contact — https://apitube.io/contact

## Contributing

Found a parameter that behaves differently from what the skill says? Open an issue with the
request you ran and the response you got. Corrections to documented behaviour are the most
useful contribution here — this file is read by agents that will act on it.

## License

MIT — see [LICENSE](LICENSE).
````
