Copy page

Reference & support

Changelog

2026-06-12

• Room ring-game catalog reads. Added GET /api/v1/management/rooms/{roomId}/ring-games and GET /api/v1/management/rooms/{roomId}/ring-games/{ringGameId} for service-account callers with ring_games:read. Responses use public pw_ring_game_... ids and room-scoped catalog fields only. Ring-game creation, publish/archive lifecycle, table spawn, waitlists, seats, live stacks, bot seats, raw table ids, real-money economy, and Table Protocol remain reserved.
• Tournament schedule occurrence preview. Added GET /api/v1/management/tournament-schedules/{tournamentScheduleId}/occurrences for service-account callers with tournament_schedules:read. The endpoint returns public-safe, deterministic preview slots with pw_tournament_occurrence_... ids, local/UTC schedule timestamps, ordinal, schedule and room ids, and explicit not_materialized status. Preview ids are generated from public schedule recurrence; they do not expose raw internal series, occurrence, instance, table, card, action, or tenant ids, and they do not imply a generated tournament run yet.
• Demo room durable recurrence proof. The demo-room provisioning example now uses the public Management schedule endpoints for recurrence-shaped prompts. It creates a durable tournament_schedule, reads deterministic occurrence previews, records not_materialized posture, and keeps result/webhook attachment for generated schedule runs as an explicit reserved gap. It no longer expands daily/weekday/weekly prompts into extra one-shot tournament samples.
• Tournament schedule authoring. Added durable public Management schedule projections: POST /api/v1/management/tournament-schedules, GET /api/v1/management/tournament-schedules, and GET /api/v1/management/tournament-schedules/{tournamentScheduleId}. Service-account callers with tournament_schedules:create or tournament_schedules:read can store recurring tournament intent for a Room using public pw_tournament_schedule_... ids, approved/custom blind and payout structures, and human_only trust mode. This is schedule intent only: materialization and result/webhook attachment for generated runs remain reserved.
• Demo room trust integrity proof. The demo-room provisioning recipe now surfaces result integrity evidence in its output/proof bundle, including trustMode, bot allowance, declared bot-seat count, and the Developer Integrity Rules reference from the public tournament result read. The public beta demo remains human_only: non-human trust modes are rejected before API calls, and missing or incomplete result integrity evidence fails the proof instead of being normalized into safe-looking claims. Bot seats, bot_only, mixed_declared, and Table Protocol remain reserved.
• Tournament schedule recurrence admission split. Reviewed the internal tournament recurrence pipeline and split public admission into durable schedule intent, deterministic occurrence preview, and later materialization. Public Management schedules and occurrence preview ids are now the admitted contract; raw series, occurrence, instance, source tournament, table, card, and action ids remain blocked.

2026-06-11

• Ring-game Management admission deferred. Reviewed the existing first-party tenant/admin ring-control surfaces and kept public Management ring games reserved for beta. The public registry now records the future ring_game_management family as a service-account projection that must mint pw_ring_game_... ids before any public routes are admitted; raw ring-game ids, table ids, tenant ids, waitlist/player data, live table state, economy internals, bot policy, and Table Protocol concerns remain blocked. Follow-up tasks now split the work into read-only room catalog projection, lifecycle write authority, and runtime/privacy readiness.
• Room invitation writes. Added POST /api/v1/management/rooms/{roomId}/invitations for server-side Management API automation. Service-account callers with room_invitations:create can create or replay pending player invitations for a Room through the existing room identity authority. Responses expose public pw_room_invitation_... ids, pending status, redacted email hints, and support evidence without raw emails, auth org ids, tenant ids, internal player ids, or cross-brand identity links. Terminal accepted, revoked, and expired invitations conflict instead of resetting to pending; email delivery, acceptance flows, role changes, removals, bulk invites, player search, browser widgets, and player /me remain reserved.

2026-06-09

