openapi: 3.0.1
info:
  title: Unity Analytics Allocations Tickets API
  description: The Unity Analytics REST API provides endpoints for ingesting custom analytics events from game clients and servers. Events are used to track player behavior, game performance, and feature adoption. The API supports batched event ingestion with automatic retry and buffering for high-volume game telemetry.
  version: v1.0.0
  termsOfService: https://unity.com/legal/terms-of-service
  contact:
    name: Unity Support
    url: https://support.unity.com
  license:
    name: Unity Terms of Service
    url: https://unity.com/legal/terms-of-service
servers:
- url: https://analytics.services.api.unity.com
  description: Unity Analytics Production Server
security:
- apiKeyAuth: []
tags:
- name: Tickets
  description: Create and manage matchmaking tickets
paths:
  /v3/projects/{projectId}/environments/{environmentId}/tickets:
    post:
      operationId: createTicket
      summary: Create Matchmaking Ticket
      description: Creates a matchmaking ticket for a player or group of players. The ticket enters the matchmaking queue and is matched with other players based on configured rules.
      tags:
      - Tickets
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environmentId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTicketRequest'
      responses:
        '200':
          description: Ticket created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCreated'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
  /v3/projects/{projectId}/environments/{environmentId}/tickets/{ticketId}:
    get:
      operationId: getTicket
      summary: Get Matchmaking Ticket
      description: Retrieves the current status of a matchmaking ticket. Polls this endpoint to check if a match has been found.
      tags:
      - Tickets
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environmentId
        in: path
        required: true
        schema:
          type: string
      - name: ticketId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ticket status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketStatus'
        '404':
          description: Ticket not found
    delete:
      operationId: deleteTicket
      summary: Delete Matchmaking Ticket
      description: Cancels and deletes a matchmaking ticket. Used when a player exits the matchmaking queue.
      tags:
      - Tickets
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environmentId
        in: path
        required: true
        schema:
          type: string
      - name: ticketId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Ticket deleted
        '404':
          description: Ticket not found
components:
  schemas:
    CreateTicketRequest:
      type: object
      required:
      - players
      - queueName
      properties:
        players:
          type: array
          items:
            $ref: '#/components/schemas/Player'
          description: Players to include in the matchmaking ticket
        queueName:
          type: string
          description: Name of the matchmaking queue to enter
        attributes:
          $ref: '#/components/schemas/TicketAttributes'
    TicketCreated:
      type: object
      properties:
        id:
          type: string
          description: Unique ticket identifier
    MatchAssignment:
      type: object
      properties:
        connection:
          type: string
          description: Server connection string for the matched game
        payload:
          type: object
          description: Additional match data
    TicketStatus:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - InProgress
          - Found
          - Failed
          description: Current ticket status
        assignment:
          $ref: '#/components/schemas/MatchAssignment'
    TicketAttributes:
      type: object
      properties:
        skill:
          type: number
          description: Player skill rating for skill-based matchmaking
        attributes:
          type: object
          additionalProperties: {}
    Player:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: Unity player ID
        attributes:
          type: object
          description: Player-specific attributes for matchmaking
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
externalDocs:
  description: Unity Analytics Documentation
  url: https://docs.unity.com/ugs/en-us/manual/analytics/manual/rest-api