Davi Developers LogoDavi Developers

API Reference

rewards

16 endpoints

GET/api/v1/rewards

List Rewards

Get all cached rewards for the current user (paginated).

Retrieves cached reward content for all transactions associated with the current user's wallets. Useful for reward preview features.

Query parameters

default_backendstring

default: "primary"

pageinteger

default: 1 · ≥ 1

page_sizeinteger

default: 20 · ≥ 1 · ≤ 100

sort_bystring | null
sort_orderstring

default: "asc"

Responses

200Successful Response
FieldTypeDescription
total_items*integer

Total number of items available

total_pages*integer

Total number of pages available

current_page*integer

Current page number

items*UserRewardCacheResponse[]

List of items on the current page

array items · UserRewardCacheResponse

FieldTypeDescription
transaction_id*string
wallet_addressstring | null
cached_content*IssuedRewardContent

object · IssuedRewardContent

FieldTypeDescription
data*object

Custom data of the reward

itemsRewardAttachment | RewardCertificate | RewardBadge | RewardCoupon | RewardTicket | RewardAsset[]

List of reward items (attachments, badges, certificates, coupons)

content_version*string

The version of the reward content schema

generated_atstring (date-time) | null

The timestamp when the reward content was generated

name*string

Reward template name at time of issuance

descriptionstring | null

Reward template description at time of issuance

issuerIssuerSnapshot | null

Issuer details captured at time of issuance

activityActivitySnapshot | null

Activity details at issuance (if activity-linked reward)

content_hash*string
cached_at*string (date-time)
cache_expires_atstring (date-time) | null
cache_hit_count*integer
last_accessed_atstring (date-time) | null
source_type*string
source_urlstring | null
fetch_latency_msinteger | null
401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/rewards" \
  -H "Authorization: Bearer <token>"
GET/api/v1/rewards/transactions/{transaction_id}

Get Reward By Transaction

Get a specific cached reward by transaction ID.

Retrieves the cached reward content for a specific transaction. If the cache is stale or missing, it will be refreshed automatically. Only returns rewards for transactions belonging to the current user's wallets.

Path parameters

transaction_id*string

Query parameters

default_backendstring

default: "primary"

Responses

200Successful Response
FieldTypeDescription
transaction_id*string
wallet_addressstring | null
cached_content*IssuedRewardContent

object · IssuedRewardContent

FieldTypeDescription
data*object

Custom data of the reward

itemsRewardAttachment | RewardCertificate | RewardBadge | RewardCoupon | RewardTicket | RewardAsset[]

List of reward items (attachments, badges, certificates, coupons)

content_version*string

The version of the reward content schema

generated_atstring (date-time) | null

The timestamp when the reward content was generated

name*string

Reward template name at time of issuance

descriptionstring | null

Reward template description at time of issuance

issuerIssuerSnapshot | null

Issuer details captured at time of issuance

object · IssuerSnapshot

FieldTypeDescription
id*string

Organization unique identifier

name*string

Organization name at issuance

slug*string

Organization slug at issuance

logo_urlstring | null

Logo URL at issuance

websitestring | null

Website at issuance

activityActivitySnapshot | null

Activity details at issuance (if activity-linked reward)

object · ActivitySnapshot

FieldTypeDescription
id*string

Activity unique identifier

name*string

Activity name at issuance

slug*string

Activity slug at issuance

descriptionstring | null

Activity description

image_urlstring | null

Activity image URL

start_timestring (date-time) | null

Activity start time

end_timestring (date-time) | null

Activity end time

content_hash*string
cached_at*string (date-time)
cache_expires_atstring (date-time) | null
cache_hit_count*integer
last_accessed_atstring (date-time) | null
source_type*string
source_urlstring | null
fetch_latency_msinteger | null
401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/rewards/transactions/{transaction_id}" \
  -H "Authorization: Bearer <token>"
GET/api/v1/rewards/files/{file_id}

Get Reward File

Get specific file data (badge, certificate, attachment, coupon, or ticket) by opaque file ID.

The file_id is a base64url-encoded identifier containing transaction_id, type, and index. Returns the matching item along with origin metadata (transaction_id, content_version, generated_at).

Path parameters

file_id*string

Query parameters

default_backendstring

default: "primary"

Responses

200Successful Response
FieldTypeDescription
transaction_id*string

Transaction ID of the cached reward

content_version*string

Version of the reward content schema

generated_atstring (date-time) | null

When the reward content was generated

reward_namestring | null

Reward template name at issuance

reward_descriptionstring | null

