GET

/v1/items

List articles

Retrieve a paginated list of articles with optional filters for category, keyword, source, content status, and date range.

Parameters

Name	Type	Description
`limit` query	`integer`	Number of articles to return Default: `40` e.g. `20`
`offset` query	`integer`	Number of articles to skip Default: `0` e.g. `0`
`category` query	`string`	Filter by category e.g. `politics`
`keyword` query	`string`	Filter by keyword in title e.g. `climate`
`source` query	`string`	Filter by source name e.g. `Reuters`
`content_status` query	`"has_content" \| "no_content" \| "failed"`	Filter by content extraction status e.g. `has_content`
`date_from` query	`integer (int64)`	Start of date range (Unix timestamp in milliseconds) e.g. `1708300800000`
`date_to` query	`integer (int64)`	End of date range (Unix timestamp in milliseconds) e.g. `1708387200000`
`sort_by` query	`"discovered" \| "published"`	Field to sort by Default: `discovered` e.g. `discovered`
`sort_order` query	`"asc" \| "desc"`	Sort direction Default: `desc` e.g. `desc`
`include_embeddings` query	`boolean`	Include embedding vectors in each article. Requires Pro tier or higher. Default: `false`
`embedding_format` query	`"json" \| "base64"`	Embedding output format (only used when include_embeddings=true) Default: `json`

limit integer

query

Number of articles to return

Default: 40

e.g. 20

offset integer

query

Number of articles to skip

Default: 0

e.g. 0

category string

query

Filter by category

e.g. politics

keyword string

query

Filter by keyword in title

e.g. climate

source string

query

Filter by source name

e.g. Reuters

content_status "has_content" | "no_content" | "failed"

query

Filter by content extraction status

e.g. has_content

date_from integer (int64)

query

Start of date range (Unix timestamp in milliseconds)

e.g. 1708300800000

date_to integer (int64)

query

End of date range (Unix timestamp in milliseconds)

e.g. 1708387200000

sort_by "discovered" | "published"

query

Field to sort by

Default: discovered

e.g. discovered

sort_order "asc" | "desc"

query

Sort direction

Default: desc

e.g. desc

include_embeddings boolean

query

Include embedding vectors in each article. Requires Pro tier or higher.

Default: false

embedding_format "json" | "base64"

query

Embedding output format (only used when include_embeddings=true)

Default: json

Request Examples

bash

curl "https://api.newsrank.ai/v1/items?limit=20&offset=0&category=politics&keyword=climate&source=Reuters&content_status=has_content&date_from=1708300800000&date_to=1708387200000&sort_by=discovered&sort_order=desc" \
  -H "Authorization: Bearer nrf_your_api_key"

Response

json

{
  "items": [
    {
      "id": 48210,
      "url_hash": "a1b2c3d4e5",
      "title": "Supreme Court Rules on Landmark Climate Case",
      "url": "https://example.com/article/supreme-court-climate",
      "source_id": 12,
      "source_name": "Reuters",
      "category": "politics",
      "published_at": 1708300800000,
      "discovered_at": 1708301400000,
      "excerpt": "The Supreme Court issued a landmark ruling today on...",
      "image_url": "https://example.com/images/court.jpg",
      "content_status": "has_content",
      "headline_summary": "Supreme Court sides with environmental regulators",
      "slug": "supreme-court-rules-on-landmark-climate-case"
    }
  ],
  "total": 1250,
  "offset": 0,
  "limit": 40
}

Try it

Server

Using sandbox demo key (5 req/min) — no signup required

Authentication

Demo key (sandbox)

Endpoint

GET /v1/items

limit integer Default: 40

offset integer Default: 0

category string

keyword string

source string

content_status "has_content" | "no_content" | "failed"

date_from integer (int64)

date_to integer (int64)

sort_by "discovered" | "published" Default: discovered

sort_order "asc" | "desc" Default: desc

include_embeddings boolean Default: false

embedding_format "json" | "base64" Default: json