---
title: "Browse, search, or sync items"
method: GET
path: "/v1/items"
---

# Browse, search, or sync items

`GET /v1/items`

## Request

- Base URL: `https://hottub.news`
- URL: `https://hottub.news/v1/items`
- Auth: none declared

## Query parameters

- `q` string
- `lang` string
- `country` string
- `topic` string
- `source` string
- `kind` string
- `since` string
- `until` string
- `after` integer
- `before` string
- `limit` integer
- `sponsored` 'include' | 'exclude' | 'only'
- `category` string
- `sentiment` string
- `political` boolean
- `tone_min` number
- `tone_max` number
- `match` 'hybrid' | 'keyword' | 'semantic'
- `collapse` 'story'
- `per_source` integer
- `sort` 'newest' | 'hot' | 'positive' | 'negative'
- `format` 'json' | 'ndjson' | 'lines' | 'md' | 'rss' | 'jsonfeed'

## Response `200`

A page of items

- List
  - `schema` 'hottub-news/list/v1', required
  - `item_schema` string
  - `count` integer, required
  - `cursor` integer
  - `next` string
  - `sponsored` integer, required
  - `items` Item[], required
    - `id` string, required: n_ news (derived from canonical URL), s_ sponsored
    - `seq` integer: Monotonic sync cursor
    - `kind` 'article' | 'press_release' | 'official' | 'community' | 'research' | 'sponsored', required
    - `title` string, required
    - `url` string, uri, required
    - `summary` string
    - `published` string, date-time, required
    - `seen` string, date-time, required
    - `lang` string
    - `country` string
    - `source` object, required
      - `id` string, required
      - `name` string, required
      - `domain` string
    - `via` string, required
    - `topics` string[]
    - `authors` string[]
    - `image` string, uri
    - `mentions` integer: Sources that linked this exact URL (omitted when 1)
    - `story` string
    - `related` integer: sort=hot / collapse=story: other reports of this story
    - `score` number: q= relevance
    - `category` 'arts-culture-entertainment' | 'conflict-war' | 'crime-law' | 'disaster-accident' | 'economy-business' | 'education' | 'environment' | 'health' | 'human-interest' | 'labour' | 'lifestyle-leisure' | 'politics' | 'religion' | 'science-technology' | 'society' | 'sport' | 'weather'
    - `category_p` number
    - `category2` string
    - `sentiment` 'negative' | 'neutral' | 'positive'
    - `tone` number
    - `political` number
    - `disclosure` object
      - `paid` unknown, required
      - `label` string, required
      - `campaign` string, required
      - `sponsor` object, required
        - `id` string, required
        - `name` string, required
        - `url` string
        - `verified` boolean, required

## Other responses

- `400`: Error with a fix-it message

---

[API](https://skmtc.dev/hottub/apis/hottub-news.md) · [All operations](https://skmtc.dev/hottub/apis/hottub-news/llms.txt) · [OpenAPI document](https://skmtc.dev/hottub/apis/hottub-news/revisions/cf50ab224171?raw)