GRgrove
giveaway

List giveaways

List giveaways with optional filtering.

Authenticated filters (require Bearer token):

  • my_giveaways=true: Giveaways created by the authenticated account
  • my_entries=true: Giveaways the authenticated account has entered

Public filters (can combine with any filter):

  • exclude_planned=true: Exclude giveaways that haven't started yet
  • status: Filter by giveaway status
  • include_stats=true: Embed per-giveaway stats on each item. Use this to avoid N+1 calls to GET /v1/giveaway/{id} just to populate stats.
get/v1/giveaways

Request

  • Base URL
    https://api.grove.city (the document declares no server; this is the origin it was published from)
  • URL
    https://api.grove.city/v1/giveaways
  • Auth
    none declared

Query parameters

my_giveawaysboolean

Filter to giveaways created by authenticated account

my_entriesboolean

Filter to giveaways the authenticated account has entered

exclude_plannedboolean

Exclude giveaways that haven't started yet (start_at > now)

status'active' | 'ended' | 'drawn' | 'cancelled'

Status states for giveaways.

State machine:

  • active: Giveaway is accepting entries (tips within window)
  • ended: Giveaway window has passed, ready for drawing
  • drawn: Winners have been selected
  • cancelled: Giveaway was cancelled before drawing

Filter by status

include_statsboolean

When true, each returned item populates its stats field (total_entries, unique_participants, total_tips_usd) using a single batched query. Frontends should prefer this over looping GET /v1/giveaway/{id} for each item.

limitinteger

Max results

offsetinteger

Pagination offset

Headers

authorizationstring nullable

Bearer <account_jwt>

Response

Successful Response

totalinteger required
limitinteger required
offsetinteger required

Changes

No recorded changes to this operation across all 1 revision of this API.