• Demo room schedule expansion. The demo-room provisioning example now turns recurrence-shaped prompts such as "daily for a week", "every weekday at noon", or "every Friday night" into bounded one-shot scheduled tournament samples through the existing Management tournament create/publish routes. The output and proof bundle expose a schedulePlan so agents can verify requested versus generated samples, including public-beta quota truncation, while true series/occurrence recurrence remains a reserved API gap.
• Demo room proof bundle. The demo-room provisioning example can now write a durable pokerworks.demo_room_provisioning.proof.v1 JSON artifact with POKERWORKS_DEMO_PROOF_OUTPUT or --proof-output. The bundle records exercised public Management API surfaces, room/tournament/structure ids, support evidence, cleanup/revoke guidance, viewability status, security posture, and machine-readable reserved gaps without exposing management tokens, raw prompt text, private cards, RNG/deck state, or action transcripts.
• Demo room capability prompts. The demo-room provisioning example now accepts a deterministic capability prompt so agents can ask for a neutral room shape, such as private poker night, scheduled tournaments, leaderboards, member widgets, ring-game interest, or declared-bot policy, before the script calls the public Management API. Competitor references are treated only as capability-shape hints and are redacted from stdout, generated names, slugs, labels, and API payloads; reserved requests are reported as explicit gaps instead of private demo bypasses.
• Local Management MCP dogfood parity. Updated the local Management API MCP adapter used by first-party dogfood agents so it mirrors the demo-room provisioning flow: room widget reads, room-owned blind and payout structure authoring, tournament result exports, scheduled MTT presets, trust-mode fields, and custom structure IDs now delegate through the public Management API client. The MCP page now clarifies that the adapter is local/private-beta only, keeps management tokens server-side, and does not expose raw gameplay authority or private demo bypasses.
• Management room viewability. Management API-created PokerDeck rooms now include links.lobbyUrl and links.dashboardUrl in room responses so server-side provisioning scripts can hand off to the real PokerDeck UI. The demo-room provisioning recipe now treats browser proof of the generated PokerDeck lobby as required evidence and keeps Management API tokens server-side; owners sign in through normal PokerDeck authentication. Room slugs are now limited to the DNS-label-safe 63 character maximum because they become PokerDeck tenant hostnames.

2026-06-08

• Management custom tournament structures. Added room-owned blind and payout structure authoring to the public Management API: POST /api/v1/management/blind-structures, PATCH /api/v1/management/blind-structures/{blindStructureId}, POST /api/v1/management/payout-structures, and PATCH /api/v1/management/payout-structures/{payoutStructureId}. Approved catalog structures remain read-only; custom writes require tournament_structures:create or tournament_structures:update, include optional provenance for manual, PokerWorks Lab, or future PokerWorks Tools imports, and reject payout tables whose paid positions exceed maxPlayers.
• Management catalog resource reads. Added resource-level Management API reads for the approved tournament setup catalog: 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, and GET /api/v1/management/payout-structures/{payoutStructureId}. The aggregate GET /api/v1/management/tournament-catalog remains the bootstrap read for room setup screens; paid-host custom preset, blind-structure, and payout-structure authoring is planned as a separate Management write slice once validation, provenance, versioning, and entitlement gates are admitted.
• Product-key internal convergence. Completed the pre-beta internal cut from legacy API-key storage and support nouns to product-key language while keeping public Management API product-key routes and scopes stable. The public exposure registry now treats stale apiKey/api_keys/bearer API-key symbols as forbidden public-contract terms after the cut.
• Room leaderboard reads. Added GET /api/v1/management/rooms/{roomId}/leaderboards and GET /api/v1/management/rooms/{roomId}/leaderboards/{leaderboardId} as server-side Management API reads for trusted host backends. Responses expose public leaderboard/run ids, freshness, availability, board display rules, and published standings without raw leaderboard UUIDs, rating identities, tenant ids, emails, private stats, contribution history, or gameplay state. Browser widgets and broader room stats remain reserved.
• Room leaderboard and stats admission. Audited the existing first-party leaderboard and stats projections for Management API exposure. The audit admitted the narrow server-side room_leaderboard_read slice now published above, with explicit room-to-leaderboard authority mapping, public leaderboard/run ids, redacted standings, freshness, erasure, and cross-room/cross-tenant IDOR tests. Broader room_stats_read remains reserved for Data / Intelligence; Management API stays limited to the room-summary operational counters already published.
• Room summary read. Added GET /api/v1/management/rooms/{roomId}/summary as a server-side Management API read for host-owned backends that need a public-safe room overview. The response includes room identity, freshness metadata, member count, upcoming tournament cards, and recent result links without raw identity ids, emails, internal tenant/source ids, cards, table state, or broad analytics. Browser-callable room_widget_summary, signed widget tokens, and deeper room stats remain reserved behind explicit authority, privacy, freshness, and token-posture follow-up tasks.