Reward template description at issuance

issuerIssuerSnapshot | null

Issuer details at time of issuance

object · IssuerSnapshot

FieldTypeDescription
id*string

Organization unique identifier

name*string

Organization name at issuance

slug*string

Organization slug at issuance

logo_urlstring | null

Logo URL at issuance

websitestring | null

Website at issuance

activityActivitySnapshot | null

Activity details at time of issuance (if activity-linked)

object · ActivitySnapshot

FieldTypeDescription
id*string

Activity unique identifier

name*string

Activity name at issuance

slug*string

Activity slug at issuance

descriptionstring | null

Activity description

image_urlstring | null

Activity image URL

start_timestring (date-time) | null

Activity start time

end_timestring (date-time) | null

Activity end time

data*RewardBadge | RewardCertificate | RewardAttachment | RewardCoupon | RewardTicket | RewardAsset

The file data (badge, certificate, attachment, coupon, ticket, asset)

preview_urlstring | null

Resolved media URL for previewing an asset item (media viewer). Populated for installable asset previews; null otherwise.

installableboolean

Whether this item is an installable reward asset (show an Install button).

default: false

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/rewards/files/{file_id}" \
  -H "Authorization: Bearer <token>"
GET/api/v1/rewards/{reward_slug}

Get Reward

Get a reward template by slug (or uuid, until v1 is frozen).

What the caller may see depends on the reward's state rather than on which path they used. A published, unarchived reward is discoverable by anyone holding reward:read — that is what makes shareable redemption links work. A draft or archived one is visible only to its organization: it is either not ready to be seen or deliberately withdrawn.

Path parameters

reward_slug*string

Responses

200Successful Response
FieldTypeDescription
uuid*string
version*integer
slug*string
organization_uuid*string
activity_uuidstring | null
name*string
descriptionstring | null
points*integer
categorystring | null
supply_totalinteger | null
supply_redeemed*integer
required_entitlementstring | null
content_configobject | null
status*enum

Lifecycle state, derived from is_draft and archived_at.

is_draft*boolean
archived_atstring (date-time) | null
created_at*string (date-time)
updated_atstring (date-time) | null
401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/rewards/{reward_slug}" \
  -H "Authorization: Bearer <token>"
PATCH/api/v1/rewards/{reward_slug}

Update Reward

Update a reward template, including its lifecycle state.

status moves the reward between draft, published and archived; the remaining fields edit its content. Requires an org-scoped token for the reward's organization.

A reward carries no point value yet: points may be omitted or sent as 0, and a non-zero value is refused.

Path parameters

reward_slug*string

Request body*application/json

FieldTypeDescription
statusenum | null

Move the reward through its lifecycle. `published` makes a draft live, `draft` returns a published reward to draft (only while it has no redemptions), and `archived` withdraws it. Omit to leave the state alone.

activity_uuidstring | string (uuid) | null

UUID of the associated activity, if any

namestring | null

Name of the reward template

descriptionstring | null

Description of the reward template

pointsinteger | null

Points required to redeem the reward. Point values are not accepted yet: omit the field or send 0, and any other value is refused.

categorystring | null

Category of the reward

supply_totalinteger | null

Total supply of the reward. None means unlimited

required_entitlementstring | null

Entitlement gate ('member' = any member; a tier key = that capability). Empty string clears the requirement.

content_configContentConfig | null

Configuration for the reward content

object · ContentConfig

FieldTypeDescription
storage_type*enum

Type of content storage

content_templateBaseRewardContent | null

Template for reward content

object · BaseRewardContent

FieldTypeDescription
data*object

Custom data of the reward

itemsRewardAttachment | RewardCertificate | RewardBadge | RewardCoupon | RewardTicket | RewardAsset[]

List of reward items (attachments, badges, certificates, coupons)

content_version*string

The version of the reward content schema

generated_atstring (date-time) | null

The timestamp when the reward content was generated

external_idstring | null

Identifier for external content source

external_webhook_uuidstring | null

Webhook UUID to call for external content generation

generator_paramsobject | null

Parameters for dynamic content generation

cache_strategyenum

Caching strategy for reward content

default: "on_demand"

cache_ttl_secondsinteger | null

Time-to-live for cached content in seconds

content_immutableboolean

Whether the content is immutable once created

default: false

mirror_assetsboolean

