Copy page

Automation & management

PokerDeck poker rooms

During beta, a room is a PokerDeck poker room: a hosted private-poker container for a company, club, friend group, or community organiser. A room gives the organiser a durable hosted-poker home for later tournaments, recipes, webhooks, and tournament result automation while PokerWorks remains the authoritative runtime.

The API resource is named room so the same PokerWorks Management API can later support other first-party surfaces, but the product you are managing today is a PokerDeck poker room.

Room management is a Management API contract. Call it from trusted server code with a service-account management token (pw_mgmt_...), never from browser code.

What you can automate now

Use the Management API room endpoints when you need to:

• create or select a default test room for a project/environment;
• update room display details, allowed origins, and basic branding;
• discover approved tournament presets, blind structures, and payout structures;
• create tournament records from approved presets;
• publish, schedule, cancel, or archive test-mode tournaments;
• read the room member directory through public room-scoped member and player IDs;
• create pending player invitations without exposing raw email in responses;
• read tournament entry/admission rows through public tournament entry and participant IDs;
• attach synthetic playground tournament result verification to a published or scheduled tournament;
• route tournament.completed webhooks into Discord, Sheets, support, or your own back office.

The Console Rooms page is the human setup and evidence surface for the same resources. Use it to confirm project origins, room automation token coverage, tournament.completed webhook readiness, room/tournament status, tournament result links, and support evidence ids. Console is read-only for room lifecycle operations in this beta slice; create and publish calls run through documented Management API HTTP contracts with scoped management tokens.

Naming boundary

Use room in public contracts, future SDK/MCP tools, and IDs. In prose, say PokerDeck poker room when you need the product context. Internal PokerWorks runtime code may map that room to a tenant, but public responses expose roomId, never tenantId.

Scopes

Create a service-account token with the narrow room scopes it needs:

Scope	Grants
rooms:read	List and read rooms visible to the token.
rooms:create	Create a room for an allowed project and environment.
rooms:update	Update room name, slug, allowed origins, or basic branding.
rooms:archive	Archive a room.
room_invitations:create	Create pending player invitations for visible rooms.
tournaments:read	List and read tournaments in visible rooms.
tournaments:create	Create tournaments from approved presets.
tournaments:update	Update safe draft or scheduled tournament fields.
tournaments:publish	Publish or schedule test-mode tournaments. Live publish is gated.
tournaments:cancel	Cancel draft, scheduled, or published tournaments.
tournaments:archive	Archive draft or cancelled tournaments.
ring_games:read	List and read room-scoped ring-game catalog projections.

Project and environment restrictions apply in addition to these scopes. A token restricted to one test project cannot create, read, update, archive, or publish tournaments in live mode or in another project.

Beta limits

Test-mode Room automation is self-serve but bounded:

Limit	Default
Active Rooms per project/environment	5
Non-archived tournaments per Room	25
Published or scheduled tournaments per Room	3

Quota failures return typed RATE_LIMIT_EXCEEDED errors with the quota name, current count, and limit in the error details. Idempotent replays and selecting an existing default Room do not create new resources or consume additional quota.

Examples that publish test tournaments cancel them after reading tournament result verification so repeated runs do not fill the published/scheduled-tournament quota. For your own tests, archive draft/cancelled tournaments or cancel published test tournaments when you no longer need them active.

Live Room and tournament writes are product-access allowlisted in beta. Reads remain scoped by the management token, but creating, updating, publishing, cancelling, or archiving live Rooms and tournaments requires the live controls named in Access & limits: allowed origins, plan entitlement, billing or receipt proof, hosted-runtime quota, usage metering, support audit, and a first-live product-access allowlist.

Current coverage

The Management API is the automation surface for operating a PokerDeck poker room. Beta exposes the safe first slice of that operator control plane:

Area	Beta API posture
Rooms	Published Management API resource.
Projects and product keys	Published developer-platform resources for integrations, environments, credentials, webhooks, usage, and restrictions.
Tournaments	Published Management API resource for tournament-style private poker nights and Sit & Go presets.
Tournament catalog	Published read-only catalog for approved tournament presets, blind structures, and payout/prize structures.
Tournament results and verification	Published through current result verification reads and playground completion fixtures; richer result reads remain reserved until admitted.
Members and players	Published read-only room member directory plus pending player invitation creation. Role changes, removals, bulk invites, email delivery, raw auth ids, and browser widgets remain reserved.
Tournament entries	Published read-only tournament entry/admission projection. Raw registration ids, player ids, seats, table state, and action state remain reserved.
Standings and recap reads	Reserved/read-first. Needs completed recap projection authority, redaction, DSAR/account-closure behavior, and freshness evidence.
Lobbies	Guide-owned runtime/read surface today; not a standalone Management API resource.
Ring games and waitlists	Published read-only room ring-game catalog projection; ring-game creation, lifecycle, waitlists, seats, live stacks, and Table Protocol remain reserved.
Tables and player actions	Reserved for future certified Game Server / Table Protocol; never raw deck, card, action, or settlement APIs.

For the broader map of room operators, branded-site partners, tournament organizers, tool builders, and future custom-client builders, see Choose your API path.

Create a room

Code
curl https://api.pokerworks.io/api/v1/management/rooms \
  -X POST \
  -H "Authorization: Bearer $POKERWORKS_MANAGEMENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: demo" \
  -d '{
    "projectId": "devproj_...",
    "environment": "test",
    "name": "Northgate Friday Poker",
    "slug": "northgate-friday-poker",
    "allowedOrigins": ["https://poker.northgate.example"],
    "defaultRoom": true,
    "branding": {
      "displayName": "Northgate Friday Poker",
      "accentColor": "#146EF5"
    }
  }'

The public-clean examples/developer-platform/tournament-automation example shows the same server-side flow without importing private PokerWorks workspace packages.

Successful responses return a public room resource:

Code
{
  "room": {
    "roomId": "pw_room_...",
    "organizationId": "org_...",
    "projectId": "devproj_...",
    "environment": "test",
    "name": "Northgate Friday Poker",
    "slug": "northgate-friday-poker",
    "allowedOrigins": ["https://poker.northgate.example"],
    "branding": {
      "displayName": "Northgate Friday Poker",
      "accentColor": "#146EF5"
    },
    "isDefault": true,
    "status": "active",
    "archivedAt": null,
    "support": {
      "evidenceId": "pwsup_pw_room_...",
      "projectId": "devproj_...",
      "roomId": "pw_room_..."
    },
    "createdAt": "2026-06-04T12:00:00.000Z",
    "updatedAt": "2026-06-04T12:00:00.000Z"
  }
}

defaultRoom: true is idempotent by policy: if the project/environment already has an active default room, PokerWorks returns that existing default room rather than creating a second one. Omit x-idempotency-key when using default-room create-or-select after the default already exists; a key can only replay the original room creation request that stored it.

Read and update rooms

Code
GET   /api/v1/management/rooms?projectId=devproj_...&environment=test
GET   /api/v1/management/rooms/{roomId}
PATCH /api/v1/management/rooms/{roomId}
POST  /api/v1/management/rooms/{roomId}/archive

Invite players

Create pending player invitations from trusted server code with a token that has room_invitations:create:

Code
curl https://api.pokerworks.io/api/v1/management/rooms/pw_room_.../invitations \
  -X POST \
  -H "Authorization: Bearer $POKERWORKS_MANAGEMENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "player@example.com",
    "role": "player"
  }'

Responses return a public pw_room_invitation_... id, pending status, support evidence, and a redacted contact hint. Raw email, auth user ids, tenant ids, player ids, cross-brand identity links, email delivery state, and invitation acceptance are not exposed by this route. Replaying the same room/email/role while the invitation is pending returns the same pending invitation; accepted, revoked, or expired invitations conflict instead of being reset.

Allowed origins on a room must stay within the owning project's allowed origins. Updating a room cannot widen browser access beyond the project boundary.