2026-06-07

• Tournament entry reads. Added GET /api/v1/management/tournaments/{tournamentId}/entries as a read-only Management API projection for tournament registration/admission rows. Responses use public pw_entry_... and pp_... identifiers and fail closed with READ_MODEL_NOT_READY until a public tournament has a materialized source tournament; standings, recap stats, seating, table state, and browser widgets remain reserved.
• Room member directory read. Added GET /api/v1/management/rooms/{roomId}/members as a read-only room-scoped Management API projection. Responses use public pw_membership_... and pw_player_... identifiers plus redacted display, role, status, and support metadata; member administration, invitations, emails, raw auth ids, browser widgets, and cross-brand identity links remain reserved.
• Tournament results wording. Locked the Management API matrix decision that /management/tournaments/{id}/results reads are the current tournament-result verification and export layer. Updated docs navigation, recipes, and webhook guidance to lead with tournament results instead of making result proof the primary builder outcome.
• Management tournament catalog. Added the read-only Management API tournament catalog at GET /api/v1/management/tournament-catalog. Service-account callers with tournaments:read can discover approved beta tournament preset keys plus the blind and payout structures those presets reference. Custom preset, blind-structure, and payout-structure authoring remains reserved for a later admitted catalog slice.
• Organization contract cutover. Updated public developer-platform contracts, generated OpenAPI mirrors, SDK/MCP/tooling fixtures, and Console API-key surfaces so operator authority is exposed as organizationId, organization, and accessibleOrganizations instead of public account-shaped fields. Calculation product-key scope is now org:read; internal accountId remains an implementation/source-table detail, with no pre-beta public aliases or compatibility shims retained.
• Operator noun guard. Extended public-docs noun-policy checks to cover Console source and operator-facing copy. Public docs and Console surfaces now reserve account for human identity, service-account, or connected-account contexts, while operator authority is described as an organization; stale event/room-event language remains blocked before beta.

2026-06-06