Copy externally-hosted images and documents named by this reward's items into Davi's storage, and serve them from there. On by default: the content of an issued reward is frozen but the URLs in it are not, so without this the artwork can be changed or taken down after issuance, and the holder's browser reveals their IP and viewing times to whoever serves it. Turn it off for artwork you intend to keep updating across already-issued rewards, or for assets too large to copy. Mirroring is best-effort — an asset that cannot be copied keeps its original URL.

default: true

Responses

200Successful Response
FieldTypeDescription
uuid*string
version*integer
slug*string
organization_uuid*string
activity_uuidstring | null
name*string
descriptionstring | null
points*integer
categorystring | null
supply_totalinteger | null
supply_redeemed*integer
required_entitlementstring | null
content_configobject | null
status*enum

Lifecycle state, derived from is_draft and archived_at.

is_draft*boolean
archived_atstring (date-time) | null
created_at*string (date-time)
updated_atstring (date-time) | null
400Invalid request
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X PATCH "https://api.davi.social/api/v1/rewards/{reward_slug}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'
DELETE/api/v1/rewards/{reward_slug}

Delete Reward

Permanently delete a draft reward template.

Only allowed if template is a draft and has no redemptions.

Requires an org-scoped token for the reward's organization.

Path parameters

reward_slug*string

Responses

200Successful Response
FieldTypeDescription
message*string

Success or status message

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X DELETE "https://api.davi.social/api/v1/rewards/{reward_slug}" \
  -H "Authorization: Bearer <token>"
POST/api/v1/rewards/{reward_slug}/trigger

Trigger Reward

Run this reward's trigger for one user, outside the event that normally fires it.

Distribution goes through the reward's enabled trigger rather than around it, so the same scope rules, deduplication and audit trail apply as an automatic firing — the bypass flags are what opt out of each, individually.

Requires an org-scoped token for the reward's organization.

Path parameters

reward_slug*string

Request body*application/json

FieldTypeDescription
user_uuid*string | string (uuid)

User UUID to trigger reward for

bypass_scope_validationboolean

Skip scope pattern matching (admin override)

default: false

bypass_deduplicationboolean

Skip deduplication check (allow duplicate rewards)

default: false

metadataobject

Additional metadata to merge with trigger metadata

Responses

200Successful Response
FieldTypeDescription
success*boolean
transaction_idstring | null
delivery_uuidstring | null
trigger_name*string
user_uuid*string
reward_template_uuid*string
points_distributed*integer
matched_scopestring | null
errorstring | null
detailsobject | null
400Invalid request
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X POST "https://api.davi.social/api/v1/rewards/{reward_slug}/trigger" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'
POST/api/v1/rewards/{reward_slug}/claim

Claim Reward

Claim a reward that is being offered by its link, for yourself.

The recipient is always the caller — there is no identifier to name someone else. That is the difference from /redeem, which issues on an organization's behalf and demands an org-scoped token: here the link is the authority, so a visitor's own token is enough and no membership in the issuing organization is needed.

A reward is claimable this way only while it is published, unarchived and carries an enabled trigger on the reward's link. Anything else — a slug the platform never made, a draft, a reward whose link was never switched on — answers 404, so a caller cannot tell which by probing.

Claiming twice returns the first claim's transaction rather than issuing again, so a double-tap or a retried request costs nothing. A reward gated on membership or an entitlement still refuses a caller who lacks it, and a reward whose supply is exhausted refuses everyone.

Charged to the expensive rate-limit bucket: a claim signs a ledger transfer.

Path parameters

reward_slug*string

Query parameters

default_backendstring

default: "primary"

Responses

200Successful Response

RedemptionResultCompleted | RedemptionResultPending

400Invalid request
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X POST "https://api.davi.social/api/v1/rewards/{reward_slug}/claim" \
  -H "Authorization: Bearer <token>"
POST/api/v1/rewards/{reward_slug}/redeem

Redeem Reward

Issue (redeem) a reward to a recipient.

Requires an org-scoped token for the reward's organization. The recipient is a tagged-union identifier that resolves to a wallet (including custodial wallets with no Davi account) — this is how a ticket is issued to a card-only attendee.

Path parameters

reward_slug*string

Query parameters

default_backendstring

default: "primary"

Request body*application/json

FieldTypeDescription
identifier*IdentifierRef

Tagged-union recipient identifier (wallet/card/username/user_id/link). Resolves to a wallet, including custodial wallets with no Davi account. Use {type: 'user_id', value: <uuid>} to issue to a known Davi user.

object · IdentifierRef

FieldTypeDescription
type*enum

How to interpret `value`

value*string

Identifier value (card uid, wallet address, username, user uuid, or Davi link)

scope*string

