openapi: 3.0.1
info:
  title: Edgegap Arbitrium API
  description: >-
    Representative OpenAPI description of the Edgegap Arbitrium REST API for
    distributed edge game-server orchestration. Covers applications, application
    versions, deployments, sessions, matchmaking, relays/networking, metrics, and
    private fleets. Auto-deploy dedicated game servers to Edgegap's global network
    of edge locations. This document is a faithful, representative subset authored
    for cataloging; consult the official Edgegap documentation for the complete,
    authoritative reference.
  termsOfService: https://edgegap.com/terms-of-service/
  contact:
    name: Edgegap Support
    url: https://edgegap.com/contact/
  version: '1.0'
servers:
  - url: https://api.edgegap.com
    description: Edgegap Arbitrium Management API
security:
  - AuthToken: []
tags:
  - name: Applications
    description: Manage applications registered on Edgegap.
  - name: App Versions
    description: Manage container image versions for an application.
  - name: Deployments
    description: Deploy, inspect, and stop dedicated game servers at the edge.
  - name: Sessions
    description: Add and remove players or groups on a running deployment.
  - name: Matchmaking
    description: Create and poll matchmaking tickets.
  - name: Relays
    description: Distributed relay sessions and per-user authorization.
  - name: Metrics
    description: Monitoring and telemetry for deployments.
  - name: Fleets
    description: Private fleet deployments and host inventory.
