GET [/instances/$INSTANCE]/private/fountains

Lists a bounded page of fountains of the instance, ordered by fountain_serial. This endpoint is available since protocol v43. Pagination and the fountain_serial response field are available since protocol v44. Clients must iterate over the pages to retrieve all fountains.

Required permission: fountains-read (see Scopes)

Request:

Query Parameters:

• limit – Optional. Signed 64-bit integer specifying the page size and order. Positive values select ascending serial order; negative values select descending serial order. The default is 20. The absolute page size is capped at 100, including when a larger magnitude is requested. Zero returns an empty page.

• offset – Optional. Exclusive fountain_serial cursor, an integer between 0 and 9223372036854775807. Defaults to 0 for non-negative limits and 9223372036854775807 for negative limits. Ascending pages contain serials greater than the cursor; descending pages contain serials less than the cursor.

To iterate, use the last entry’s fountain_serial as the offset of the next request, keeping the same limit. Stop when a page is empty. For example, start with ?limit=20 and continue with ?limit=20&offset=42 if the last returned serial is 42. Each request reads the current database state; the iteration does not provide a snapshot across requests.

Response:

200 OK:

The backend has successfully returned a page of at most 100 fountains. Returns a FountainsListResponse.

400 Bad request:

A pagination parameter is malformed or outside its permitted range.

404 Not found:

The merchant instance is unknown.

500 Internal Server Error:

The server experienced an internal failure.

Details:

interface FountainsListResponse {

  // The requested page of fountains, in serial order.
  fountains: FountainEntry[];
}

interface FountainEntry {

  // Database serial number used as an exclusive pagination cursor.
  // Since protocol **v44**.
  fountain_serial: Integer;

  // Identifier of the fountain.
  fountain_id: Slug;

  // Human-readable description of the fountain.
  description: string;
}