{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Pagination and versioning","description":"Read US healthcare contracts and organizations, and work with your saved work, from your own code.","siteUrl":"https://docs.hrcledger.com","llmstxt":{"title":"HRC Ledger API","description":"One key, one envelope, every route and guide."}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"pagination-and-versioning","__idx":0},"children":["Pagination and versioning"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"read-a-long-list-one-page-at-a-time","__idx":1},"children":["Read a long list one page at a time"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A list route gives you one page at a time. Ask for a page size with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]},". It is"," ","25 if you do not send it, and it can be 1 to 100."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The page comes back in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"ok\": true,\n  \"data\": {\n    \"items\": [],\n    \"nextCursor\": \"<cursor>\",\n    \"total\": 120\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items"]}," is this page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextCursor"]}," gets the next page. Send it back as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]},". When it is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", you"," ","have the last page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," is how many there are in all. It is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when the count is not known."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," total does not mean zero."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -H \"Authorization: Bearer $HRC_LEDGER_KEY\" \\\n  \"https://hrcledger.com/api/v1/lists?limit=25&cursor=<cursor>\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A cursor is only for the list that made it. Do not build or change one by hand."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-contract-and-organization-searches","__idx":2},"children":["The contract and organization searches"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/contracts"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/market/orgs"]}," came first and use page"," ","numbers instead. Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," (it starts at 1) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]},". The answer has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," ","and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," next to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-version-is-in-the-address","__idx":3},"children":["The version is in the address"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every route starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]}," is the version."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We do not break ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]},". These changes can happen in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]},", so write your code to"," ","allow them:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a new route,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a new field in an answer,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a new optional parameter,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a new error code."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These changes would break your code, so they only come with a new version, such"," ","as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a field taken out of an answer,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a field whose type changes,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a parameter that becomes required,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a route taken away."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every change to the contract is in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer/changelog"},"children":["Changelog"]},", with its date."]}]},"headings":[{"value":"Pagination and versioning","id":"pagination-and-versioning","depth":1},{"value":"Read a long list one page at a time","id":"read-a-long-list-one-page-at-a-time","depth":2},{"value":"The contract and organization searches","id":"the-contract-and-organization-searches","depth":3},{"value":"The version is in the address","id":"the-version-is-in-the-address","depth":2}],"frontmatter":{"seo":{"title":"Pagination and versioning"}},"lastModified":"2026-10-22T07:39:08.493Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer/pagination-and-versioning","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}