How to make your first request with cURL#

To make your first APITube request with cURL, send a GET to https://api.apitube.io/v1/news/everything with your API key in an X-API-Key header. A valid key returns HTTP 200 and a JSON object whose results field holds the articles. This one command is the whole round trip — copy it into a terminal, swap in your key, and you have live news back.

curl "https://api.apitube.io/v1/news/everything?per_page=3" \
  -H "X-API-Key: YOUR_API_KEY"

cURL ships on macOS, Linux and Windows 10+, so this works without installing anything. Once this call succeeds, every filter — keywords, language, dates — is just another parameter on the same URL.

How do you pass your API key in cURL?#

The API reads your key from one of three places, checked in this order: an Authorization: Bearer header, an X-API-Key header, then an api_key query parameter. Any one of them authenticates the call, so pick whichever is easiest:

# X-API-Key header (recommended for scripts)
curl "https://api.apitube.io/v1/news/everything" -H "X-API-Key: YOUR_API_KEY"

# Bearer token
curl "https://api.apitube.io/v1/news/everything" -H "Authorization: Bearer YOUR_API_KEY"

# api_key in the URL (quickest one-off test)
curl "https://api.apitube.io/v1/news/everything?api_key=YOUR_API_KEY"

Use a header in anything you keep — the query-string form puts your key in shell history and server logs. For the full breakdown, see how to authenticate your API requests.

How do you add parameters and encode them correctly?#

Filters are query parameters on the same endpoint. The catch with cURL is encoding: a value with a space (like a two-word title) or a symbol breaks a raw URL. The clean fix is -G plus --data-urlencode, which builds the query string and encodes each value for you:

curl -G "https://api.apitube.io/v1/news/everything" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "title=electric vehicles" \
  --data-urlencode "language.code=en" \
  --data-urlencode "per_page=10"

Parameter names that contain a dot — language.code, published_at.start — are passed exactly as written; the dot needs no escaping. Only the values need encoding, and --data-urlencode handles that. Without -G, always wrap the whole URL in quotes: an unquoted & between parameters is read by your shell as “run in background”, which silently sends only the first parameter. The maximum per_page is 250; ask for more and the API returns 400 with code ER0171 (“Limit is out of range”). The complete parameter list lives in the official News API parameter reference.

How do you read the cURL response?#

A successful call returns a JSON envelope, not a bare list. The fields you reach for first are status ("ok"), results (the article array), page and limit (the current page and its size), has_next_pages and next_page (whether more exist, plus a ready-made URL), the export block (the same search as CSV, XLSX, RSS, XML, TSV, Parquet, JSON or JSONL), and request_id (quote it to support):

{
  "status": "ok",
  "limit": 3,
  "page": 1,
  "has_next_pages": true,
  "next_page": "https://api.apitube.io/v1/news/everything?per_page=3&page=2",
  "results": [ "… article objects …" ],
  "request_id": "…"
}

To see the HTTP status line and headers as well as the body, add -i. To watch the whole exchange — request headers, TLS, redirects — use -v. To pretty-print only the parts you care about, pipe a quiet call into jq:

curl -s "https://api.apitube.io/v1/news/everything?api_key=YOUR_API_KEY&per_page=3" \
  | jq '{status, page, count: (.results | length)}'

How do you send a POST request with a JSON body instead?#

The same endpoint also accepts POST. Put your filters in a JSON body and set Content-Type: application/json; the API merges query-string and body parameters, so the key can still travel in a header. This is cleaner than -G when a query gets long:

curl -X POST "https://api.apitube.io/v1/news/everything" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "electric vehicles", "language.code": "en", "per_page": 10}'

GET and POST return the identical envelope, so use whichever reads better. New to the endpoint itself? Start with how to run your first news search for what each field means.

Common Questions#

• Why does cURL return a 401?
• Why is only part of my query applied?
• How do I see the exact HTTP status code?
• Which endpoints work without a key?

Why does cURL return a 401?#

A 401 means the key never reached the API or did not match. If no key was sent you get code ER0201; if a key was sent but is wrong, revoked or mistyped you get ER0202. Both arrive as a JSON envelope with status: "not_ok" and an errors array. The usual cURL cause is the header being dropped — check there is a space after the colon in -H "X-API-Key: ..." and that the key has no stray whitespace. See how to fix authentication (401) errors.

Why is only part of my query applied?#

Almost always an unquoted URL. In a shell, & separates commands and ?/spaces are special, so curl https://...?a=1&b=2 sends a=1 and backgrounds the rest. Wrap the entire URL in double quotes, or build the query with -G --data-urlencode so cURL assembles and encodes it for you.

How do I see the exact HTTP status code?#

Add -i to include the status line and response headers above the body, or -w "%{http_code}\n" to print just the numeric code. A working request shows 200; an auth failure shows 401; an out-of-range per_page shows 400.

Which endpoints work without a key?#

Only three: /ping (a health check), /openapi.json (the schema) and /robots.txt. Every endpoint that returns news data requires a valid key, so your first real call always carries one.