Read room members

Code
GET /api/v1/management/rooms/{roomId}/members?limit=50

Room member reads are a server-side Management API projection for hosts and back-office tools. They return public room-scoped memberId and playerId values, display-safe profile fields, role, status, timestamps, and support metadata for the room visible to the management token.

This endpoint does not expose email addresses, raw auth user ids, internal player ids, cross-brand identity links, invitations, role changes, removals, or live table state. Browser widgets must still call your server or wait for a future browser-safe public read contract.

Read room ring games

Code
GET /api/v1/management/rooms/{roomId}/ring-games?limit=50
GET /api/v1/management/rooms/{roomId}/ring-games/{ringGameId}

Room ring-game reads are a server-side Management API projection for hosts, dashboards, and back-office setup tools. They return public pw_ring_game_... ids plus catalog-safe fields such as name, status, play-money/social economy mode, blind/buy-in display values, publication posture, presentation mode, trust mode, and support metadata for ring games owned by the room authority.

These endpoints are read-only. They do not create, publish, pause, archive, or operate ring games; they do not expose raw ring_games.id values, tenant ids, table ids, waitlist membership, seats, player ids, live stacks, HUD data, private cards, deck/RNG state, action state, bot-seat control, real-money economy, rake, cashout, or Table Protocol. Browser widgets must call your server or wait for a future browser-safe signed read contract.

Discover tournament presets

Before creating tournaments, read the approved catalog. Use the aggregate endpoint when you want to bootstrap a room setup screen in one call:

Code
GET /api/v1/management/tournament-catalog

Use the resource endpoints when your integration wants to cache, inspect, or link directly to one part of the setup catalog:

Code
GET /api/v1/management/tournament-presets
GET /api/v1/management/tournament-presets/{presetKey}
GET /api/v1/management/blind-structures
GET /api/v1/management/blind-structures/{blindStructureId}
GET /api/v1/management/payout-structures
GET /api/v1/management/payout-structures/{payoutStructureId}

The catalog resources return:

• tournamentPresets: approved presetKey values accepted by POST /management/tournaments;
• blindStructures: read-only blind schedules for planning and display;
• payoutStructures: read-only prize/payout structures for planning and display.

Approved catalog structures remain read-only, while room-owned custom blind and payout structures can be authored through the Management API and attached to tournament creation. Those structures are enough to create approved PokerDeck tournaments and explain the blind schedule or payout plan before a host publishes. Paid custom template authoring remains a separate Management write slice until template validation, provenance, versioning, entitlement, and operator-authority contracts are admitted. Guarantee, bounty, satellite, deal, and prize-fulfillment authoring require separate economy and integrity admission.

PokerWorks Lab tools can generate blind schedules and payout ladders today. A server-side integration can submit those structures through the custom authoring endpoints and record provenance as pokerworks_lab or, after the planned product maturity rename, pokerworks_tools.

Create a tournament

Tournaments are the tournament-style unit for automation: they have a lifecycle, can later produce a tournament.completed webhook, and expose tournament result verification discovery without exposing cards, deck order, player actions, or settlement authority.

Use a presetKey from GET /api/v1/management/tournament-presets or GET /api/v1/management/tournament-catalog. The beta presets are six_max_nlhe_sng_v1, a play-money six-max NLHE Sit & Go/private poker-night shape, and scheduled_mtt_nlhe_v1, a scheduled no-limit Hold'em multi-table tournament shape.

Code
TOURNAMENT_PRESET=six_max_nlhe_sng_v1

curl https://api.pokerworks.io/api/v1/management/tournaments \
  -X POST \
  -H "Authorization: Bearer $POKERWORKS_MANAGEMENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: demo" \
  -d '{
    "name": "Friday Poker Night",
    "presetKey": "'"$TOURNAMENT_PRESET"'",
    "roomId": "pw_room_...",
    "schedule": {
      "startsAt": "2026-06-05T19:30:00.000Z",
      "timezone": "Europe/London"
    }
  }'

