Davi Developers LogoDavi Developers

Documentation

Read a User's Rewards

List the rewards a signed-in user holds, read one reward, and fetch a single item inside it.

This page covers reading the rewards a user holds, with the user's own access token. All three endpoints take scope reward:read. To issue rewards, see Issue Rewards.

List what a user holds

curl "https://api.davi.social/api/v1/rewards" \
  -H "Authorization: Bearer ACCESS_TOKEN"

GET /rewards returns the rewards held across all of the caller's wallets, most recent first, paginated.

Paging walks transactions

Paging runs over the caller's transaction history, then keeps only the transactions that carry reward content. As a result:

  • total_items counts transactions, not rewards. It is an upper bound on the number of items you receive.
  • A page can be shorter than page_size. Transactions with no reward content (a points-only reward, an attendance proof, a plain transfer) are dropped after paging, as is any whose content cannot be read.
  • An empty page is not the end. Keep requesting while current_page is below total_pages.
let page = 1, totalPages = 1;
const rewards = [];
do {
  const res = await fetch(`${API}/rewards?page=${page}`, { headers });
  const body = await res.json();
  rewards.push(...body.items);   // may be empty on any given page
  totalPages = body.total_pages;
} while (page++ < totalPages);

Read one reward

curl "https://api.davi.social/api/v1/rewards/transactions/TRANSACTION_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

GET /rewards/transactions/{transaction_id} returns one reward's content, keyed on the transaction that issued it. It answers 404 when:

  • the transaction belongs to no wallet, or to someone else's wallet (the two answer identically, so a 404 does not say whether the transaction exists);
  • the transaction carries no reward content, such as points on their own or an attendance proof. The list applies the same filter.

This route returns a cached projection of the reward, which keeps listing many rewards cheap. For a transaction detail view, use POST /transactions/{transaction_id}/decrypt and the manifest URL it returns; see Transactions.

Read one item inside a reward

curl "https://api.davi.social/api/v1/rewards/files/FILE_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

GET /rewards/files/{file_id} returns a single item from a reward (a badge, certificate, attachment, coupon, voucher, ticket or profile asset) by the opaque id the reward lists it under.

The id is fixed when the reward is issued. Refetching, correcting or reordering the content does not change it, so you can store it or put it in a link. Davi mints the id: a uid you send on an item is discarded, because an issuer-chosen id could collide with another issuer's or be guessed.

The response carries the item's origin: the transaction, the content version, and when it was generated.

An id for an item the reward does not have, and an id in a reward held by someone else, both answer not found.

Caching

All three endpoints read the same cache, refreshed when it goes stale. If a refresh fails, the endpoint returns the copy already cached, so a reward stays readable while its manifest host is unreachable. Only a reward with nothing cached and nothing reachable reports why it could not be read.

Responses carry the cache state: cached_at, cache_expires_at, content_hash and source_type.

Next