News & Widget API Guide

The News API provides access to financial news articles across multiple languages. Query articles with full-text search, date ranges, and topic filters. The Widget API is a lightweight, CORS-enabled endpoint designed for embedding a news feed directly into third-party websites via a JavaScript widget or custom integration.

Both APIs authenticate with an API key sent in the x-api-key header.

Base URL: https://wingnews.theinvestinsight.com/api

---

Authentication

API Key

All requests require an API key passed in the x-api-key header.

x-api-key: na_live_abc123...

Domain Whitelisting

API keys can optionally enforce domain restrictions. When enabled, the server validates the Origin (or Referer) header against the key's allowed domain list.

Wildcard patterns are supported:

Pattern	Matches
example.com	Exact match only
*.example.com	Any subdomain (app.example.com, cdn.example.com)

If the requesting domain is not in the list, the API returns 403 Forbidden.

Rate Limiting

Each API key has a per-hour token budget.

Header / Status	Description
429 Too Many Requests	Budget exhausted — wait and retry
503 Service Unavailable	Rate-limit service temporarily down

---

News API

Full-featured endpoint for server-to-server integrations. Supports text search, sorting, and both cursor and offset pagination.

List Articles

Retrieve a paginated list of refined news articles.

GET /api/news

Query Parameters

Parameter	Type	Default	Description
q	string	—	Full-text search across title and summary (case-insensitive)
lang	string	—	Language code (e.g. es, zh, ja)
tags	string[]	—	Filter by topics (repeatable: tags=finance&tags=crypto)
from	string	—	Start date, ISO-8601 (e.g. 2026-01-01T00:00:00Z)
to	string	—	End date, ISO-8601 (e.g. 2026-01-31T23:59:59Z)
sortField	string	publishedAt	Sort by publishedAt or title
sortOrder	string	desc	asc or desc
cursor	string	—	Cursor token for cursor-based pagination
offset	number	0	Offset for offset-based pagination (min: 0)
limit	number	20	Items per page (min: 1, max: 100)

Pagination: Supply either cursor or offset, not both. Cursor-based is recommended for infinite-scroll UIs; offset-based for numbered pages.

Example Request

GET /api/news?q=inflation&lang=es&tags=markets&from=2026-02-01T00:00:00Z&limit=10

Response

{
  "items": [
    {
      "id": "cm6xk9abc000108l4",
      "title": "Fed Signals Continued Caution on Inflation",
      "summary": "Federal Reserve officials indicated they remain cautious about inflation trends...",
      "content": "<p>Federal Reserve officials indicated they remain cautious...</p>",
      "image": {
        "original": "https://cdn.example.com/images/abc123.jpg",
        "large": "https://cdn.example.com/images/abc123-large.jpg",
        "medium": "https://cdn.example.com/images/abc123-medium.jpg",
        "thumbnail": "https://cdn.example.com/images/abc123-thumbnail.jpg"
      },
      "language": "es",
      "publishedAt": "2026-02-15T09:30:00.000Z",
      "topics": ["markets", "federal-reserve", "inflation"]
    }
  ],
  "pagination": {
    "cursor": "cm6xk9abc000208l4",
    "hasMore": true,
    "total": 245
  }
}

---

Get Article

Retrieve a single article by ID.

GET /api/news/:id

Path Parameters

Parameter	Type	Description
id	string	Article ID

Response — A single Article object.

Returns 404 if the article doesn't exist.

---

Get Available Languages

Retrieve the list of languages that currently have published articles. Use these codes with the lang filter.

GET /api/news/cultures

Response

[
  { "code": "ar", "name": "Arabic" },
  { "code": "de", "name": "German" },
  { "code": "es", "name": "Spanish" },
  { "code": "fr", "name": "French" },
  { "code": "hu", "name": "Hungarian" },
  { "code": "id", "name": "Indonesian" },
  { "code": "it", "name": "Italian" },
  { "code": "ja", "name": "Japanese" },
  { "code": "pt", "name": "Portuguese" },
  { "code": "ru", "name": "Russian" },
  { "code": "tr", "name": "Turkish" },
  { "code": "vi", "name": "Vietnamese" },
  { "code": "zh", "name": "Chinese" }
]

The list only includes languages with at least one completed, refined article. Sorted alphabetically by name.

---

Widget API

Lightweight endpoint for client-side integrations and the embeddable JavaScript widget. CORS is fully open, however security is enforced through API key domain whitelisting.

List Widget Articles

GET /api/v1/widget/news

Query Parameters

Parameter	Type	Default	Description
lang	string	—	Language code (e.g. es, ja)
from	string	—	Start date, ISO-8601
to	string	—	End date, ISO-8601
topics	string[]	—	Filter by topics (repeatable or comma-separated)
cursor	string	—	Cursor for infinite scroll pagination
offset	number	0	Offset for numbered page pagination
limit	number	20	Items per page (min: 1, max: 100)

Example Request

GET /api/v1/widget/news?lang=es&topics=crypto&limit=5

Response — Same shape as News API list response.

---

Get Widget Article

GET /api/v1/widget/news/:id

Path Parameters

Parameter	Type	Description
id	string	Article ID

Response — A single Article object. Returns 404 if not found.

---

Data Reference

Article Object

Field	Type	Description
id	string	Unique article ID
title	string	Article headline
summary	string	Short excerpt / summary
content	string | null	Full HTML content (null if unavailable)
image	object | null	Image object with size variants
language	string	ISO language code (e.g. es, zh)
publishedAt	string	Publication timestamp (ISO-8601)
topics	string[]	Topic tags (e.g. ["markets", "crypto"])

Image Object

Each article can have an image served in multiple sizes for responsive loading.

Field	Type	Description
original	string	Full-resolution image URL
large	string	Large variant (approximately 1/2 original size)
medium	string	Medium variant (approximately 1/3 original size)
thumbnail	string	Thumbnail variant (approximately 1/4 original size)

URL Pattern: Variant URLs are derived from the original by appending a size suffix before the extension.

Original:  https://cdn.example.com/images/abc123.jpg
Large:     https://cdn.example.com/images/abc123-large.jpg
Medium:    https://cdn.example.com/images/abc123-medium.jpg
Thumbnail: https://cdn.example.com/images/abc123-thumbnail.jpg

Pagination Object

All list endpoints return pagination metadata alongside results.

{
  "items": [],
  "pagination": {
    "cursor": "cm6xk9abc000208l4",
    "hasMore": true,
    "total": 245
  }
}

Field	Type	Description
cursor	string | null	Token to fetch the next page (null if no more pages)
hasMore	boolean	Whether additional pages exist
total	number	Total number of matching articles

Cursor Pagination — Pass the cursor value as the cursor query parameter in the next request. Ideal for infinite-scroll UIs.

Offset Pagination — Pass a numeric offset to skip that many records. Ideal for numbered-page UIs. Do not combine with cursor.

Language Codes

Supported languages:

Code	Language
ar	Arabic
de	German
es	Spanish
fr	French
hu	Hungarian
id	Indonesian
it	Italian
ja	Japanese
pt	Portuguese
ru	Russian
tr	Turkish
vi	Vietnamese
zh	Chinese

Use GET /api/news/cultures for the current, complete list.

Error Responses

All error responses use a consistent shape:

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Status	Error	Common Cause
400	Bad Request	Invalid query parameter (e.g. bad date format)
401	Unauthorized	Missing, invalid, expired, or inactive API key
403	Forbidden	Domain not in API key's whitelist
404	Not Found	Article ID doesn't exist or isn't published yet
429	Too Many Requests	Rate limit exceeded — wait and retry
503	Service Unavailable	Internal service temporarily down