Room-owned custom structures can be attached during creation:

Code
{
  "blindStructureId": "pw_blind_structure_...",
  "name": "Friday Poker Night",
  "payoutStructureId": "pw_payout_structure_...",
  "presetKey": "scheduled_mtt_nlhe_v1",
  "roomId": "pw_room_..."
}

Tournament endpoints:

Code
GET   /api/v1/management/tournaments?roomId={roomId}
POST  /api/v1/management/tournaments
GET   /api/v1/management/tournaments/{tournamentId}
PATCH /api/v1/management/tournaments/{tournamentId}
POST  /api/v1/management/tournaments/{tournamentId}/publish
POST  /api/v1/management/tournaments/{tournamentId}/cancel
POST  /api/v1/management/tournaments/{tournamentId}/archive
GET   /api/v1/management/tournaments/{tournamentId}/entries

Test-mode tournaments can be published or scheduled as control-plane records until the per-Room concurrency limit is reached. Live tournament writes stay gated behind the beta product-access allowlist; broad live provisioning is not self-serve yet.

Read tournament entries

Code
GET /api/v1/management/tournaments/{tournamentId}/entries?limit=50

Tournament entry reads expose the registration/admission rows for a materialized tournament through public entryId and publicParticipantId values. The endpoint is for host dashboards, back-office automation, and server-rendered widgets that need to show who has entered a tournament without handling raw registration ids, auth user ids, player ids, emails, seats, cards, table state, or actions.

If the control-plane tournament has not materialized a source tournament yet, the endpoint fails closed with READ_MODEL_NOT_READY instead of returning a fake-empty list.

Attach test tournament result verification

After a test tournament is published or scheduled, the developer playground can attach its frozen completion fixture to that tournament. The management token needs playground:write, tournament_results:read, and tournaments:update. This does not run live gameplay or settle a real tournament; it binds synthetic, public-safe tournament result data to the tournament so recipes can prove the output loop:

Code
curl https://api.pokerworks.io/api/v1/management/playground/tournament-completion \
  -H "Authorization: Bearer $POKERWORKS_MANAGEMENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "devproj_...",
    "fixture": "completed-six-max-nlhe-v1",
    "tournament": {
      "roomId": "pw_room_...",
      "tournamentId": "pw_tournament_..."
    }
  }'

The response includes the usual playground, webhookEvent, webhook delivery summaries, and results payload. When tournament is supplied, it also includes the updated tournament with:

• output.results.available: true;
• output.results.tournamentId set to the public pw_tournament_... id;
• links.resultsUrl pointing at the management tournament result verification read.

Webhook receivers still consume tournament.completed and follow links.results.href; the Room tournament output gives organisers and agents a stable tournament record that points at the same certified result.

What rooms do not do yet

Rooms do not expose player seating, player actions, cards, random-number generation, shuffle/deal primitives, raw tournament structure authoring, custom gameplay clients, or settlement authority. Tournaments expose bounded preset lifecycle management only; tournament-result verification reads and tournament.completed remain the output path after completion.

Room member directories, tournament entries, and room leaderboards are published Management reads. Standings beyond the published leaderboard pack, aggregate room stats, and browser-callable widget-safe summaries remain reserved read-first surfaces. During beta, build website, Discord, stream, or sponsor widgets from your trusted server using room member reads, tournament entry reads, room leaderboard reads, webhooks, and tournament-result verification reads. Never embed a management token or product key in widget code.

When a widget or public page displays PokerWorks output, follow Public Data Use And Brand Rules: use documented reads only, preserve the public/private visibility tier, avoid scraping first-party pages, and do not imply unsupported PokerWorks/PokerDeck partnership or certification.

Public widgets and room summaries must also follow Public read freshness: declare their freshness class, stale ceiling, cache behavior, and visibility tier before they are presented as browser-callable beta surfaces.

Related

• Service accounts & management tokens
• Webhooks
• Demo room provisioning
• Tournament results & verification
• Public Data Use And Brand Rules
• Public read freshness
• Recipes