ggbucks.docs
Developer portal

Developer

Page through linked players or reward decisions

Choose players or events, then optionally constrain organization, project and game. Membership is checked on each page. Return newest records first by creation time and UUID; nextCursor is opaque and bound to the original kind and filters. Keep the same filters until nextCursor is null. Changing scope requires starting without a cursor. Unknown or repeated query parameters are rejected.

GET/api/developer/v1/records

Authentication

Invited developer session

An invited developer Clerk session issued through https://developers.ggbucks.com with a verified primary email and active immutable subject binding. Game keys do not authorize the console. Organization membership and role are checked separately.

# Illustrative request only. Replace IDs/tokens; events need a current occurredAt.
# Native examples require an already admitted native session/device permit.
curl --fail-with-body --max-time 15 -X GET \
  "https://api.ggbucks.com/api/developer/v1/records?kind=players&limit=50" \
  -H "Authorization: Bearer ${GGBUCKS_DEVELOPER_SESSION}"

Illustrative examples; replace placeholders. Use your approved developer portal session. Game keys do not authorize console requests.

Parameters

kindqueryrequired

Choose the player or event collection.

"players" | "events"
organizationIdqueryoptional

Optional organizationId filter.

string · uuid
projectIdqueryoptional

Optional projectId filter.

string · uuid
gameIdqueryoptional

Optional gameId filter.

string · uuid
cursorqueryoptional

Opaque nextCursor from the previous page with unchanged kind and filters.

string
limitqueryoptional

Page size, default 50, maximum 100.

integer

Responses

200Successful sandbox response.

application/json

{
  "data": {
    "kind": "players",
    "nextCursor": null,
    "records": [
      {
        "createdAt": "2026-10-11T12:00:00.000Z",
        "externalPlayerId": "studio-player-42",
        "gameId": "11111111-1111-4111-8111-111111111111",
        "ggbucksUserId": null,
        "id": "11111111-1111-4111-8111-111111111111",
        "linkedAt": null,
        "organizationId": "11111111-1111-4111-8111-111111111111",
        "username": null
      }
    ]
  }
}
dataobjectrequired
  • Unknown fields are rejected
Show nested fields
kind"events" | "players"required
nextCursornull | stringrequired
Show nested fields

Accepted shape 1

null

Accepted shape 2

string
recordsobject | object[]required
Show item fields

Accepted shape 1

createdAtstring · date-timerequired
externalPlayerIdstringrequired
  • At least 1 characters
  • Up to 200 characters
  • Pattern: ^[^\u0000-\u001f\u007f]*$
gameIdstring · uuidrequired
ggbucksUserIdnull | string · uuidrequired
idstring · uuidrequired
linkedAtnull | string · date-timerequired
organizationIdstring · uuidrequired
usernamenull | stringrequired

Unknown fields are rejected.

Accepted shape 2

createdAtstring · date-timerequired
eventIdstring · uuidrequired
eventTypestringrequired
  • Up to 64 characters
  • Pattern: ^[a-z][a-z0-9_.-]{0,63}$
gameIdstring · uuidrequired
idstring · uuidrequired
occurredAtstring · date-timerequired
organizationIdstring · uuidrequired
playerIdstring · uuidrequired
reason"daily_player_cap" | "game_budget_exhausted" | "game_paused" | "game_payout_ceiling" | "player_not_linked" | "project_budget_exhausted" | "project_payout_ceiling" | "rate_limited" | "timestamp_out_of_window" | "unknown_or_inactive_rule" | "user_unavailable" | nullrequired
rewardGgbucksintegerrequired

Integer sandbox TEST ggbucks. 1,000 units represent one test dollar.

  • Minimum 0
  • Maximum 1,000,000,000,000
status"accepted" | "rejected"required

Unknown fields are rejected.

Unknown fields are rejected.

Unknown fields are rejected.

400Invalid request or allocation/cap constraint.

application/json

errorobjectrequired
  • Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

401Missing or invalid credential/token.

application/json

errorobjectrequired
  • Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

403Admission or organization permission denied.

application/json

errorobjectrequired
  • Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

404Scoped resource not found.

application/json

errorobjectrequired
  • Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

409Replay conflict, expired link or incompatible resource state.

application/json

errorobjectrequired
  • Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.

503Platform disabled or admission/database dependency temporarily unavailable; no successful mutation is implied.

application/json

errorobjectrequired
  • Unknown fields are rejected
Show nested fields
code"AUTH_UNAVAILABLE" | "DEVELOPER_ACCESS_UNAVAILABLE" | "DEVELOPER_INVITATION_REQUIRED" | "EMAIL_VERIFICATION_REQUIRED" | "INVALID_CONTENT_TYPE" | "INVALID_CURSOR" | "INVALID_PLAYER" | "INVALID_PUBLIC_KEY" | "INVALID_RECORD_QUERY" | "INVALID_REQUEST" | "INVALID_SESSION_ORIGIN" | "PAYLOAD_TOO_LARGE" | "PLATFORM_DISABLED" | "PLATFORM_UNAVAILABLE" | "UNAUTHORIZED" | "already_linked" | "conflict" | "event_conflict" | "forbidden" | "game_limit" | "game_paused" | "insufficient_funds" | "invalid_action" | "invalid_event" | "invalid_key" | "invalid_link" | "invalid_metadata" | "invalid_player" | "limit_exceeded" | "link_disabled" | "not_found" | "owner_immutable" | "project_limit" | "retry_later" | "secret_key_required" | "unauthorized" | "unlimited_funding" | "user_unavailable"required
messagestringrequired

Unknown fields are rejected.

Unknown fields are rejected.