API Reference
Complete reference for the 555 backend API. All endpoints are served from a single REST server and use JSON for request/response bodies unless otherwise noted. Base URL:https://api.rndrntwrk.com
Authentication Model
Most endpoints require a valid session cookie obtained through the SIWS (Sign In With Solana) flow. The flow works as follows:- Request a nonce via
POST /auth/nonce - Sign the nonce with your Solana wallet
- Submit the signed message to
POST /auth/verifyto receive a session cookie - Include the session cookie on all subsequent requests
requireAdminToken middleware.
Authentication
POST /auth/nonce
POST /auth/nonce
Request a sign-in nonceGenerates a one-time nonce for the SIWS authentication flow. The client signs this nonce with their Solana wallet private key and submits it to
/auth/verify.- Auth: None
- Returns: JSON object containing the nonce string
POST /auth/verify
POST /auth/verify
Verify signed nonce and create sessionValidates the signed SIWS message. On success, sets an authenticated session cookie and returns the wallet address.
- Auth: None (establishes auth)
- Returns: Session cookie + wallet address
POST /auth/logout
POST /auth/logout
End the current sessionDestroys the server-side session and clears the session cookie.
- Auth: Session cookie
- Returns:
200 OK
GET /me
GET /me
Get current authenticated userReturns the wallet address and account metadata for the currently authenticated session.
- Auth: Session cookie
- Returns: Wallet address, eligibility status, and session metadata
POST /auth/social/link/start
POST /auth/social/link/start
POST /auth/social/link/verify
POST /auth/social/link/verify
Arcade & Gaming
GET /game/{id}/rank
GET /game/{id}/rank
Get wallet rank for a gameReturns the current authenticated wallet’s rank within a specific game leaderboard.
- Auth: Session cookie
- Path params:
id— game identifier - Returns: Rank position, score, and percentile
POST /arcade/score
POST /arcade/score
Submit an arcade scoreRecords a game score for the authenticated wallet. Scores are validated server-side and contribute to leaderboard standings and point accrual.
- Auth: Session cookie
- Returns: Recorded score confirmation and updated rank
GET /arcade/state
GET /arcade/state
Get current arcade stateReturns the current arcade theme, active events, and visual state. Used by the frontend to render the Alice-themed arcade environment.
- Auth: None
- Returns: Theme configuration, active event data, and arcade metadata
GET /arcade/cabinets
GET /arcade/cabinets
List arcade cabinetsReturns all arcade cabinets and their current possession state (which entity or character is controlling each cabinet).
- Auth: None
- Returns: Array of cabinet objects with game ID, possession status, and display metadata
GET /game/{id}/state
GET /game/{id}/state
Get game stateRetrieves the persisted game state for the authenticated wallet in a specific game.
- Auth: Session cookie
- Path params:
id— game identifier - Returns: Serialized game state object
PUT /game/{id}/state
PUT /game/{id}/state
Save game statePersists game state for the authenticated wallet. Used for saving progress in stateful games.
- Auth: Session cookie
- Path params:
id— game identifier - Returns: Confirmation of saved state
POST /game/{id}/record
POST /game/{id}/record
Post a game recordSubmits a finalized game record (e.g. completed run, match result) that is immutably logged.
- Auth: Session cookie
- Path params:
id— game identifier - Returns: Recorded entry confirmation
POST /game/{id}/play
POST /game/{id}/play
Register a game play sessionLogs that the user started a play session for a specific game. Used for engagement tracking and quest completion.
- Auth: Session cookie
- Path params:
id— game identifier - Returns: Play session acknowledgment
GET /game/{id}/leaderboard
GET /game/{id}/leaderboard
Get per-game leaderboardReturns the leaderboard for a specific game. Supports period-based filtering.
- Auth: None
- Path params:
id— game identifier - Query params:
period—day,week,month, oryear - Returns: Ranked array of wallet addresses and scores
GET /game/{id}/stats
GET /game/{id}/stats
Get game statisticsReturns aggregate statistics for a specific game (total plays, unique players, etc.).
- Auth: None
- Path params:
id— game identifier - Returns: Aggregate game stats object
GET /game/referral/leaderboard
GET /game/referral/leaderboard
Get referral pseudo-game leaderboardReturns a leaderboard ranked by referral activity, formatted like a game leaderboard.
- Auth: None
- Returns: Ranked array of wallets by referral performance
Battles
POST /battle/create
POST /battle/create
Create a new battleCreates a head-to-head or multiplayer battle instance for a specific game.
- Auth: Session cookie
- Returns: Battle ID, game configuration, and join details
GET /battle/active
GET /battle/active
Get active battlesLists all currently active (joinable or in-progress) battles.
- Auth: None
- Returns: Array of active battle objects
POST /battle/{id}/join
POST /battle/{id}/join
Join an active battleEnrolls the authenticated wallet into an existing battle.
- Auth: Session cookie
- Path params:
id— battle identifier - Returns: Battle state with participant list
Lottery
POST /round
POST /round
Create a lottery round (legacy)Creates a new lottery round. This is the original endpoint kept for backwards compatibility.
- Auth: Session cookie
- Returns: Round ID and configuration
POST /round/{id}/ticket
POST /round/{id}/ticket
Buy a lottery ticket (legacy)Purchases a ticket for an existing round.
- Auth: Session cookie
- Path params:
id— round identifier - Returns: Ticket number and transaction confirmation
POST /round/{id}/finalize
POST /round/{id}/finalize
Finalize a lottery round (legacy)Triggers the finalization and winner selection for a round.
- Auth: Session cookie
- Path params:
id— round identifier - Returns: Winning ticket, payout details
GET /round/{id}
GET /round/{id}
Get a lottery round (legacy)Retrieves metadata and status for a specific round.
- Auth: None
- Path params:
id— round identifier - Returns: Round object with status, entries, and prize pool
POST /chat/round
POST /chat/round
Create a chat-based lottery roundCreates a new chat-integrated lottery round where entries are submitted via the chat system.
- Auth: Admin token
- Returns: Round ID and configuration
GET /chat/round/active
GET /chat/round/active
Get the active chat roundReturns the currently active chat-based lottery round, if any.
- Auth: None
- Returns: Active round object or
null
GET /chat/round/{id}/entries
GET /chat/round/{id}/entries
Get entries for a chat roundReturns all entries submitted to a specific chat round.
- Auth: None
- Path params:
id— round identifier - Returns: Array of chat entry objects
POST /chat/round/{id}/start
POST /chat/round/{id}/start
Start a chat roundTransitions a chat round from pending to active, allowing entries.
- Auth: Admin token
- Path params:
id— round identifier - Returns: Updated round state
GET /chat/round/{id}/winning-numbers
GET /chat/round/{id}/winning-numbers
Get winning numbersReturns the winning numbers for a finalized chat round.
- Auth: None
- Path params:
id— round identifier - Returns: Winning number set and derivation proof
GET /chat/round/{id}/audit
GET /chat/round/{id}/audit
Get round audit trailReturns the full audit trail for a round including randomness source, entry hashes, and selection proof.
- Auth: None
- Path params:
id— round identifier - Returns: Audit object with cryptographic proofs
GET /chat/round/{id}/entries/root
GET /chat/round/{id}/entries/root
Get Merkle root of entriesReturns the Merkle root hash of all entries in a chat round for on-chain verification.
- Auth: None
- Path params:
id— round identifier - Returns: Merkle root hash
GET /chat/round/{id}/winners
GET /chat/round/{id}/winners
Get chat round winnersReturns the list of winners for a finalized chat round.
- Auth: None
- Path params:
id— round identifier - Returns: Array of winner objects with wallet and prize
GET /chat/round/{id}/payouts
GET /chat/round/{id}/payouts
Get round payout detailsReturns payout transaction details for a finalized round.
- Auth: None
- Path params:
id— round identifier - Returns: Payout status and transaction signatures
GET /chat/round/recent-finalized
GET /chat/round/recent-finalized
Get recently finalized roundsReturns a list of recently finalized chat rounds for display.
- Auth: None
- Returns: Array of finalized round summaries
GET /chat/status
GET /chat/status
Get chat system statusReturns the current status of the chat/lottery system, including connection health.
- Auth: None
- Returns: Status object with system health indicators
Leaderboards
GET /leaderboard/global
GET /leaderboard/global
Get global leaderboardReturns the cross-game global leaderboard combining points from all sources (games, quests, referrals).
- Auth: None
- Query params:
period—day,week,month, oryear;limit,offset - Returns: Ranked array of wallets with composite scores
GET /leaderboard/global/stats
GET /leaderboard/global/stats
Get global leaderboard statsReturns aggregate statistics for the global leaderboard (total participants, total points distributed, etc.).
- Auth: None
- Returns: Global stats summary object
GET /leaderboard/global/period-stats
GET /leaderboard/global/period-stats
Get period-based global statsReturns global stats scoped to a specific time period.
- Auth: None
- Query params:
period—day,week,month, oryear - Returns: Period-scoped stats object
GET /leaderboard/global/rank
GET /leaderboard/global/rank
Get current wallet’s global rankReturns the authenticated wallet’s rank on the global leaderboard.
- Auth: Session cookie
- Returns: Rank position, score, and percentile
GET /leaderboard/quests
GET /leaderboard/quests
Get quest leaderboardReturns a leaderboard ranked by social/quest points only (excludes game scores).
- Auth: None
- Returns: Ranked array of wallets with quest point totals
GET /leaderboard/quests/rank
GET /leaderboard/quests/rank
Get current wallet’s quest rankReturns the authenticated wallet’s rank on the quest leaderboard.
- Auth: Session cookie
- Returns: Rank position and quest point total
GET /leaderboard/quests/stats
GET /leaderboard/quests/stats
Get quest leaderboard statsReturns aggregate statistics for the quest leaderboard.
- Auth: None
- Returns: Quest leaderboard stats summary
Rewards
POST /api/rewards/claim
POST /api/rewards/claim
Claim a rewardSubmits a Merkle proof to claim a reward for a specific epoch. The proof is verified on-chain and tokens are transferred to the wallet.
- Auth: Session cookie
- Returns: Transaction signature and claim confirmation
GET /api/rewards/epoch/{epoch}/proof/{wallet}
GET /api/rewards/epoch/{epoch}/proof/{wallet}
Get reward proof for a walletReturns the Merkle proof needed to claim rewards for a specific epoch and wallet address.
- Auth: None
- Path params:
epoch— epoch number;wallet— Solana wallet address - Returns: Merkle proof, amount, and leaf index
GET /api/rewards/epoch/{epoch}
GET /api/rewards/epoch/{epoch}
Get reward epoch detailsReturns metadata for a specific reward epoch including totals, Merkle root, and status.
- Auth: None
- Path params:
epoch— epoch number - Returns: Epoch object with root, total, status, and timestamp
GET /api/rewards/epochs
GET /api/rewards/epochs
List all reward epochsReturns all reward epochs ordered by epoch number.
- Auth: None
- Returns: Array of epoch summary objects
GET /api/rewards/epochs/committed
GET /api/rewards/epochs/committed
List committed (on-chain) epochsReturns only epochs that have been committed on-chain, excluding those settled off-chain. Used post-go-live.
- Auth: None
- Returns: Array of committed epoch objects
GET /api/rewards/wallet/{wallet}/claimable
GET /api/rewards/wallet/{wallet}/claimable
Get claimable rewards for a walletReturns all unclaimed reward amounts across all epochs for the specified wallet.
- Auth: None
- Path params:
wallet— Solana wallet address - Returns: Array of claimable epoch/amount pairs
GET /api/rewards/wallet/{wallet}/claimable-epochs
GET /api/rewards/wallet/{wallet}/claimable-epochs
Get claimable epochs (filtered)Returns claimable epochs excluding off-chain settled ones. Used for the post-go-live claim UI.
- Auth: None
- Path params:
wallet— Solana wallet address - Returns: Filtered array of claimable epoch objects
GET /api/rewards/wallet/{wallet}/projected
GET /api/rewards/wallet/{wallet}/projected
Get projected rewards for todayReturns the estimated reward amount for today based on current leaderboard standing and pool size.
- Auth: None
- Path params:
wallet— Solana wallet address - Returns: Projected reward amount and calculation breakdown
GET /api/rewards/wallet/{wallet}/pending-usdc
GET /api/rewards/wallet/{wallet}/pending-usdc
Get pending USDC balanceReturns the pending (not yet claimed) USDC balance for a wallet.
- Auth: None
- Path params:
wallet— Solana wallet address - Returns: Pending USDC amount
GET /api/rewards/pool/today
GET /api/rewards/pool/today
Get today’s reward poolReturns the current day’s total reward pool size and distribution parameters.
- Auth: None
- Returns: Pool total, distribution curve, and timestamp
GET /config/rewards
GET /config/rewards
Get rewards configurationReturns the dynamic rewards configuration including total reward amounts and distribution rules.
- Auth: None
- Returns: Rewards config object
Referrals
GET /api/referral/link
GET /api/referral/link
Get referral linkReturns the referral link for the authenticated wallet. Creates one if it does not exist.
- Auth: Session cookie
- Returns: Referral link URL and code
POST /api/referral/link
POST /api/referral/link
Create referral linkExplicitly creates a new referral link for the authenticated wallet.
- Auth: Session cookie
- Returns: Referral link URL and code
POST /api/referral/bind
POST /api/referral/bind
Bind a referral codeBinds the authenticated wallet to a referrer using a referral code. A wallet can only be referred once.
- Auth: Session cookie
- Returns: Binding confirmation
GET /api/referral/summary
GET /api/referral/summary
Get referral summaryReturns a summary of the authenticated wallet’s referral activity (total referrals, points earned).
- Auth: Session cookie
- Returns: Referral count, total points earned from referrals
GET /api/referral/stats
GET /api/referral/stats
Get referral statsReturns detailed referral statistics for the authenticated wallet.
- Auth: Session cookie
- Returns: Detailed referral performance metrics
GET /api/referral/referred
GET /api/referral/referred
Get referred walletsReturns a list of wallets that were referred by the authenticated wallet.
- Auth: Session cookie
- Returns: Array of referred wallet addresses and timestamps
Profile & Daily Tasks
GET /api/profile
GET /api/profile
Get user profileReturns the profile for the authenticated wallet including points balance, rank, and linked accounts.
- Auth: Session cookie
- Returns: Profile object with balances, rank, and social links
GET /api/profile/beta-points
GET /api/profile/beta-points
Get beta points balanceReturns the beta (devnet) points balance for the authenticated wallet.
- Auth: Session cookie
- Returns: Beta points total and breakdown
GET /api/profile/beta-stats
GET /api/profile/beta-stats
Get beta statisticsReturns detailed beta-mode statistics for the authenticated wallet.
- Auth: Session cookie
- Returns: Beta stats object
GET /api/beta/preference
GET /api/beta/preference
Get beta mode preferenceReturns whether the authenticated wallet has opted into beta (devnet) mode.
- Auth: Session cookie
- Returns: Boolean preference flag
POST /api/beta/preference
POST /api/beta/preference
Set beta mode preferenceToggles the beta (devnet) mode preference for the authenticated wallet.
- Auth: Session cookie
- Returns: Updated preference
GET /api/tasks/daily
GET /api/tasks/daily
Get daily tasksReturns the list of daily tasks and their completion status for the authenticated wallet.
- Auth: Session cookie
- Returns: Array of task objects with completion state
POST /api/tasks/daily/complete
POST /api/tasks/daily/complete
Complete a daily taskMarks a daily task as completed for the authenticated wallet and awards associated points.
- Auth: Session cookie
- Returns: Points awarded and updated task state
GET /api/me/payments
GET /api/me/payments
Get my payment historyReturns USDC payment transactions for the authenticated wallet.
- Auth: Session cookie
- Returns: Array of payment objects with amounts and timestamps
GET /users/{wallet}/stats
GET /users/{wallet}/stats
Get public user statsReturns publicly visible stats for any wallet address.
- Auth: None
- Path params:
wallet— Solana wallet address - Returns: Public stats summary
Events & SSE
GET /events
GET /events
Subscribe to Server-Sent Events (SSE)Opens a persistent SSE connection for real-time event streaming. The server pushes events for new chat entries, lottery updates, battle results, and system notifications.
- Auth: None (public stream)
- Returns:
text/event-streamwith typed JSON payloads
new_entry— New chat lottery entry submittedchat_message— Chat message broadcast- Round state transitions, winner announcements, etc.
GET /events/burn/active
GET /events/burn/active
Get active burn eventReturns the currently active token burn event, if any.
- Auth: None
- Returns: Active burn event object or
null
POST /events/burn
POST /events/burn
Create a burn eventCreates a new token burn event with specified parameters.
- Auth: Session cookie
- Returns: Burn event ID and configuration
POST /events/burn/{id}/activate
POST /events/burn/{id}/activate
Activate a burn eventTransitions a burn event from pending to active.
- Auth: Session cookie
- Path params:
id— burn event identifier - Returns: Updated burn event state
GET /events/burn/{id}/leaderboard
GET /events/burn/{id}/leaderboard
Get burn event leaderboardReturns the overall leaderboard for a burn event ranked by total burn amount.
- Auth: None
- Path params:
id— burn event identifier - Returns: Ranked array of participants
GET /events/burn/{id}/leaderboard/referrals
GET /events/burn/{id}/leaderboard/referrals
Get burn referral leaderboardReturns the burn event leaderboard filtered to referral-sourced burns.
- Auth: None
- Path params:
id— burn event identifier - Returns: Ranked array by referral burns
GET /events/burn/{id}/leaderboard/game
GET /events/burn/{id}/leaderboard/game
Get burn game leaderboardReturns the burn event leaderboard filtered to game-sourced burns.
- Auth: None
- Path params:
id— burn event identifier - Returns: Ranked array by game burns
GET /events/burn/{id}/leaderboard/social
GET /events/burn/{id}/leaderboard/social
GET /events/burn/{id}/rank
GET /events/burn/{id}/rank
Get my burn event rankReturns the authenticated wallet’s rank within a burn event.
- Auth: Session cookie
- Path params:
id— burn event identifier - Returns: Rank position and burn total
GET /events/burn/{id}/quests
GET /events/burn/{id}/quests
Get burn event questsReturns quests associated with a specific burn event.
- Auth: None
- Path params:
id— burn event identifier - Returns: Array of event-scoped quest objects
Quests
GET /quests
GET /quests
List all questsReturns all available quests with their requirements and reward amounts.
- Auth: None
- Returns: Array of quest objects
GET /me/quests
GET /me/quests
Get my quest progressReturns quest completion status for the authenticated wallet.
- Auth: Session cookie
- Returns: Array of quests with per-wallet progress and completion state
GET /me/quest-multiplier
GET /me/quest-multiplier
Get quest multiplierReturns the current quest point multiplier for the authenticated wallet based on completed quests and streaks.
- Auth: Session cookie
- Returns: Multiplier value and contributing factors
GET /ledger/quests
GET /ledger/quests
Get quest ledgerReturns the full quest point ledger showing all quest point transactions for the authenticated wallet.
- Auth: Session cookie
- Returns: Array of ledger entries with quest ID, points, and timestamp
Social Integration
POST /integrations/twitter/events
POST /integrations/twitter/events
Twitter bot event webhookReceives webhook events from the Twitter/X bot integration. Used for tracking social engagement quests (retweets, follows, mentions).
- Auth: Webhook signature verification
- Returns:
200 OKacknowledgment
GET /social/round/{id}
GET /social/round/{id}
GET /social/latest
GET /social/latest
GET /social/round/{id}/post
GET /social/round/{id}/post
Clips
POST /clip/upload
POST /clip/upload
Upload a clipUploads a gameplay or stream clip. Triggers
clip_upload quest completion if applicable.- Auth: Session cookie
- Returns: Clip ID and upload confirmation
GET /clips
GET /clips
List clipsReturns uploaded clips, optionally filtered by game or wallet.
- Auth: None
- Returns: Array of clip objects with metadata
Eligibility & Configuration
GET /eligibility
GET /eligibility
Check token-gate eligibilityChecks whether the authenticated wallet meets the token-holding requirements for platform access.
- Auth: Session cookie
- Returns: Boolean eligibility status and token balance
GET /config/normalization
GET /config/normalization
Get normalization configReturns the current point normalization rules and score caps, exposed for frontend transparency.
- Auth: None
- Returns: Normalization parameters and cap values
GET /config/games
GET /config/games
Get games registryReturns the registry of all games and their category mappings.
- Auth: None
- Returns: Array of game objects with IDs, names, and categories
GET /api/price/sol
GET /api/price/sol
Get SOL/USD priceReturns a cached SOL/USD price. Provided as a convenience endpoint to avoid frontend CORS and rate-limit issues with external price APIs.
- Auth: None
- Returns:
{ "price": <float> }— SOL price in USD
GET /healthz
GET /healthz
Health checkReturns server health status. Used by load balancers and monitoring.
- Auth: None
- Returns:
200 OK
Wallet & Webhooks
POST /api/wallet/resolve
POST /api/wallet/resolve
Resolve a wallet addressResolves a wallet identifier (e.g. SNS domain, Twitter handle) to a Solana wallet address. Used internally by the bot to map user-friendly identifiers.
- Auth: None
- Returns: Resolved Solana wallet address
POST /webhooks/payment-status
POST /webhooks/payment-status
Payment status webhookReceives payment status updates from the Hyperlink orchestrator. Updates internal payment records.
- Auth: Webhook signature
- Returns:
200 OKacknowledgment
Admin
All admin endpoints require therequireAdminToken middleware. These are not intended for public consumption.
POST /admin/theme
POST /admin/theme
Update arcade themeSets the arcade visual theme and aesthetic parameters.
- Auth: Admin token
- Returns: Updated theme configuration
POST /admin/event
POST /admin/event
Trigger arcade eventTriggers a one-time arcade event (animation, announcement, etc.).
- Auth: Admin token
- Returns: Event acknowledgment
POST /admin/cabinet/possess
POST /admin/cabinet/possess
Possess a cabinetSets a cabinet to “possessed” state, assigning an AI character or entity to control it.
- Auth: Admin token
- Returns: Updated cabinet state
POST /admin/cabinet/release
POST /admin/cabinet/release
Release a cabinetReleases a cabinet from possessed state, returning it to normal operation.
- Auth: Admin token
- Returns: Updated cabinet state
POST /rewards/trigger-epoch
POST /rewards/trigger-epoch
Trigger a rewards epochManually triggers the daily rewards epoch generation. Normally run by the scheduler.
- Auth: Admin token
- Returns: Epoch creation confirmation
POST /auto/start
POST /auto/start
Start auto-schedulerStarts the automatic round scheduling system.
- Auth: Admin token
- Returns: Scheduler status
POST /auto/stop
POST /auto/stop
Stop auto-schedulerStops the automatic round scheduling system.
- Auth: Admin token
- Returns: Scheduler status
GET /auto/status
GET /auto/status
Get auto-scheduler statusReturns the current state of the automatic round scheduler.
- Auth: Admin token
- Returns: Scheduler running state and next scheduled time
POST /quests (admin)
POST /quests (admin)
Create a questCreates a new quest definition with requirements and reward configuration.
- Auth: Admin token
- Returns: Created quest object
GET /quests/{id} (admin)
GET /quests/{id} (admin)
Get quest by IDReturns full quest details including internal configuration.
- Auth: Admin token
- Path params:
id— quest identifier - Returns: Quest object with admin-level detail
PATCH /quests/{id}
PATCH /quests/{id}
Update a questPartially updates a quest definition.
- Auth: Admin token
- Path params:
id— quest identifier - Returns: Updated quest object
DELETE /quests/{id}
DELETE /quests/{id}
Delete a questRemoves a quest definition.
- Auth: Admin token
- Path params:
id— quest identifier - Returns:
204 No Content
POST /admin/quests/{id}/complete
POST /admin/quests/{id}/complete
Manually complete a quest for a userAdmin override to mark a quest as completed for a specific wallet.
- Auth: Admin token
- Path params:
id— quest identifier - Returns: Completion confirmation
POST /api/rewards/settled-offchain
POST /api/rewards/settled-offchain
Mark epochs settled off-chainMarks specified epochs as having been settled off-chain (e.g. direct transfer). Idempotent.
- Auth: Admin token
- Returns: Updated epoch settlement status
POST /api/rewards/epoch/import
POST /api/rewards/epoch/import
Import reward epoch distributionImports a pre-computed distribution blob from an external job into the rewards system.
- Auth: Admin token / internal
- Returns: Import confirmation with epoch number
POST /api/beta/convert
POST /api/beta/convert
Convert beta pointsConverts beta (devnet) points to mainnet points for a wallet.
- Auth: Admin token
- Returns: Conversion result
GET /debug/points
GET /debug/points
Debug points visibilityDiagnostic endpoint showing both beta and regular point balances for the authenticated wallet.
- Auth: Session cookie
- Returns: Dual-mode points breakdown
Error Responses
All endpoints return errors in a consistent JSON format:| Status Code | Meaning |
|---|---|
400 | Bad request — missing or invalid parameters |
401 | Unauthorized — missing or invalid session |
403 | Forbidden — insufficient permissions (e.g. admin-only) |
404 | Not found — resource does not exist |
409 | Conflict — duplicate action (e.g. already claimed, already bound) |
500 | Internal server error |
Rate Limiting
The API does not currently enforce per-IP rate limits at the application layer, but is fronted by infrastructure-level protections. Excessive request volume may result in temporary throttling. Be respectful with polling intervals — prefer the SSE stream atGET /events for real-time updates.