Connect KVwire to your agent

Add category to an items request to get one category; without it all categories are included. Returned items use the same values in their category.

1. 01
   Compress

   Add --compressed to curl, or enable gzip or br in other clients. Compressed JSON is 1/4 to 1/8 of its size.

2. 02
   Send the ETag

   Keep the ETag from the response and send If-None-Match next time; unchanged content returns 304 with no body.

3. 03
   Keep the pace

   Items and trending at most once a minute; the daily once after daily at 08:00, the weekly and monthly once after they come out; when paging back, stop at an item you already have.

How often content changes: new items arrive throughout the day, the selection changes a few to a few dozen times a day, and the daily comes out daily at 08:00, the weekly Mondays at 10:00 and the monthly on the 1st of each month at 10:30 (UTC).

# First time: keep the ETag from the response headers
curl --compressed -i 'https://kvwire.com/api/v1/items?mode=selected&window=24h&limit=20'
# Then at most once a minute with the ETag; a 304 means nothing changed
curl --compressed -i -H 'If-None-Match: <last ETag>' 'https://kvwire.com/api/v1/items?mode=selected&window=24h&limit=20'

To page back, pass page.nextCursor back as cursor and stop at an item you already have, instead of re-reading 7 days each time.

400

Bad parameters: fix them per the OpenAPI definition and the returned code; do not switch to a wider query automatically. An invalid cursor, or one outside the window, returns invalid_cursor; start again from the first page.

409

snapshot_required: changes cannot safely continue; take a fresh full snapshot.

429

Too many requests: wait as Retry-After says and do not retry in parallel.

5xx

Back off exponentially and use the last successful result meanwhile; the public service has no SLA.

Anonymous access does not mean every use is permitted; see the Terms of Use。