paths:
  /v1/app:
    get:
      operationId: listApplications
      tags:
        - Applications
      summary: List applications
      description: Returns a paginated list of applications for the account.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
    post:
      operationId: createApplication
      tags:
        - Applications
      summary: Create application
      description: Registers a new application on Edgegap.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
  /v1/app/{app_name}:
    get:
      operationId: getApplication
      tags:
        - Applications
      summary: Get application
      parameters:
        - $ref: '#/components/parameters/AppName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
    patch:
      operationId: updateApplication
      tags:
        - Applications
      summary: Update application
      parameters:
        - $ref: '#/components/parameters/AppName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCreate'
      responses:
        '200':
          description: OK
    delete:
      operationId: deleteApplication
      tags:
        - Applications
      summary: Delete application
      parameters:
        - $ref: '#/components/parameters/AppName'
      responses:
        '200':
          description: OK
  /v1/app/{app_name}/versions:
    get:
      operationId: listAppVersions
      tags:
        - App Versions
      summary: List application versions
      parameters:
        - $ref: '#/components/parameters/AppName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionList'
  /v1/app/{app_name}/version:
    post:
      operationId: createAppVersion
      tags:
        - App Versions
      summary: Create application version
      description: Creates a new version (container image + runtime config) for an application.
      parameters:
        - $ref: '#/components/parameters/AppName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
  /v1/app/{app_name}/version/{version_name}:
    get:
      operationId: getAppVersion
      tags:
        - App Versions
      summary: Get application version
      parameters:
        - $ref: '#/components/parameters/AppName'
        - $ref: '#/components/parameters/VersionName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
    patch:
      operationId: updateAppVersion
      tags:
        - App Versions
      summary: Update application version
      parameters:
        - $ref: '#/components/parameters/AppName'
        - $ref: '#/components/parameters/VersionName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionCreate'
      responses:
        '200':
          description: OK
    delete:
      operationId: deleteAppVersion
      tags:
        - App Versions
      summary: Delete application version
      parameters:
        - $ref: '#/components/parameters/AppName'
        - $ref: '#/components/parameters/VersionName'
      responses:
        '200':
          description: OK
  /v2/deployments:
    post:
      operationId: createDeployment
      tags:
        - Deployments
      summary: Create deployment
      description: >-
        Deploys an application version as a dedicated server, auto-selecting the
        optimal edge location for the supplied players/IPs or geo coordinates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
  /v1/deployments:
    get:
      operationId: listDeployments
      tags:
        - Deployments
      summary: List deployments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentList'
  /v1/status/{deployment_id}:
    get:
      operationId: getDeploymentStatus
      tags:
        - Deployments
      summary: Get deployment status
      parameters:
        - $ref: '#/components/parameters/DeploymentId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
  /v1/stop/{deployment_id}:
    delete:
      operationId: stopDeployment
      tags:
        - Deployments
      summary: Stop deployment
      parameters:
        - $ref: '#/components/parameters/DeploymentId'
      responses:
        '200':
          description: OK
  /v1/deployments/bulk-stop:
    post:
      operationId: bulkStopDeployments
      tags:
        - Deployments
      summary: Bulk stop deployments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deployments:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: OK
  /v1/deployment/{deployment_id}/container-logs:
    get:
      operationId: getContainerLogs
      tags:
        - Deployments
      summary: Get container logs
      parameters:
        - $ref: '#/components/parameters/DeploymentId'
      responses:
        '200':
          description: OK
  /v1/deployments/{deployment_id}/tags:
    get:
      operationId: listDeploymentTags
      tags:
        - Deployments
      summary: List deployment tags
      parameters:
        - $ref: '#/components/parameters/DeploymentId'
      responses:
        '200':
          description: OK
    post:
      operationId: addDeploymentTag
      tags:
        - Deployments
      summary: Add deployment tag
      parameters:
        - $ref: '#/components/parameters/DeploymentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: OK
  /v1/session:
    post:
      operationId: createSession
      tags:
        - Sessions
      summary: Create session
      description: Creates a session with users, linked to a deployment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /v1/session/{session_id}:
    get:
      operationId: getSession
      tags:
        - Sessions
      summary: Get session
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
    delete:
      operationId: deleteSession
      tags:
        - Sessions
      summary: Delete session
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: OK
  /v1/session/{session_id}/users:
    get:
      operationId: listSessionUsers
      tags:
        - Sessions
      summary: List session users
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: OK
  /tickets:
    post:
      operationId: createMatchmakingTicket
      tags:
        - Matchmaking
      summary: Create matchmaking ticket
      description: >-
        Creates a new matchmaking ticket on a deployed matchmaker service.
        Served from the matchmaker service URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
  /tickets/{ticket_id}:
    get:
      operationId: getMatchmakingTicket
      tags:
        - Matchmaking
      summary: Poll matchmaking ticket
      parameters:
        - name: ticket_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
    delete:
      operationId: deleteMatchmakingTicket
      tags:
        - Matchmaking
      summary: Delete matchmaking ticket
      parameters:
        - name: ticket_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /v1/relays/sessions:
    get:
      operationId: listRelaySessions
      tags:
        - Relays
      summary: List relay sessions
      responses:
        '200':
          description: OK
    post:
      operationId: createRelaySession
      tags:
        - Relays
      summary: Create relay session
      description: Creates a distributed relay session with users and an optional webhook_url.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelaySessionCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelaySession'
  /v1/relays/sessions/{session_id}:
    get:
      operationId: getRelaySession
      tags:
        - Relays
      summary: Get relay session
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelaySession'
    delete:
      operationId: deleteRelaySession
      tags:
        - Relays
      summary: Delete relay session
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: OK
  /v1/relays/sessions:authorize-user:
    post:
      operationId: authorizeRelayUser
      tags:
        - Relays
      summary: Authorize relay user
      description: Grants a user access to a relay session (requires session_id and user_ip).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                session_id:
                  type: string
                user_ip:
                  type: string
      responses:
        '200':
          description: OK
  /v1/relays/sessions:revoke-user:
    post:
      operationId: revokeRelayUser
      tags:
        - Relays
      summary: Revoke relay user
      description: Removes a user's access to a relay session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                session_id:
                  type: string
                authorization_token:
                  type: string
      responses:
        '200':
          description: OK
  /v1/metrics/deployment/{deployment_id}:
    get:
      operationId: getDeploymentMetrics
      tags:
        - Metrics
      summary: Get deployment metrics
      description: Returns monitoring telemetry (CPU, memory, network) for a deployment.
      parameters:
        - $ref: '#/components/parameters/DeploymentId'
      responses:
        '200':
          description: OK
  /v2/private-fleets/deployments:
    post:
      operationId: createPrivateFleetDeployment
      tags:
        - Fleets
      summary: Create private fleet deployment
      description: Deploys onto self-managed hosts registered in a private fleet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentCreate'
      responses:
        '200':
          description: OK
  /v2/private-fleets/{fleet_name}/hosts:
    get:
      operationId: listPrivateFleetHosts
      tags:
        - Fleets
      summary: List private fleet hosts
      parameters:
        - name: fleet_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API token generated in the Edgegap dashboard (User Settings / Tokens),
        sent as `Authorization: token <your_token>`.
  parameters:
    AppName:
      name: app_name
      in: path
      required: true
      schema:
        type: string
    VersionName:
      name: version_name
      in: path
      required: true
      schema:
        type: string
    DeploymentId:
      name: deployment_id
      in: path
      required: true
      schema:
        type: string
    SessionId:
      name: session_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Application:
      type: object
      properties:
        name:
          type: string
        is_active:
          type: boolean
        is_telemetry_agent_active:
          type: boolean
        image:
          type: string
        create_time:
          type: string
          format: date-time
    ApplicationCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        is_active:
          type: boolean
        is_telemetry_agent_active:
          type: boolean
    ApplicationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Application'
        total_count:
          type: integer
    Version:
      type: object
      properties:
        name:
          type: string
        docker_repository:
          type: string
        docker_image:
          type: string
        docker_tag:
          type: string
        vcpu:
          type: integer
        memory:
          type: integer
        ports:
          type: array
          items:
            $ref: '#/components/schemas/Port'
        is_active:
          type: boolean
    VersionCreate:
      type: object
      required:
        - name
        - docker_image
      properties:
        name:
          type: string
        docker_repository:
          type: string
        docker_image:
          type: string
        docker_tag:
          type: string
        vcpu:
          type: integer
        memory:
          type: integer
        ports:
          type: array
          items:
            $ref: '#/components/schemas/Port'
    VersionList:
      type: object
      properties:
        versions:
          type: array
          items:
            $ref: '#/components/schemas/Version'
    Port:
      type: object
      properties:
        port:
          type: integer
        protocol:
          type: string
          enum:
            - TCP
            - UDP
            - TCP/UDP
            - WS
            - WSS
            - HTTP
            - HTTPS
        to_check:
          type: boolean
    DeploymentCreate:
      type: object
      required:
        - app_name
        - version_name
      properties:
        app_name:
          type: string
        version_name:
          type: string
        ip_list:
          type: array
          items:
            type: string
        geo_ip_list:
          type: array
          items:
            type: object
            properties:
              ip:
                type: string
              latitude:
                type: number
              longitude:
                type: number
        env_vars:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
    Deployment:
      type: object
      properties:
        request_id:
          type: string
        fqdn:
          type: string
        app_name:
          type: string
        app_version:
          type: string
        current_status:
          type: string
        running:
          type: boolean
        public_ip:
          type: string
        location:
          type: object
          properties:
            city:
              type: string
            country:
              type: string
            continent:
              type: string
            latitude:
              type: number
            longitude:
              type: number
        ports:
          type: object
          additionalProperties:
            type: object
    DeploymentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Deployment'
        total_count:
          type: integer
    SessionCreate:
      type: object
      required:
        - app_name
        - version_name
      properties:
        app_name:
          type: string
        version_name:
          type: string
        deployment_request_id:
          type: string
        ip_list:
          type: array
          items:
            type: string
        webhook_url:
          type: string
    Session:
      type: object
      properties:
        session_id:
          type: string
        status:
          type: string
        ready:
          type: boolean
        linked:
          type: boolean
        deployment_request_id:
          type: string
        user_count:
          type: integer
    TicketCreate:
      type: object
      properties:
        profile:
          type: string
        attributes:
          type: object
          additionalProperties: true
    Ticket:
      type: object
      properties:
        id:
          type: string
        state:
          type: string
          enum:
            - PENDING
            - MATCHED
            - DEPLOYING
            - READY
            - CANCELLED
        assignment:
          type: object
          properties:
            host:
              type: string
            port:
              type: integer
    RelaySessionCreate:
      type: object
      properties:
        webhook_url:
          type: string
        users:
          type: array
          items:
            type: object
            properties:
              ip:
                type: string
    RelaySession:
      type: object
      properties:
        session_id:
          type: string
        status:
          type: string
        relays:
          type: array
          items:
            type: object
            properties:
              host:
                type: string
              port:
                type: integer