Parties

Parties

A party is a group of players in one Game Project that queues for Matchmaking as one unit. A party has one leader and up to 8 members. A player can be in only one party per Game Project. All calls need an API key with the matchmaker scope and the player session token. The Game Project must also have the matchmaker feature on.

Leader and members

The leader sets the queue settings, invites players, makes join codes, kicks members, queues, and cancels. Each member, the leader included, sets its own readiness and properties, sends heartbeats, and can leave. There is no route to give the leader role to a different player. When the leader leaves or drops out, the member who joined first and is still live becomes the leader.

Each write body has expected_version. Send the version from your last read of the party. If the party changed since then, the call returns 409 stale_version. Get the party again and retry.

A party has the state idle, queued, matched, or closed. Settings changes, new invites, new join codes, and joins work only in idle.

Routes

Route	Who	Purpose
POST /v1/parties	Any player	Create a party with settings. The caller becomes the leader.
GET /v1/parties/current	Member	Get your current party, for example after a reconnect.
GET /v1/parties/{id}	Member	Get a party.
PATCH /v1/parties/{id}	Leader	Change settings.
DELETE /v1/parties/{id}	Leader	Disband the party.
PUT /v1/parties/{id}/members/me/ready	Member	Set ready and your properties.
POST /v1/parties/{id}/heartbeat	Member	Keep your place. Returns the full party.
DELETE /v1/parties/{id}/members/me	Member	Leave the party.
DELETE /v1/parties/{id}/members/{player_id}	Leader	Kick a member.
POST /v1/parties/{id}/queue	Leader	Queue the party.
DELETE /v1/parties/{id}/queue	Leader	Cancel the queue, or return a matched party to idle.
POST /v1/parties/{id}/rematch	Leader	Queue again after a match.

settings uses the same fields as a matchmaking ticket: mode, fleet, region, game_mode, min_count, max_count, count_multiple, allow_cross_region, and query. properties holds string_properties, numeric_properties, and attributes (4 KiB maximum). Other members get your attributes raw, so escape them before you show them.

Each member must send a heartbeat within 30 seconds. If not, a sweep removes the member. A change to the roster or to the settings clears the readiness of all members.

Invites

The leader sends POST /v1/parties/{id}/invites with player_id. The target must be an accepted friend in this Game Project, and neither player can block the other. See Friends and Presence. An invite expires after 5 minutes. A second invite to the same player only resets the expiry and sends no new event.

The target lists pending invites with GET /v1/party-invites. Each item has id, party_id, party_version, target_id, and expires_at. Accept with POST /v1/party-invites/{id}/accept. Decline with DELETE /v1/party-invites/{id}. The leader can use the same DELETE to revoke an invite. For both calls, send party_version as expected_version.

Join codes

The leader makes a code with POST /v1/parties/{id}/invite-codes. Set max_uses from 1 to 7 (default 7). A new code revokes all earlier codes of the party. A code expires after 5 minutes. The response shows the code one time only, because the server keeps only a hash. Revoke a code with DELETE /v1/parties/{id}/invite-codes/{code_id}.

A player joins with POST /v1/parties/join and {"code": "..."}. Case and hyphens in the code do not matter.

Wrong codes count against the player and against the source IP in this Game Project. A successful join resets the count for that player. When a count reaches its limit, joins return 429 code_redemption_cooldown with Retry-After in seconds.

Setting	Default	Purpose
PARTY_CODE_PLAYER_MAX_FAILURES	10	Wrong codes one player can send in the window.
PARTY_CODE_IP_MAX_FAILURES	100	Wrong codes one source IP can send per Game Project in the window.
PARTY_CODE_COOLDOWN	15m	The failure window and the block time.

See Configuration Reference.

Queue for a match

1. The leader sets the settings while the party is idle.
2. Each member sends PUT .../members/me/ready with "ready": true.
3. The leader sends POST /v1/parties/{id}/queue with an Idempotency-Key header.

All members must be ready and live. The party size must not be more than settings.max_count. The server makes one ticket for each member and puts each ticket_id in members[]. The tickets match together or not at all. A retry with the same key returns the same party while it is still queued.

Each member gets a matchmaker_matched event for its own ticket. A member that misses the event polls GET /v1/matchmaker/tickets/{ticket_id}. After a match, the party is matched and all readiness is clear. To play again, all members get ready again, and the leader calls rematch with last_match_id. A failed or expired queue sets the party back to idle. When a member leaves or is removed, the server cancels the queue for the whole party.

PARTY_ENQUEUE_ENABLED (default true) controls queue and rematch. When it is false, both return 503 party_enqueue_disabled. All other party calls continue to work.

A party member cannot make a solo ticket. POST /v1/matchmaker/tickets returns 409 party_member_must_leave. A member cannot cancel a party ticket either. DELETE /v1/matchmaker/tickets/{id} returns 409 party_ticket_requires_leader_cancel. The leader uses DELETE /v1/parties/{id}/queue.

curl -s -X POST http://localhost:8080/v1/parties/42/queue \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>" \
  -H "Idempotency-Key: queue-7f3a" \
  -H "Content-Type: application/json" \
  -d '{"expected_version":9}'

Realtime events

Event	Payload	Sent to
party_changed	party_id, version, state	Current members and members that the change removed.
party_invite	invite_id, party_id, from_player_id	The invited player.

The server does not guarantee event delivery. When version is newer than yours, call GET /v1/parties/{id}. A 404 means that you are not a member now. The heartbeat also returns the full party. See Realtime WebSocket Events.

Errors

Huma puts the short code in detail, not in title.

Status	detail	Meaning
400	varies	Settings, properties, or attributes are not valid.
403	not_leader	Only the leader can do this.
403	forbidden	The key has no matchmaker scope (plain-text body), or matchmaking is off for the player or Game Project.
404	party_not_found	The party does not exist, or you are not a member.
404	invalid_invite	The invite or code is unknown, expired, revoked, used up, or not for you. Or the invite target is not a friend.
409	stale_version	expected_version is old. Get the party and retry.
409	party_busy	The party state does not allow this call.
409	party_full	The party has 8 members.
409	not_ready	A member is not ready or not live.
409	party_exceeds_mode_capacity	The party has more members than max_count.
409	party_already_active	The player is already in a party in this Game Project.
409	ticket_already_active	The player has a queued solo ticket.
429	code_redemption_cooldown	Too many wrong codes. Wait for Retry-After.
503	party_enqueue_disabled	The server turned off party queue.

Full reference: the /v1/parties* and /v1/party-invites* operations.