Skip to content
UpVoiced Docs

API guides

Pagination

Lists are paginated with opaque cursors. A page is an object with items and next_cursor; next_cursor is null on the last page.

{
  "items": [{ "id": "0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d", "title": "Dark mode", … }],
  "next_cursor": "<opaque string, or null on the last page>"
}

Get the next page

Send next_cursor back as the cursor query parameter with the same filters and sort. limit sets the page size; each operation lists its range and default (usually 1–100, default 25).

curl "https://api.upvoiced.com/v1/posts?limit=100&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

With the SDK

paginate() follows the cursors for you, one page at a time:

import { UpVoiced } from '@upvoiced/sdk';

const apiKey = process.env['UPVOICED_API_KEY']; // uv_live_… (Settings → API keys)
const workspace = process.env['UPVOICED_WORKSPACE_ID']; // sent as X-Workspace
if (!apiKey || !workspace) throw new Error('Set UPVOICED_API_KEY and UPVOICED_WORKSPACE_ID.');
const upvoiced = new UpVoiced({ apiKey, workspace });

// Every item, fetching pages of 100 lazily; stop iterating to stop fetching.
for await (const post of upvoiced.paginate('/v1/posts', { query: { sort: 'top', limit: 100 } })) {
  console.log(post.title, post.vote_count);
}

// Or one page at a time: pass next_cursor back as cursor until it is null.
let cursor: string | undefined;
do {
  const page = await upvoiced.get('/v1/posts', {
    query: { limit: 100, ...(cursor ? { cursor } : {}) },
  });
  for (const post of page.items) console.log(post.title);
  cursor = page.next_cursor ?? undefined;
} while (cursor);

Paginated operations