Spec list cursors for a public invoices API

Vibe codingMedium25 minStripe style

Your task

Your company's public REST API, written in Go, lets integrators list invoices. They can sort by created or amount_due, filter by status and customer, and page forward or back. Many integrators run sync jobs that save a cursor and resume hours later. An agent will write the shared paging package that every list endpoint will use.

Write the spec you would hand the agent.

What you know:

  • Go, pgx and Postgres
  • invoices(id, account_id, customer_id, status, amount_due, created_at), where id is unique and every column is NOT NULL
  • many invoices share an amount_due, and nightly billing creates thousands with the same created_at
  • the account comes from the API key on each request

Then, in a few sentences: what would "add cursor pagination" leave the agent to guess?