Paginação, busca e filtros

As listagens padronizadas retornam items e page. A paginação usa cursor por chave, sem números de página ou offset.

{
  "items": [],
  "page": {
    "limit": 50,
    "total": 0,
    "next_cursor": null
  }
}

total conta os registros dentro dos filtros e do escopo permitido; não é um total de todas as organizações. next_cursor: null indica que não há próxima página no resultado consultado.

Parâmetros

Parâmetro	Comportamento
limit	Padrão 50; de 1 a 100
cursor	Valor opaco recebido em page.next_cursor
sort	Campos separados por vírgula; - indica ordem decrescente
q	Busca nos campos marcados como pesquisáveis; até 200 caracteres
filter	Objeto JSON com campos e operadores permitidos pelo recurso

Exemplo de primeira leitura:

curl --get "$COBRES_API_URL/api/v1/debts" \
  -H "Authorization: Bearer $COBRES_API_KEY" \
  --data-urlencode 'limit=50' \
  --data-urlencode 'sort=-created_at' \
  --data-urlencode 'filter={"original_amount_cents":{"gte":10000}}'

Na leitura seguinte, envie o cursor retornado e mantenha a consulta. Ao alterar busca, filtro ou ordenação, reinicie sem cursor. O cursor é vinculado à ordenação; reaproveitá-lo em outra ordem provoca 400 listing_invalid.

Formato de filtros

A igualdade pode ser abreviada: {"status":"active"}. Operadores usam um objeto com uma única operação: {"created_at":{"gte":"2026-10-01T00:00:00Z"}}.

Para combinar, use {"and":[... ]} ou {"or":[... ]}. A implementação limita profundidade a 3, nós a 20, filhos de or a 10 e valores de in a 50. Nem todo campo aceita todos os operadores; a definição da listagem é a referência.

Não envie SQL, nomes de tabelas ou campos arbitrários. Um campo retornado no item pode não permitir busca ou ordenação. Por exemplo, campos auxiliares usados para busca podem ser explicitamente não ordenáveis.

Concorrência e exportação

O cursor preserva a progressão da ordenação e considera valores nulos ao final. Ele não cria um snapshot imutável do conjunto inteiro. Em rotinas de sincronização, guarde os identificadores processados e considere alterações concorrentes. Não use total como prova de que todos os registros foram processados.