Skip to main content
GET
/
api
/
v1
/
stories
List stories
curl --request GET \
  --url http://localhost:3000/api/v1/stories \
  --header 'Authorization: Bearer <token>'
{
  "stories": [
    {
      "id": "<string>",
      "title": "<string>",
      "summary": "<string>",
      "article_count": 123,
      "published_at": "2023-11-07T05:31:56Z",
      "article_ids": [
        "<string>"
      ],
      "country": "<string>",
      "topics": [
        "<string>"
      ],
      "companies": [
        {
          "id": "<string>",
          "name": "<string>",
          "ticker_symbol": "<string>"
        }
      ],
      "category": {
        "id": "<string>",
        "name": "<string>"
      }
    }
  ],
  "pagination": {
    "count": 25,
    "next_cursor": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

API Key authentication using Bearer token

Headers

​
If-None-Match
string

ETag value from a previous response. Returns 304 Not Modified if data has not changed.

Query Parameters

​
limit
integer

Number of stories to return per page (default 25, max 100).

​
cursor
string

Opaque pagination cursor returned as pagination.next_cursor from a previous response. Mutually exclusive with q.

​
updated_after
string

ISO 8601 datetime. Returns only stories updated after this timestamp. Use this for polling-based real-time updates: store the timestamp of your last sync, then request only newer results on each poll (see the Real-Time Updates guide at /api-docs). Disables cursor pagination — all matching results are returned in a single response.

​
q
string

Full-text search query (2-200 characters). Results are ranked by relevance instead of publication date. Mutually exclusive with cursor. Disables caching.

​
country
string

Filter by country using ISO 3166-1 alpha-2 code (e.g. SE, NO, DK).

​
category
string

Filter by category ID.

​
ticker
string

Filter by company stock ticker symbol. Returns stories mentioning the company.

​
published_after
string

ISO 8601 datetime. Returns stories published on or after this timestamp.

​
published_before
string

ISO 8601 datetime. Returns stories published before this timestamp.

​
fields
string

Comma-separated list of fields to include in the response. Available fields: id, title, summary, published_at, article_count, article_ids, country, category, topics, companies.

Response

Stories retrieved

​
stories
object[]
​
pagination
object