Pagination

List endpoints return results in pages using opaque cursors. Cursors are stable across inserts and deletes, so you never miss or double-count a record while paging.

#Request parameters

Parameter	Type	Default	Description
`limit`	integer	`25`	Items per page, `1`–`100`.
`cursor`	string	-	Opaque cursor from a previous response's `next_cursor`.

#Response shape

Paginated responses wrap results in a data array alongside a next_cursor:

{
  "data": [
    { "id": "8842", "first_name": "Dana", "last_name": "Levi" },
    { "id": "8843", "first_name": "Yossi", "last_name": "Cohen" }
  ],
  "next_cursor": "eyJpZCI6Ijg4NDMifQ"
}

When next_cursor is a string, there are more results - pass it back as ?cursor=....
When next_cursor is null, you've reached the last page.

Cursors are opaque

Never parse, construct, or store assumptions about a cursor's contents. Treat it as a black box: take the next_cursor you're given and send it back verbatim.

#Paging through every result

cursor=""
while : ; do
  resp=$(curl -sG https://api.smile-app.co.il/v1/patients \
    -H "Authorization: Bearer sk_live_..." \
    --data-urlencode "limit=100" \
    --data-urlencode "cursor=$cursor")
  echo "$resp" | jq '.data[]'
  cursor=$(echo "$resp" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

#Response formats

Many endpoints support a response_format query parameter to trade detail for payload size:

Value	Description
`concise` (default)	Core identity and reference fields only. Smaller payloads, ideal for lists and agents.
`detailed`	Adds extra fields such as address, contacts, and balances where available.

curl -G https://api.smile-app.co.il/v1/patients/8842 \
  -H "Authorization: Bearer sk_live_..." \
  --data-urlencode "response_format=detailed"

Keep payloads small for agents

For AI agents and bulk scripts, prefer concise and a high limit. Fetch detailed only for the specific records you need to act on.

#Non-paginated lists

A few small reference endpoints (such as catalog lists and availability) return all results in a single data array with no cursor, since the result set is naturally bounded.

{ "data": [ /* ... */ ] }