openapi: 3.0.3
info:
  title: Hathora Cloud API
  description: >-
    Hathora Cloud is on-demand, globally distributed compute for multiplayer
    game servers. Use the Hathora Cloud API to manage applications, upload and
    run game server builds, configure deployments, launch and stop processes,
    create and manage rooms, discover ping endpoints, stream logs, read process
    metrics, and manage organization tokens and billing. Player-facing
    authentication issues short-lived player tokens for use with room and lobby
    endpoints.
  termsOfService: https://hathora.dev/terms-of-service
  contact:
    name: Hathora Support
    url: https://hathora.dev
    email: support@hathora.dev
  version: '3.0'
servers:
  - url: https://api.hathora.dev
    description: Hathora Cloud production API
tags:
  - name: AuthV1
    description: Player authentication - issue short-lived player tokens.
  - name: AppsV2
    description: Create and manage your organization's applications.
  - name: BuildsV3
    description: Upload and manage game server build artifacts.
  - name: DeploymentsV3
    description: Versioned runtime configuration for a build.
  - name: ProcessesV3
    description: Launch, inspect, and stop running game server processes.
  - name: RoomsV2
    description: Create, inspect, and destroy rooms and get connection info.
  - name: DiscoveryV2
    description: Region ping endpoints for latency-based routing.
  - name: LogsV1
    description: Stream and download logs for processes.
  - name: MetricsV1
    description: Read CPU, memory, egress, and connection metrics for a process.
  - name: BillingV1
    description: Account balance, invoices, payment method, and Stripe portal.
  - name: TokensV1
    description: Create, list, and revoke organization API tokens.
security:
  - hathoraDevToken: []