Scope of the redemption

metadataobject

Additional metadata

idempotency_keystring | null

Client-provided idempotency key. If not provided, will be derived from stable identifiers

Responses

200Successful Response

RedemptionResultCompleted | RedemptionResultPending

400Invalid request
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X POST "https://api.davi.social/api/v1/rewards/{reward_slug}/redeem" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'
GET/api/v1/rewards/deliveries/{delivery_uuid}

Get Delivery Status

Poll the status of an async external reward generation.

When redeeming an external reward, the webhook delivery is processed asynchronously. This endpoint allows clients to poll for the result by delivery UUID.

Path parameters

delivery_uuid*string

Responses

200Successful Response
FieldTypeDescription
status*enum

Status of the external reward generation

delivery_uuidstring | null

Webhook delivery UUID for polling (when status is pending)

transaction_idstring | null

Transaction ID (when status is completed)

errorstring | null

Error message (when status is failed)

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/rewards/deliveries/{delivery_uuid}" \
  -H "Authorization: Bearer <token>"
POST/api/v1/rewards/{reward_slug}/propagate

Propagate Reward

Propagate template changes to all existing holders.

Creates a background job that reverses old reward transactions and issues new ones with updated content.

Path parameters

reward_slug*string

Responses

200Successful Response
FieldTypeDescription
uuid*string
reward_template_uuid*string
from_version*integer
to_version*integer
total_count*integer
completed_count*integer
failed_count*integer
status*string
points_delta*integer
initiated_by*string
completed_atstring (date-time) | null
failure_reasonstring | null
created_at*string (date-time)
updated_atstring (date-time) | null
400Invalid request
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X POST "https://api.davi.social/api/v1/rewards/{reward_slug}/propagate" \
  -H "Authorization: Bearer <token>"
GET/api/v1/rewards/{reward_slug}/propagations

List Propagations

List all propagation records for a reward template.

Path parameters

reward_slug*string

Responses

200Successful Response
FieldTypeDescription
total_items*integer

Total number of items available

total_pages*integer

Total number of pages available

current_page*integer

Current page number

items*RewardPropagationResponse[]

List of items on the current page

array items · RewardPropagationResponse

FieldTypeDescription
uuid*string
reward_template_uuid*string
from_version*integer
to_version*integer
total_count*integer
completed_count*integer
failed_count*integer
status*string
points_delta*integer
initiated_by*string
completed_atstring (date-time) | null
failure_reasonstring | null
created_at*string (date-time)
updated_atstring (date-time) | null
400Invalid request
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/rewards/{reward_slug}/propagations" \
  -H "Authorization: Bearer <token>"
GET/api/v1/rewards/{reward_slug}/propagations/{propagation_uuid}

Get Propagation

Get a single propagation record.

Path parameters

reward_slug*string
propagation_uuid*string

Responses

200Successful Response
FieldTypeDescription
uuid*string
reward_template_uuid*string
from_version*integer
to_version*integer
total_count*integer
completed_count*integer
failed_count*integer
status*string
points_delta*integer
initiated_by*string
completed_atstring (date-time) | null
failure_reasonstring | null
created_at*string (date-time)
updated_atstring (date-time) | null
400Invalid request
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

404Resource not found
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/rewards/{reward_slug}/propagations/{propagation_uuid}" \
  -H "Authorization: Bearer <token>"
GET/api/v1/organizations/{organization_slug}/rewards

List Organization Rewards

List all reward templates for an organization.

Path parameters

organization_slug*string

Query parameters

default_backendstring

default: "primary"

pageinteger

default: 1 · ≥ 1

page_sizeinteger

default: 20 · ≥ 1 · ≤ 100

sort_bystring | null
sort_orderstring

default: "asc"

Responses

200Successful Response
FieldTypeDescription
total_items*integer

Total number of items available

total_pages*integer

Total number of pages available

current_page*integer

Current page number

items*RewardTemplateResponse[]

List of items on the current page

array items · RewardTemplateResponse

FieldTypeDescription
uuid*string
version*integer
slug*string
organization_uuid*string
activity_uuidstring | null
name*string
descriptionstring | null
points*integer
categorystring | null
supply_totalinteger | null
supply_redeemed*integer
required_entitlementstring | null
content_configobject | null
status*enum

Lifecycle state, derived from is_draft and archived_at.

is_draft*boolean
archived_atstring (date-time) | null
created_at*string (date-time)
updated_atstring (date-time) | null
401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/organizations/{organization_slug}/rewards" \
  -H "Authorization: Bearer <token>"
