Skip to main content
This guide gets you a working lobby in under 5 minutes. No dashboard setup. No player auth. Just curl. By the end, you’ll have created a lobby, joined it with a second player, updated player state, and torn it all down.

​
Prerequisites

  • A PlayFlow project (free tier works — sign up here)
  • Your Client API Key (from Project Settings → starts with pfclient_)
Use the client key (pfclient_*) for anything a game client can do. Use the server key (pf_*) only for trusted backend services or admin operations.
This quickstart assumes no player-auth provider is configured on the project (the free-tier default), so the x-player-id header names the player. If you’ve set up JWT, PlayFab, or Steam auth, client-key calls must send a valid x-player-token instead — see the player authentication guide.

​
1. Create a Lobby

A lobby is created by a “host” player. The host is whoever sends the x-player-id header on the create request.
Response:
You just made a lobby. No dashboard config was needed — PlayFlow used defaults. Note the code field: that’s the invite code your players share.

​
About {config}

The default in the URL is a lobby config name. If no config with that name exists in your dashboard, PlayFlow uses sensible defaults:
  • timeout: 300s
  • serverSize: small
  • Build: latest default
maxPlayers isn’t a config default — it comes from the create request body (omit it and you get 2). Set it explicitly on each create call, as shown above. For production games, you’ll create named configs in the dashboard (casual, ranked_2v2, etc.) with custom matchmaking rules and server overrides. But you don’t need to yet.

​
2. Join as a Second Player

Share the invite code MEOW-42 with your friend. They call:
They could also join by lobby ID if they have it:
The response is the full lobby, now with 2 players:

​
3. Check Your Current Lobby

Any player can check which lobby they’re in using /me:
Returns the full lobby state. If you’re not in a lobby, returns 404.
/me is the player-centric primitive throughout the API. Instead of tracking lobby IDs in your game, just use /me endpoints — PlayFlow finds your lobby automatically from the x-player-id header.

​
4. Update Player State

Ready up, pick a character, set your MMR — anything goes in player state. The server merges your updates into existing state.
The response shows player2’s updated state:
State updates merge — existing keys are preserved unless overwritten. Setting ready: true doesn’t wipe out team: blue.

​
5. Start the Game

When ready, the host launches a game server directly:
The response now has server populated:
Use server.network_ports[0].host and server.network_ports[0].external_port to connect your game client. The server block is the same shape as GET /v3/servers/{instance_id}. The server transitions from launching → running in typically 10-30 seconds.
Only the host can start the game. If a non-host tries, they get a 403 with the message “Only the host can perform this action”. Lobby errors return {error, detail, status} — branch on the HTTP status, not the message text.

​
6. Leave (Cleanup)

Every player leaves with:
When the last player leaves, the lobby auto-deletes. The response is {"status": "lobby_deleted"}. If the host leaves while others remain, host transfers to the next player automatically.

​
That’s It

You’ve now exercised the full lobby lifecycle using just 6 API calls. The full API adds matchmaking, host-only actions (kick, settings), invite code joining, lobby browsing, real-time SSE updates, and more — but this is the 80% of what most games need.

Lobby Lifecycle

Host-only actions (kick, settings, transfer host), leaving behavior, error handling.

Matchmaking

Skip the manual “start” — let PlayFlow find opponents automatically.

Real-time Events

Stop polling. Subscribe to live events with SSE.

API Reference

Every endpoint with full schemas and try-it-out.