Campaigns API

Endpoints authenticated by Campaign API Keys. Include headers:

  • Authorization: Bearer <campaign_api_key>
  • X-Oncade-API-Version: v1
  • X-Campaign-Id: <campaignId>

GET /api/v1/campaign/[id]

Get details for a specific campaign (scoped to the key's campaign). Returns campaign status plus deployment details.

Response body includes:

  • campaign: object with fields id, name, environment, status, businessId, address, createdAt, updatedAt, totalAmountFunded, totalAmountPaidOut, availableToWithdraw.

PUT /api/v1/campaign/[id]/stop

Freeze the campaign. Returns 202 (Accepted) and enqueues a background job. A webhook will be emitted when stopped.

PUT /api/v1/campaign/[id]/start

Activate the campaign. Returns 202 (Accepted) and enqueues a background job. A webhook will be emitted when started.

POST /api/v1/campaign/[id]/events

Enqueue a campaign event for a linked user. Provide eventCode and the approveduserRef from the linking flow in the JSON body. Returns 202 (Accepted) and enqueues a background job.

Response: { success: true, message: 'Event enqueued' }

Error response: { success: false, error: '...' }

Headers must include Authorization, X-Oncade-API-Version: v1, and X-Campaign-Id. For POST requests we recommend an Idempotency-Key.

curl -s -X POST \
  -H "Authorization: Bearer $CAMPAIGN_KEY" \
  -H "X-Oncade-API-Version: v1" \
  -H "X-Campaign-Id: $CID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"eventCode":"quest_complete","userRef":"link_usr_123"}' \
  https://oncade.gg/api/v1/campaign/$CID/events

GET /api/v1/campaign/[id]/events

List configured campaign events (code, name, payoutAmount).

Response: { success: true, events: [{ code, name, payoutAmount }] }

POST /api/v1/campaign/[id]/users/link/initiate

Begin the email-based account linking flow for a campaign. Provide the player's email in the JSON body and include anIdempotency-Key header so retries reuse the same session. Returns 201 Created, sets theLocation header to the approval URL, and returns a body with { url, sessionKey }. If a pending unexpired session already exists for the same email, returns 200 with the same body.

GET /api/v1/campaign/[id]/users/link/details

Poll the status of a campaign link session using the sessionKey. When approved it returns the transformeduserRef that should be used for campaign events.

POST /api/v1/campaign/[id]/withdraw

When stopped, request to send remaining funds back to the business funding wallet. Returns 202 (Accepted) and enqueues a background job. A webhook will be emitted upon completion.

GET /api/v1/campaign/[id]/user/[userId]

Get user-specific details for this campaign.

GET /api/v1/campaign/[id]/users

Returns a paginated list of users linked to this campaign. Authenticated via campaign API key.

Query parameters:

  • page (optional, default 1)
  • limit (optional, default 20, max 100)

Response:

{
  "users": [
    { "linkId": "link_abc123", "userRef": "usr_xyz789", "email": "player@example.com", "name": "Player One", "linkedAt": "2025-01-15T12:00:00.000Z" }
  ],
  "pagination": { "page": 1, "limit": 20, "totalCount": 1, "totalPages": 1, "hasNextPage": false, "hasPrevPage": false }
}

DELETE /api/v1/campaign/[id]/users/[userId]

Removes a linked user from a campaign by their userRef (transformed user ID). Authenticated via campaign API key.

Response: { "success": true }

Errors:

  • 404 - User reference not found or no active link for this user

Link Invites

Use link invites as a growth tool for rewards onboarding. You can create channel-specific links, track usage, and control distribution with expiration, max-use limits, and pause/revoke lifecycle states.

Link invites are shareable codes that generate account linking sessions on each visit. Share the resulting URL (e.g. https://oncade.gg/join/<code>) via email, social media, or any channel. Each visitor gets their own unique linking session.

POST /api/v1/campaign/[id]/link-invites

Create a new link invite for the campaign. Returns 201 Created with aLocation header pointing to the invite URL.

Body (all fields optional):

  • label (string, max 120 chars) — human-friendly name for tracking
  • maxUses (integer, 1–1,000,000) — limit total redemptions, omit for unlimited
  • expiresAt (ISO 8601 date string) — when the invite expires, omit for never
curl -s -X POST \
  -H "Authorization: Bearer $CAMPAIGN_KEY" \
  -H "X-Oncade-API-Version: v1" \
  -H "X-Campaign-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{"label":"Email blast Feb 2026","maxUses":500}' \
  https://oncade.gg/api/v1/campaign/$CID/link-invites

GET /api/v1/campaign/[id]/link-invites

List all link invites for the campaign. Add ?includeRevoked=true to include revoked invites.

Response: { invites: [{ code, label, status, maxUses, currentUses, expiresAt, url, ... }] }

PATCH /api/v1/campaign/[id]/link-invites/[code]

Update a link invite. You can change label, maxUses,expiresAt, or status (set to "active" or "paused").

DELETE /api/v1/campaign/[id]/link-invites/[code]

Permanently revoke a link invite. Revoked invites can no longer be used.

See also: API Reference