POST/api/v1/organizations/{organization_slug}/rewards

Create Reward

Create a new reward template for an organization.

Requires an org-scoped token for the target organization.

A reward carries no point value yet: points may be omitted or sent as 0, and a non-zero value is refused.

Path parameters

organization_slug*string

Query parameters

default_backendstring

default: "primary"

Request body*application/json

FieldTypeDescription
organization_uuid*string | string (uuid)

UUID of the organization creating the reward template

activity_uuidstring | string (uuid) | null

UUID of the associated activity, if any

name*string

Name of the reward template

descriptionstring

Description of the reward template

default: ""

pointsinteger

Points required to redeem the reward. Point values are not accepted yet: omit the field or send 0, and any other value is refused.

default: 0

categorystring | null

Category of the reward

supply_totalinteger | null

Total supply of the reward. None means unlimited

required_entitlementstring | null

Entitlement gate. None = open to everyone; 'member' = any active member; any other key = the member's active tier must grant it (grant the same key to several tiers to allow all of them).

content_config*ContentConfig

Configuration for the reward content

object · ContentConfig

FieldTypeDescription
storage_type*enum

Type of content storage

content_templateBaseRewardContent | null

Template for reward content

object · BaseRewardContent

FieldTypeDescription
data*object

Custom data of the reward

itemsRewardAttachment | RewardCertificate | RewardBadge | RewardCoupon | RewardTicket | RewardAsset[]

List of reward items (attachments, badges, certificates, coupons)

content_version*string

The version of the reward content schema

generated_atstring (date-time) | null

The timestamp when the reward content was generated

external_idstring | null

Identifier for external content source

external_webhook_uuidstring | null

Webhook UUID to call for external content generation

generator_paramsobject | null

Parameters for dynamic content generation

cache_strategyenum

Caching strategy for reward content

default: "on_demand"

cache_ttl_secondsinteger | null

Time-to-live for cached content in seconds

content_immutableboolean

Whether the content is immutable once created

default: false

mirror_assetsboolean

Copy externally-hosted images and documents named by this reward's items into Davi's storage, and serve them from there. On by default: the content of an issued reward is frozen but the URLs in it are not, so without this the artwork can be changed or taken down after issuance, and the holder's browser reveals their IP and viewing times to whoever serves it. Turn it off for artwork you intend to keep updating across already-issued rewards, or for assets too large to copy. Mirroring is best-effort — an asset that cannot be copied keeps its original URL.

default: true

Responses

200Successful Response
FieldTypeDescription
uuid*string
version*integer
slug*string
organization_uuid*string
activity_uuidstring | null
name*string
descriptionstring | null
points*integer
categorystring | null
supply_totalinteger | null
supply_redeemed*integer
required_entitlementstring | null
content_configobject | null
status*enum

Lifecycle state, derived from is_draft and archived_at.

is_draft*boolean
archived_atstring (date-time) | null
created_at*string (date-time)
updated_atstring (date-time) | null
400Invalid request
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

409Resource already exists
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X POST "https://api.davi.social/api/v1/organizations/{organization_slug}/rewards" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'
GET/api/v1/activities/{activity_slug}/rewards

List Activity Rewards

List all reward templates for an activity.

Path parameters

activity_slug*string

Query parameters

default_backendstring

default: "primary"

pageinteger

default: 1 · ≥ 1

page_sizeinteger

default: 20 · ≥ 1 · ≤ 100

sort_bystring | null
sort_orderstring

default: "asc"

Responses

200Successful Response
FieldTypeDescription
total_items*integer

Total number of items available

total_pages*integer

Total number of pages available

current_page*integer

Current page number

items*RewardTemplateResponse[]

List of items on the current page

array items · RewardTemplateResponse

FieldTypeDescription
uuid*string
version*integer
slug*string
organization_uuid*string
activity_uuidstring | null
name*string
descriptionstring | null
points*integer
categorystring | null
supply_totalinteger | null
supply_redeemed*integer
required_entitlementstring | null
content_configobject | null
status*enum

Lifecycle state, derived from is_draft and archived_at.

is_draft*boolean
archived_atstring (date-time) | null
created_at*string (date-time)
updated_atstring (date-time) | null
401Authentication failed
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

403Insufficient permissions
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

422Validation error
FieldTypeDescription
errors*object

Map of field names to error messages. Use '_root' for form-level errors.

message*string

Human-readable error summary

codestring | null

Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/activities/{activity_slug}/rewards" \
  -H "Authorization: Bearer <token>"