paths:
  /auth/v1/{appId}/login/anonymous:
    post:
      operationId: LoginAnonymous
      tags:
        - AuthV1
      summary: Returns a unique player token for an anonymous user.
      security: []
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: Player token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerTokenObject'
        '404':
          $ref: '#/components/responses/NotFound'
  /auth/v1/{appId}/login/nickname:
    post:
      operationId: LoginNickname
      tags:
        - AuthV1
      summary: Returns a unique player token with a specified nickname.
      security: []
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - nickname
              properties:
                nickname:
                  type: string
                  example: Alice
      responses:
        '200':
          description: Player token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerTokenObject'
  /auth/v1/{appId}/login/google:
    post:
      operationId: LoginGoogle
      tags:
        - AuthV1
      summary: Returns a unique player token using a Google-signed OIDC idToken.
      security: []
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - idToken
              properties:
                idToken:
                  type: string
      responses:
        '200':
          description: Player token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerTokenObject'
  /apps/v2/list:
    get:
      operationId: GetApps
      tags:
        - AppsV2
      summary: Returns an unsorted list of your organization's applications.
      parameters:
        - $ref: '#/components/parameters/OrgIdQuery'
      responses:
        '200':
          description: A list of applications.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
  /apps/v2/create:
    post:
      operationId: CreateApp
      tags:
        - AppsV2
      summary: Create a new application.
      parameters:
        - $ref: '#/components/parameters/OrgIdQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppConfig'
      responses:
        '201':
          description: Application created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
  /apps/v2/update/{appId}:
    post:
      operationId: UpdateApp
      tags:
        - AppsV2
      summary: Update data for an existing application.
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppConfig'
      responses:
        '200':
          description: Application updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
  /apps/v2/info/{appId}:
    get:
      operationId: GetApp
      tags:
        - AppsV2
      summary: Get details for an application.
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: Application details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/v2/delete/{appId}:
    delete:
      operationId: DeleteApp
      tags:
        - AppsV2
      summary: Delete an application using appId. Your organization will lose access.
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '204':
          description: Application deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /builds/v3/{appId}/list:
    get:
      operationId: GetBuilds
      tags:
        - BuildsV3
      summary: Returns an array of builds for an application.
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: A list of builds.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Build'
  /builds/v3/{appId}/create:
    post:
      operationId: CreateBuild
      tags:
        - BuildsV3
      summary: >-
        Creates a new build. Responds with a buildId that you must pass to
        RunBuild.
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                buildTag:
                  type: string
                  description: Tag to associate an external version with a build.
                  example: 0.1.14-14c793
      responses:
        '201':
          description: Build created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
  /builds/v3/{appId}/run/{buildId}:
    post:
      operationId: RunBuild
      tags:
        - BuildsV3
      summary: Builds a game server artifact from a tarball you provide.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/BuildId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: A tarball of the game server Dockerfile and source.
      responses:
        '200':
          description: A stream of build logs.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /builds/v3/{appId}/info/{buildId}:
    get:
      operationId: GetBuild
      tags:
        - BuildsV3
      summary: Get details for a build.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/BuildId'
      responses:
        '200':
          description: Build details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '404':
          $ref: '#/components/responses/NotFound'
  /builds/v3/{appId}/delete/{buildId}:
    delete:
      operationId: DeleteBuild
      tags:
        - BuildsV3
      summary: Delete a build. All associated metadata is deleted.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/BuildId'
      responses:
        '204':
          description: Build deleted.
  /deployments/v3/{appId}/list:
    get:
      operationId: GetDeployments
      tags:
        - DeploymentsV3
      summary: Returns an array of deployments for an application.
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: A list of deployments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Deployment'
  /deployments/v3/{appId}/create/{buildId}:
    post:
      operationId: CreateDeployment
      tags:
        - DeploymentsV3
      summary: >-
        Create a new deployment. All new processes for the app will use the
        latest deployment configuration.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/BuildId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentConfig'
      responses:
        '201':
          description: Deployment created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
  /deployments/v3/{appId}/latest:
    get:
      operationId: GetLatestDeployment
      tags:
        - DeploymentsV3
      summary: Get the latest deployment for an application.
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: Latest deployment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
  /deployments/v3/{appId}/info/{deploymentId}:
    get:
      operationId: GetDeployment
      tags:
        - DeploymentsV3
      summary: Get details for a deployment.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - name: deploymentId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Deployment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '404':
          $ref: '#/components/responses/NotFound'
  /processes/v3/{appId}/list/latest:
    get:
      operationId: GetLatestProcesses
      tags:
        - ProcessesV3
      summary: Retrieve the latest process objects for an application.
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: A list of processes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Process'
  /processes/v3/{appId}/create:
    post:
      operationId: CreateProcess
      tags:
        - ProcessesV3
      summary: Start a new process in a specific region.
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - region
              properties:
                region:
                  $ref: '#/components/schemas/Region'
      responses:
        '201':
          description: Process created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
  /processes/v3/{appId}/info/{processId}:
    get:
      operationId: GetProcess
      tags:
        - ProcessesV3
      summary: Get details for a process.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/ProcessId'
      responses:
        '200':
          description: Process details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '404':
          $ref: '#/components/responses/NotFound'
  /processes/v3/{appId}/stop/{processId}:
    post:
      operationId: StopProcess
      tags:
        - ProcessesV3
      summary: Stop a running process.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/ProcessId'
      responses:
        '204':
          description: Process stopped.
  /rooms/v2/{appId}/create:
    post:
      operationId: CreateRoom
      tags:
        - RoomsV2
      summary: Create a new room for an application.
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - region
              properties:
                region:
                  $ref: '#/components/schemas/Region'
                roomConfig:
                  type: string
                  description: Optional opaque config string passed to the process.
      responses:
        '201':
          description: Room created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomCreated'
  /rooms/v2/{appId}/info/{roomId}:
    get:
      operationId: GetRoomInfo
      tags:
        - RoomsV2
      summary: Get details for a room.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/RoomId'
      responses:
        '200':
          description: Room details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Room'
        '404':
          $ref: '#/components/responses/NotFound'
  /rooms/v2/{appId}/connectioninfo/{roomId}:
    get:
      operationId: GetConnectionInfo
      tags:
        - RoomsV2
      summary: Poll this endpoint to get connection details for an active room.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/RoomId'
      responses:
        '200':
          description: Connection info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionInfo'
  /rooms/v2/{appId}/destroy/{roomId}:
    post:
      operationId: DestroyRoom
      tags:
        - RoomsV2
      summary: Destroy a room. All associated metadata is deleted.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/RoomId'
      responses:
        '204':
          description: Room destroyed.
  /discovery/v2/ping:
    get:
      operationId: GetPingServiceEndpoints
      tags:
        - DiscoveryV2
      summary: >-
        Returns an array of all regions with a host and port that a client can
        directly ping for latency-based routing.
      security: []
      responses:
        '200':
          description: Ping service endpoints.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DiscoveryResponse'
  /logs/v1/{appId}/process/{processId}:
    get:
      operationId: GetLogsForProcess
      tags:
        - LogsV1
      summary: Returns a stream of logs for a process using appId and processId.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/ProcessId'
      responses:
        '200':
          description: A stream of log lines.
          content:
            application/x-ndjson:
              schema:
                type: string
  /logs/v1/{appId}/process/{processId}/download:
    get:
      operationId: DownloadLogForProcess
      tags:
        - LogsV1
      summary: Download the log file for a stopped process.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/ProcessId'
      responses:
        '200':
          description: Log file.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /metrics/v1/{appId}/process/{processId}:
    get:
      operationId: GetMetrics
      tags:
        - MetricsV1
      summary: Get metrics for a process using appId and processId.
      parameters:
        - $ref: '#/components/parameters/AppId'
        - $ref: '#/components/parameters/ProcessId'
        - name: metrics
          in: query
          description: The metrics to retrieve.
          schema:
            type: array
            items:
              type: string
              enum:
                - cpu
                - memory
                - rate_egress
                - total_egress
                - active_connections
      responses:
        '200':
          description: Metrics data keyed by metric name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
  /billing/v1/balance:
    get:
      operationId: GetBalance
      tags:
        - BillingV1
      summary: Get the current account balance.
      responses:
        '200':
          description: Account balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: number
                    format: double
  /billing/v1/invoices:
    get:
      operationId: GetInvoices
      tags:
        - BillingV1
      summary: Retrieve invoice history.
      responses:
        '200':
          description: A list of invoices.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'
  /billing/v1/paymentmethod:
    get:
      operationId: GetPaymentMethod
      tags:
        - BillingV1
      summary: Get stored payment method details.
      responses:
        '200':
          description: Payment method.
          content:
            application/json:
              schema:
                type: object
                properties:
                  brand:
                    type: string
                  last4:
                    type: string
  /billing/v1/customerportalurl:
    post:
      operationId: InitStripeCustomerPortalUrl
      tags:
        - BillingV1
      summary: Initialize a Stripe customer portal URL.
      responses:
        '200':
          description: Stripe portal URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
  /tokens/v1/{orgId}/list:
    get:
      operationId: GetOrgTokens
      tags:
        - TokensV1
      summary: Returns an unsorted list of an organization's API tokens.
      parameters:
        - $ref: '#/components/parameters/OrgId'
      responses:
        '200':
          description: A list of org tokens.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrgToken'
  /tokens/v1/{orgId}/create:
    post:
      operationId: CreateOrgToken
      tags:
        - TokensV1
      summary: Create a new organization API token.
      parameters:
        - $ref: '#/components/parameters/OrgId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: ci-token
      responses:
        '201':
          description: Org token created. The plainTextToken is only shown once.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OrgToken'
                  - type: object
                    properties:
                      plainTextToken:
                        type: string
  /tokens/v1/{orgId}/revoke/{orgTokenId}:
    put:
      operationId: RevokeOrgToken
      tags:
        - TokensV1
      summary: Revoke an organization API token.
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - name: orgTokenId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Token revoked.
components:
  securitySchemes:
    hathoraDevToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Organization developer/API token used for management endpoints (apps,
        builds, deployments, processes, rooms, logs, metrics, billing, tokens).
    playerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Short-lived player token issued by the AuthV1 login endpoints, used by
        game clients for room and lobby operations.
  parameters:
    AppId:
      name: appId
      in: path
      required: true
      description: The unique identifier for an application.
      schema:
        type: string
        example: app-af469a92-5b45-4565-b3c4-b79878de67d2
    BuildId:
      name: buildId
      in: path
      required: true
      schema:
        type: string
    ProcessId:
      name: processId
      in: path
      required: true
      schema:
        type: string
        example: cbfbb - 12345
    RoomId:
      name: roomId
      in: path
      required: true
      schema:
        type: string
        example: 2swovpy1fnunu
    OrgId:
      name: orgId
      in: path
      required: true
      schema:
        type: string
        example: org-6f706e83-0ec1-437a-9a46-7d4281eb2f39
    OrgIdQuery:
      name: orgId
      in: query
      required: false
      schema:
        type: string
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    Region:
      type: string
      description: The region where a process, room, or lobby runs.
      enum:
        - Seattle
        - Los_Angeles
        - Washington_DC
        - Chicago
        - London
        - Frankfurt
        - Mumbai
        - Singapore
        - Tokyo
        - Sydney
        - Sao_Paulo
    PlayerTokenObject:
      type: object
      properties:
        token:
          type: string
          description: A signed JWT player token.
    AppConfig:
      type: object
      required:
        - appName
      properties:
        appName:
          type: string
          example: minecraft
        authConfiguration:
          type: object
          description: Configuration for player auth providers.
    Application:
      type: object
      properties:
        appId:
          type: string
        appName:
          type: string
        orgId:
          type: string
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
    Build:
      type: object
      properties:
        buildId:
          type: string
        appId:
          type: string
        buildTag:
          type: string
        status:
          type: string
          enum:
            - created
            - running
            - succeeded
            - failed
        imageSize:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
    DeploymentConfig:
      type: object
      required:
        - idleTimeoutEnabled
        - roomsPerProcess
        - transportType
        - containerPort
        - requestedCPU
        - requestedMemoryMB
      properties:
        idleTimeoutEnabled:
          type: boolean
        roomsPerProcess:
          type: integer
          example: 3
        transportType:
          type: string
          enum:
            - tcp
            - udp
            - tls
        containerPort:
          type: integer
          example: 4000
        requestedCPU:
          type: number
          example: 0.5
        requestedMemoryMB:
          type: integer
          example: 1024
        env:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
        additionalContainerPorts:
          type: array
          items:
            type: object
            properties:
              transportType:
                type: string
              port:
                type: integer
              name:
                type: string
    Deployment:
      type: object
      properties:
        deploymentId:
          type: integer
        appId:
          type: string
        buildId:
          type: string
        buildTag:
          type: string
        idleTimeoutEnabled:
          type: boolean
        roomsPerProcess:
          type: integer
        transportType:
          type: string
        containerPort:
          type: integer
        requestedCPU:
          type: number
        requestedMemoryMB:
          type: integer
        createdAt:
          type: string
          format: date-time
    Process:
      type: object
      properties:
        processId:
          type: string
        appId:
          type: string
        deploymentId:
          type: integer
        region:
          $ref: '#/components/schemas/Region'
        host:
          type: string
        port:
          type: integer
        roomsAllocated:
          type: integer
        roomsPerProcess:
          type: integer
        status:
          type: string
          enum:
            - starting
            - active
            - draining
            - stopping
            - stopped
        startedAt:
          type: string
          format: date-time
        stoppingAt:
          type: string
          format: date-time
          nullable: true
        terminatedAt:
          type: string
          format: date-time
          nullable: true
    RoomCreated:
      type: object
      properties:
        roomId:
          type: string
        processId:
          type: string
    Room:
      type: object
      properties:
        roomId:
          type: string
        appId:
          type: string
        currentAllocation:
          type: object
          properties:
            processId:
              type: string
            roomAllocationId:
              type: string
            scheduledAt:
              type: string
              format: date-time
            unscheduledAt:
              type: string
              format: date-time
              nullable: true
        status:
          type: string
          enum:
            - scheduling
            - active
            - suspended
            - destroyed
    ConnectionInfo:
      type: object
      properties:
        status:
          type: string
          enum:
            - starting
            - active
        roomId:
          type: string
        exposedPort:
          type: object
          properties:
            transportType:
              type: string
            port:
              type: integer
            host:
              type: string
            name:
              type: string
    DiscoveryResponse:
      type: object
      properties:
        region:
          $ref: '#/components/schemas/Region'
        host:
          type: string
        port:
          type: integer
    MetricValue:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
        value:
          type: number
          format: double
    MetricsResponse:
      type: object
      properties:
        cpu:
          type: array
          items:
            $ref: '#/components/schemas/MetricValue'
        memory:
          type: array
          items:
            $ref: '#/components/schemas/MetricValue'
        rate_egress:
          type: array
          items:
            $ref: '#/components/schemas/MetricValue'
        total_egress:
          type: array
          items:
            $ref: '#/components/schemas/MetricValue'
        active_connections:
          type: array
          items:
            $ref: '#/components/schemas/MetricValue'
    Invoice:
      type: object
      properties:
        invoiceId:
          type: string
        amountDue:
          type: number
          format: double
        status:
          type: string
        dueDate:
          type: string
          format: date-time
        invoiceUrl:
          type: string
          format: uri
    OrgToken:
      type: object
      properties:
        orgTokenId:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - revoked
        createdAt:
          type: string
          format: date-time
    ApiError:
      type: object
      properties:
        message:
          type: string