API pagination

Some requests are likely to return a large amount of data. You can paginate it by adding ?limit=<x>, where x is the number of elements of the dataset you wish to return in each response, to the end of the request. This instructs the server to only send x "pages" of the response.

For the Stamps endpoint, x refers to the number of Stamp objects to return in each response. The full request to the Stamp endpoint, including the pagination instruction and headers, could look as follows:

curl --request GET 'https://api.scorer.gitcoin.co/registry/stamps/{address}?limit=3' \
  --header 'X-API-KEY: {API-KEY}'

In this example, the API will return three Stamps in each response.

To help you navigate, the returned data includes values in the prev and next fields. These are endpoint URLs with pre-filled query parameters you can use to retrieve the previous or next chunk of data. Note that if you request a limit of 3, your next value is also going to have a limit of 3. For example, if the response contains Stamps 4, 5 and 6, the URL in prev will return Stamps 1, 2, and 3. The URL in next will return Stamps 7, 8, and 9.

This is what a response looks like with the next and prev fields. Notice these fields values are endpoint URLs.

{
  "next": "https://api.scorer.gitcoin.co/registry/stamps/{address}?token=bmVw%4dFNQ9fM3TcxMTcD%3D&limit=3",
  "prev": "https://api.scorer.gitcoin.co/registry/stamps/{address}?token=c9fMTcHJlTcwdlxMNQ%3D%3D&limit=3",
  "items": [
    {
      "version": "1.0.0",
      "credential": {...}
    }
  ]
}

To retrieve the next page of results you can use the URL provided in the next field, in this case:

curl --request GET 'https://api.scorer.gitcoin.co/registry/stamps/{address}?token=bmVw%4dFNQ9fM3TcxMTcD%3D&limit=3' \
  --header 'X-API-KEY: {API-key}'

You can also use the offset parameter to retrieve data from a given location in a paginated API response. The offset value given identifies the first element in the response you want to retrieve. For example, passing offset=5 means the response will skip the first 5 elements and start at element 6 of the returned data. You can combine this with limit to get specific chunks of data, for example to retrieve objects 6 - 10, you could pass offset=5&limit=5.

Here's what that would look like in practice, retrieving the 6th to 10th Stamps for a given address:

curl --request GET 'https://api.scorer.gitcoin.co/registry/stamps/{address}?offset=5&limit=5' \
  --header 'X-API-KEY: {API-key}'

Stamp and score expiry Educating users