• Public read policy guard. Added executable registry enforcement for published browser-callable public reads. Public result/proof reads now declare visibility tier, freshness class, stale ceiling, cache behavior, CORS posture, rate-limit boundary, invalidation semantics, support-evidence boundary, and Data Use And Brand Rules reference before the public contract exposure guard will pass.
• First API call and collections. Added the First API Call & Collections concept page and canonical on-ramp policy. PokerWorks now distinguishes browser-safe public result/proof reads, server-side Calculation API first calls, and server-side Management automation loops; generated Postman collections are published only as deterministic outputs of public OpenAPI and webhook contracts, not hand-maintained endpoint lists or new access rights.
• Developer ecosystem programs. Added the Developer Ecosystem Programs concept page and canonical policy for directories and approved programs before marketplace. Recipes, public-clean examples, developer community surfaces, streamer/operator/coach/certified-bot directories, and approved integration examples are now staged ahead of marketplace, revenue-share, or embedded third-party app distribution, which remain reserved until demand, review, support, billing, certification, and takedown machinery exist.
• Approved integrations. Added the Approved Integrations concept page and canonical admission policy for future OAuth apps, connected clients, custom clients, bot/Table Protocol access, bulk exports, and high-integrity room integrations. Public reads can stay low-friction; account access, player-capable clients, gameplay control, and bulk private exports remain gated until scopes, consent, revocation, review, audit, data rights, support ownership, and contract proofs are admitted.
• Integrity tiers. Added the Integrity Tiers concept page and canonical room integrity-tier policy. integrityTier is now separate from trustMode: social is the public-beta default, while leaderboard, sponsored/prize, certified bot arena, research sandbox, and training-assisted tiers remain reserved until their policy, proof, webhook, audit, support-evidence, disclosure, sanction, and appeal deltas are admitted.
• Public read freshness. Added the Public Read Cache And Widget Freshness contract and docs concept page. Browser-callable public reads and widgets now have an admission rule for visibility tier, projection authority, freshness class, stale ceiling, cache headers, CORS/origin posture, rate limits, invalidation behavior, and support evidence before docs can present them as beta-ready.
• Public data and brand rules. Added the Public Data Use And Brand Rules concept page and canonical policy for public API output, widgets, exports, recipes, SDK/CLI/MCP examples, and brand references. Public-safe reads and widgets may support documented integration outcomes, but they do not grant scraping, private-room data reuse, model-training, public hand-history dataset, brand impersonation, unsupported attribution, or support-evidence rights. The Chess.com platform lessons are now lined up as follow-up tasks for public-read cache/freshness, integrity tiers, approved OAuth/connected-client/bulk-export admission, and directories/programs before marketplace.
• Table Protocol admission contract. Reserved the future Game Server API / Table Protocol behind a canonical admission contract. The registry now records that any certified custom-client, external bot-seat, live table stream, or gameplay action-submission surface must first define protocol/schema versioning, initial snapshots, ordered deltas, typed events, keep-alives, reconnect/resume, closure semantics, seat-scoped action idempotency, visibility tiers, trust-mode enforcement, and support/sanction evidence. No Table Protocol route, scope, schema, or SDK surface is published for beta.
• Result-proof productization. Clarified that result proof is a projection-backed, privacy-safe trust product rather than a novelty claim about proof technology. Documented the webhook/result-proof reconciliation contract, verifier/export posture, privacy tiers, and support/dispute evidence expectations. Added management and public result-proof export endpoints that return a canonical, SHA-256 digest-backed envelope for support/dispute preservation, plus a public verifier endpoint for saved export envelopes; signing-key workflows remain tracked follow-up work.
• Responsible social gaming baseline. Added the platform baseline for social/play-money player protection, clarified that brand policy is a configuration overlay rather than a public route fork, and updated Security and Access docs so play-money posture does not imply weaker moderation, fair-play, bot-disclosure, economy, privacy, or responsible-play obligations.
• Developer integrity trust modes. Added the trustMode policy field to room, tournament, and spectator embed-session Management resources. human_only is the public-beta default and only currently admitted write value; bot_only and mixed_declared remain reserved until certified protocol enforcement lands. Management API remains separate from future Table Protocol/gameplay action submission. Result/proof and tournament.completed webhook DTOs now include a privacy-safe integrity summary with the applied trust mode, whether bots were policy-allowed, declared bot-seat count/presence, and support-safe policy evidence.
• Developer docs IA. Reframed the developer docs around builder outcomes: operating a PokerDeck poker room, automating with service accounts, building branded sites, automating tournament outcomes, and using Calculation API tools. Added Choose your API path, made Management API the primary platform path, kept Calculation API as the quick first-call on-ramp, and kept the API reference implemented-only.
• Management API reference order. Reordered the Management API reference around the operator workflow: Organization, Projects, Product keys, Rooms, Tournaments, Tournament results & verification, Webhooks, Embeds, Playground, Usage, Billing, and Audit. Tightened the docs homepage, API reference hub, Calculation overview, and automation guides so the Management API reads as the platform control plane while Calculation remains the stateless product-key on-ramp.
• Public package status. Updated CLI, MCP, and Management SDK pages to status notes until those artifacts are public install paths. Beta integrations should use Console setup, documented HTTP/OpenAPI contracts, service-account management tokens, webhooks, and result/proof reads rather than private monorepo commands.
• Management authz beta gate. Tightened webhook endpoint and delivery list reads so restricted management tokens inherit project/environment grants even when callers omit explicit filters. Updated public API conventions and versioning standards with the list-authz and beta lifecycle requirements.
• Credential posture. Clarified that product API keys (pw_test_ / pw_live_) and management tokens (pw_mgmt_) are server-side bearer credentials. Browser, mobile, and embedded flows use short-lived launch/session credentials such as pwes_ embed launch secrets minted by trusted server code through the Management API; product keys do not mint browser access.
• Calculation API route root. Normalized the Calculation API public contract to the shared /api/v1 version root: /api/v1/calculations/**, /api/v1/usage, and /api/v1/health. Management API remains under /api/v1/management/**, where management marks the service-account control-plane segment. No /v1/** Calculation API aliases are retained for beta.
• Runtime/read boundary. Documented that embed-open and public result/proof reads are browser-safe runtime companions, not a self-serve gameplay, table-state, launch-ticket, or action-submission API.
• Management product keys. Cut the Management API product-key routes from /api-keys to /product-keys, renamed service-account scopes from api_keys:* to product_keys:*, and updated the repo-owned management client methods to listProductKeys(), createProductKey(), and revokeProductKey(). No legacy route aliases or duplicate public scopes are retained for public beta.

2026-06-05

• Public contract exposure guard. Added contracts:public-exposure:check, a registry-backed guard that fails unregistered public routes, scopes, webhook event types, ID prefixes, and do-not-expose leaks across public OpenAPI contracts, docs API mirrors, and developer webhook contracts.
• API contract-freeze registry. Added the public API conventions standard and a machine-readable resource registry that classifies Calculation API, Management API, runtime/read companions, Webhooks, reserved future planes, scopes, prefixes, object-authorization paths, privacy posture, consistency, and do-not-expose patterns for the pre-beta contract-freeze guardrail work.
• Management API namespace. Cut the service-account automation surface over to /api/v1/management/**, renamed MCP tool IDs to pokerworks_management_*_v1, and split /docs/api into an API-reference hub with separate Calculation API and Management API references. The old /api/v1/developer-api/management/** namespace is not preserved in beta.
• Calculation API naming. Renamed the product-key reference to Calculation API, moved it to /docs/api/calculations, and renamed the generated contract artifacts to calculation-api.openapi.json / pokerworks-calculation-api.openapi.json.

2026-06-04

• Console Room setup. Added a Console Rooms page for human operators to inspect PokerDeck Rooms, tournaments, setup gates, scoped-token coverage, webhook readiness, result/proof links, and support evidence while lifecycle writes remain in the management API, SDK, CLI, and MCP.
• Room beta guardrails. Test-mode Room provisioning now enforces explicit quotas (active Rooms per project/environment, non-archived tournaments per Room, and concurrent published/scheduled tournaments per Room) with typed RATE_LIMIT_EXCEEDED responses. Live Room and tournament writes now fail closed behind the first-live product-access allowlist until billing, entitlement, hosted-runtime quota, usage metering, and support-audit controls are enabled.
• Tournament automation example. Added examples/developer-platform/tournament-automation, a public-clean Node.js example that creates or selects a test PokerDeck Room, publishes a bounded tournament, attaches the playground completion fixture, prints certified result/proof evidence, and cancels the test tournament after the proof read so repeated runs stay within test quotas.
• Tournament output loop. The test-mode playground completion endpoint can now attach its synthetic completed tournament fixture to a published or scheduled tournament, returning an updated tournament with links.resultsUrl and output.results.available so Discord/result-proof recipes can prove the bounded tournament outcome loop.
• Tournament output hardening. Tournament playground outputs now use tournament-scoped synthetic tournament ids and require tournaments:update when a playground completion attaches output to a tournament.
• Room MCP automation. Added bounded tournament MCP tools for agent-native tournament list/create, read/update, publish/schedule, cancel, and archive flows over the shared management client, with explicit tournaments:read, tournaments:create, tournaments:update, tournaments:publish, tournaments:cancel, and tournaments:archive descriptions plus destructive annotations for cancel/archive operations.
• Room SDK/CLI automation. Extended the repo-owned management CLI with Room and bounded tournament commands (rooms ... and tournaments ...) over the shared management client, including idempotency keys for create calls and clean JSON evidence output for dogfood/support workflows.
• Tournaments. Added beta management contracts and management-client methods for bounded tournaments: create from the approved six_max_nlhe_sng_v1 preset, list/read, update draft or scheduled fields, publish/schedule in test mode, cancel, and archive. Live publish/start remains gated until the beta live guardrails for quotas, billing, entitlement, audit, and abuse limits land.
• Rooms. Added beta management contracts, management-client methods, and MCP tools for creating, listing, updating, and archiving Rooms with public roomId identifiers, scoped management-token permissions, idempotent default-room creation, and no public tenantId leakage.
• Public-clean examples. Added an export-ready examples/developer-platform tree with dependency-free Node.js examples for the result/proof explorer, Discord announcements, Google Sheets results, and a minimal signed webhook receiver template. The examples validate with developer-platform-public-examples:test and fail on private PokerWorks workspace imports or missing setup files.
• Developer Playground. Added a test-mode playground completion endpoint (POST /api/v1/management/playground/tournament-completion) that emits a frozen synthetic tournament.completed fixture, queues real signed webhook deliveries for active test endpoints, and returns the same public-safe result/proof DTO used by recipes.
• Management tokens. Added the playground:write scope and Console preset support so service-account tokens can exercise webhook/result-proof recipes without live access.
• Agent-native automation. Added the pokerworks_management_playground_tournament_completion_emit_v1 MCP tool and management-client method for agent-runnable playground proofs.
• Recipes. Added a result/proof explorer recipe and updated the Discord and Google Sheets recipes with a test-mode playground trigger step.
• Examples dogfood. Added a repo-owned developer-platform-public-examples:dogfood check that verifies the deployed docs and can exercise the live test-mode playground loop from ignored local operator env without printing secrets. The dogfood runner now also creates, reads, updates, lists, and archives a temporary non-default test Room through the same management API surface used by organisers.

2026-06-03

• Developer platform docs moved to a beta posture: developers can create a Console account, start with test keys/free credits, and use scoped automation surfaces where project configuration and support evidence are ready.
• Result/proof reads are live. A scoped management read (GET /api/v1/management/tournaments/{id}/results), plus a browser-safe public read for explicitly public results, returns the privacy-safe winner, standings, payout summary, replay status, and support evidence. The v0 tournament.completed webhook payload stays minimal and now carries a links.results discovery link; the maintained recipes and the Management API MCP read consume it.
• Webhook signed delivery is live in beta: endpoint verification, at-least-once delivery with exponential backoff, delivery logs, and manual replay.
• Recipes & the automation loop. The Recipes hub now opens with a five-step automation loop overview (project setup → scoped management token → webhook endpoint → result/proof read → recipe outcome). Added the Embed a club lobby and Google Sheets results export recipes alongside the Discord announcements recipe.
• Console. Added the Webhooks UI (endpoints, deliveries, signed-delivery replay), a service-account token-preset flow with a "verified automation loop" guide, organization account switching, and a receipts / billing portal.
• Billing & credits. Calculation API credits now grant from plans; credit exhaustion returns a typed 402.
• The /developers landing page now frames access as beta / test-mode first instead of an access-gated preview.

2026-05-27

• Restructured the docs around the two-plane model: a Calculation API section (product keys, poker math, SDK status) and an Automation & management section (service accounts, management tokens, webhooks, and beta automation contracts).
• Added pages for service accounts & management tokens, versioning & stability, status, and a glossary. Private CLI, MCP, and management-client pages are intentionally unlisted until public artifacts are available.
• Split concepts (explanation) from reference (errors, rate limits); expanded Errors & troubleshooting.
• Added a "Which key do I use?" reference for pw_test_ / pw_live_ / pw_mgmt_.

2026-05-25

• Developer platform docs moved to an invite-gated beta posture: developers can create an account in the console, issue test keys, and start calling the calculation API with free credits.
• Docs updated from "Alpha Access" to Access & limits.
• Added Console and Sign-up entry points across the docs and the /developers landing page.
• API reference now renders from the generated Calculation API projection instead of the hand-maintained preview file.

2026-05-24

• Promoted the Zudoku documentation app as the canonical repo-owned docs/reference surface for pokerworks.io/docs.
• Preserved the split between the corporate /developers landing page, the docs hub, the public API origin, and the future console.
• Published the initial calculation API, SDK, reference, and access pages.

Planned

• Publish the public TypeScript SDK as @pokerworks/sdk once it no longer depends on private monorepo packages.