Beta API Documentation
warning
This documentation is now deprecated. If you are using Matchmaker Self Serve though UDash, please use the documentation here.
Packages#
If you are using Unity, refer to the Getting Started Guide for details about the Client SDK package. This information can help to simplify the ticket management flow that is detailed in the following sections.
Authorization#
Depending on which API endpoint to call, there are three types of authorization possible, all in JWT token format.
For more information about JWT-based authentication and authorization, see the JWT website.
Developer#
The Configs API is protected by administrative authorization on the project. To manage configs, the caller must have either Manager or Owner permissions for the project in their Unity organization (for more information, see the Unity documentation on Organization roles.
Server#
The Backfill endpoint is protected by a JWT that the dedicated game server (DGS) receives in its configuration when an allocation occurs. The JWT needs to be passed in the Authorization header of the request with the following format:
Player#
The Tickets endpoint is protected by a player identity token that is also using the JWT format. Player Identity is a white-labled identity token exchange provider that is required to call matchmaking. It is standards-compliant and is compatible with most identity solutions by default. The client flow, a client ID, and supplemental documentation is provided in the Unity Player ID Documentation.
Beta API#
https://cloud.connected.unity3d.com/{unityProjectId}/matchmaking/api/v1
Rate-limiting#
Rate limits are used on some matchmaking APIs. These limits help to keep the matchmaker stable under load. The limits are set high enough that they should not be a concern with normal usage patterns. When the matchmaker is rate-limiting, APIs return a 429 status code. For more information, see the IETF documentation on RFC 6585.
For responses with a 429 status code that do not provide rate-limiting headers (such as retry-after), it is recommended that you use the following exponential backoff policy:
- Retry after
Yseconds, whereY = Jitter + 2^Attempt- Jitter should be should a random value between
-AttemptandAttemptfor each request
- Jitter should be should a random value between
- Maximum of 5 attempts
Request Size Limit#
All apis enforce a payload size limit. 64kB and greater will result in a 413 HTTP return code. This includes the Ticket POST api.
Tickets#
Tickets are matchmaking requests for one or more players. They contain player matchmaking intentions and other player data that is needed by match functions.
Tickets require player authorization.
Ticket requests are also subject to rate-limiting. The limits take into account scenarios such as when players make the requests, which results in many requests from different clients, and when a developer creates a proxy server that performs the requests on behalf of players, which results in many requests from the same client. Rate-limiting is applied based on the current ticket pool size, which means that as the pool of tickets reaches a certain threshold, the endpoint starts to reject ticket creation requests to empty the pool more effectively.
POST /tickets
Create a matchmaking ticket, effectively starting matchmaking.
Header: X-On-Behalf-Of Value: player-id. See the Player Auth API documentation
Body: CreateTicket
Response: 201 (CreateTicketResponse), 400
GET /tickets?id={ticketId}
Get a matchmaking ticket. Poll continuously until the assignment is not null.
Response: 200 (TicketResponse)
note
An error attached to the ticket stating that the Multiplay max is zero for a fleet or region indicates that the maximum number of servers allowed for your fleet or region in Multiplay is zero. Reach out to your Multiplay representative to ensure your fleet/region have the limit increased.
DELETE /tickets?id={ticketId}
Delete a matchmaking ticket, effectively ending matchmaking.
Header: X-On-Behalf-Of Value: player-id. See the Player Auth API documentation
Response: 200, 404 [not found]
Configs#
Matchmaking configurations are the instructions for running matchmaking functions. They specify which Multiplay server profile to use, and other match-specific parameters that are necessary to run multiple modes, playlists, and match configurations.
Matchmaking configurations require developer authorization.
Config requests are also subject to rate-limiting.
POST /configs
Create a new matchmaking config. The existence of the config immediately enables it for matchmaking cycles.
Body: Config
Response: 200, 400 (ValidationErrorResponse)
note
POST generates a new GUID identifer for your config. Consider using the put command to have direct control over config names.
GET /configs/{configId}
Get an existing matchmaking config.
Response: 200 (Config)
PUT /configs/{configId}
Creates or updates the config that is specified by configId. ConfigId conforms to restrictions from most file systems for names.
Body: Config
Response: 200, 400 (ValidationErrorResponse), 409
DELETE /configs/{configId}
Delete an existing matchmaking config. Removing the config immediately disables it for matchmaking cycles.
Response: 204 [deleted]
Backfill#
POST /api/v2/backfill/{id}/approvals
Approves a backfill ticket. Returns the BackfillTicket. Approving a backfill ticket will allow all proposed tickets associated with that backfill ticket to be assigned. This must be called periodically in order to get players via backfill. It is recommended that this be called no faster than once a second while backfill is in progress.
Response: 200 (BackfillTicket), 404, 500, 503
Note:Proposed tickets associated with a backfill ticket will be rejected after 20 seconds if not approved. Rejected tickets will return to the pool of tickets queryable by the match function.
Known issues: There is a known issue with this endpoint catalogued here
POST /api/v2/backfill
Creates a backfill ticket. Returns the backfill ticket ID wrapped in a CreateBackfillTicketResponse. This should be called when backfill begins.
Body: CreateBackfillTicketRequest
Response: 201 (CreateBackfillTicketResponse)
PUT /api/v2/backfill/{id}
Updates a backfill ticket. Updating a backfill ticket will reject all proposed tickets associated with that backfill ticket. Rejected tickets will return to the pool of tickets queryable by match functions. This should be called when the server state changes in order to reflect the current server state, such as when people leave the server, or when people join the server without the involvement of the matchmaker.
Note: When matchmaking logic updates backfill tickets, the update is bound to the version the matchmaking logic observed. Calling this method will most likely cause any pending updates from matchmaking logic to fail, as the state of the backfill ticket is replaced. See section on DGS Updates Backfill Ticket Too Frequently for more details.
Body: BackfillTicket
Response: 200
DELETE /api/v2/backfill/{id}
Deletes a backfill ticket. Deleting a backfill ticket will reject all proposed tickets associated with that backfill ticket. Rejected tickets will return to the pool of tickets queryable by the match function. This should be called when backfill ends.
Response: 204
ProblemDetails#
When a request cannot be successfully completed, an error response is generated. Whenever possible, this response displays in the form of an RFC 7807 ProblemDetails response. For more information, see the IETF documentation on RFC 7807.
For example, requesting a ticket that does not exist returns a response similar to the following example:
A ProblemDetails response is generated in the following scenarios:
| Request | Reason | HTTP code |
|---|---|---|
| Create Ticket | Ticket validation error (invalid ticket contents) | 400 |
| Create Ticket | Invalid/missing content-type (Content-Type header must be application/json) | 415 |
| Get Ticket | Ticket not found | 404 |
| Create Config | Config validation error | 400 |
| Update Config | Config validation error | 400 |
| Get Function Logs | Invalid time range | 400 |
| Get Function Logs | Invalid function name | 400 |
| Get Function Logs | Function not found | 404 |
| Any | Internal service error | 5xx |
Note that the details provided in a ProblemDetails response can be helpful for troubleshooting your issue if it is included in a support request.