edgegap-v2-openapi.yaml

openapi: 3.0.1
info:
  title: Edgegap v2 API
  description: 'Maintained by [Edgegap Technologies](https://edgegap.com/)'
  version: 2026.03.16
tags: []
paths:
  /deployments:
    post:
      summary: '[v2] Deploy'
      deprecated: false
      description: >-
        <strong>[Rate Limit: 40/seconds]</strong> Initiate a new deployment. A
        deployment is a containerized server instance of an application version
        running on the Edgegap platform.
      operationId: deployment-create
      tags: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentCreate'
            examples: {}
      responses:
        '202':
          description: Deployment Request Accepted
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  request_id:
                    type: string
                    description: Request ID. Unique identifier of the deployment request
                    example: a69f8e3e0555
                required:
                  - request_id
          headers: {}
        '400':
          description: Client Side Request Error
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                    example: Error message
                  details:
                    type: object
                    description: Additional error details
                    properties: {}
                required:
                  - message
          headers: {}
        '401':
          description: Unauthorized - Missing Token
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                    example: Error message
                  details:
                    type: object
                    description: Additional error details
                    properties: {}
                required:
                  - message
          headers: {}
        '422':
          description: Couldn't Allocate Server
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  request_id:
                    type: string
                    description: Request ID. Unique identifier of the deployment request
                    example: a69f8e3e0555
                  message:
                    type: string
                    description: Error message
                    example: Error message
                required:
                  - request_id
                  - message
          headers: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                    example: Error message
                  details:
                    type: object
                    description: Additional error details
                    properties: {}
                required:
                  - message
          headers: {}
      security:
        - api-token: []
  /private-fleets/{fleet-name}/hosts:
    get:
      summary: List Private Fleet Hosts
      deprecated: false
      description: >-
        <strong>[Rate Limit: 10/seconds]</strong> List all hosts in a private
        fleet.
      operationId: private-fleet-hosts-list
      tags: []
      parameters:
        - name: fleet-name
          in: path
          description: Name of your private fleet.
          required: true
          schema:
            type: string
            example: test-fleet
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        host_id:
                          type: string
                          description: >-
                            Unique private fleet host identifier, used to deploy
                            on this host.
                          example: alpha-north-america-95fab093
                        status:
                          type: string
                          description: >-
                            Lifecycle stage of the host, only ACTIVE hosts
                            accept deployments.
                          enum:
                            - PENDING
                            - ACTIVE
                          example: ACTIVE
                        ip_address:
                          type: string
                          description: Public IP address of the host.
                          nullable: true
                          example: 192.53.120.48
                        latitude:
                          type: number
                          description: Approximate geographic latitude of the host.
                          nullable: true
                          example: 43.6173
                        longitude:
                          type: number
                          description: Approximate geographic longitude of the host.
                          nullable: true
                          example: -79.3186
                        city:
                          type: string
                          description: City in which the host is located.
                          nullable: true
                          example: Toronto
                        country:
                          type: string
                          description: Country in which the host is located.
                          nullable: true
                          example: Canada
                        continent:
                          type: string
                          description: Continent in which the host is located.
                          nullable: true
                          example: North America
                        allocated_cpu_units:
                          type: integer
                          description: >-
                            Total virtual CPU units currently in use for
                            deployments, beacons, and orchestration.
                          nullable: true
                          example: 1152
                        allocated_memory_mb:
                          type: integer
                          description: >-
                            Total memory in MB currently in use for deployments,
                            beacons, and orchestration.
                          example: 2176
                        allocatable_cpu_units:
                          type: integer
                          description: Total available virtual CPU units for deployments.
                          nullable: true
                          example: 12928
                        allocatable_memory_mb:
                          type: integer
                          description: Total available memory in MB for deployments.
                          nullable: true
                          example: 25178
                        beacon:
                          type: object
                          properties:
                            tcp_port:
                              type: integer
                              description: >-
                                External beacon TCP port used to perform TCP
                                ping.
                              example: 30974
                            udp_port:
                              type: integer
                              description: >-
                                External beacon UDP port used to perform UDP
                                ping.
                              example: 31843
                            ip_address:
                              type: string
                              description: >-
                                Public IP address used to perform ping
                                measurement.
                              example: 192.53.120.48
                          required:
                            - tcp_port
                            - udp_port
                            - ip_address
                          description: >-
                            Assigned beacon information, if enabled for this
                            fleet.
                          nullable: true
                        created_at:
                          type: string
                          description: Timestamp of creation in UTC, ISO 8601 format.
                          example: '2025-11-26T16:32:30.825138Z'
                        updated_at:
                          type: string
                          description: Timestamp of last update in UTC, ISO 8601 format.
                          example: '2025-11-26T16:32:30.825144Z'
                        centroid:
                          type: object
                          properties:
                            label:
                              type: string
                              description: Human readable label.
                              example: Alpha
                            latitude:
                              type: number
                              description: Approximate geographic latitude of the centroid.
                              example: 43.98884323260136
                            longitude:
                              type: number
                              description: >-
                                Approximate geographic longitude of the
                                centroid.
                              example: -78.67419552556069
                            radius_km:
                              type: number
                              description: >-
                                Approximate geographic radius used to pick
                                primary and fallback locations.
                            desired_host_count:
                              type: integer
                              description: >-
                                Requested amount of hosts to be started under
                                this centroid.
                              example: 1
                          required:
                            - label
                            - latitude
                            - longitude
                            - radius_km
                            - desired_host_count
                          description: >-
                            Centroid information used to orchestrate placement
                            of the host.
                        delete_schedule:
                          type: object
                          properties:
                            uuid:
                              type: string
                              description: Unique identifier of deletion schedule.
                              example: 10287c9b-a6e2-4909-84c8-59daf74895b5
                            scheduled_at:
                              type: string
                              description: >-
                                Timestamp of scheduled deletion in UTC, ISO 8601
                                format.
                              example: '2025-11-30T23:59:00Z'
                          description: If defined, specified when the host will be deleted.
                          required:
                            - uuid
                            - scheduled_at
                          nullable: true
                        fleet_host_specifications:
                          type: object
                          properties:
                            cpu_units:
                              type: integer
                              description: >-
                                Host specification vCPU units selected during
                                fleet creation.
                              example: 16384
                            memory_mb:
                              type: integer
                              description: >-
                                Host specification memory MB selected during
                                fleet creation.
                              example: 32768
                            base_clock_speed_mhz:
                              type: integer
                              description: >-
                                Host specification base CPU clock frequency
                                selected during fleet creation.
                              example: 2000
                          required:
                            - cpu_units
                            - memory_mb
                            - base_clock_speed_mhz
                      description: List of private fleet hosts.
                      required:
                        - host_id
                        - status
                        - allocated_cpu_units
                        - allocated_memory_mb
                        - created_at
                        - updated_at
                        - centroid
                        - fleet_host_specifications
                required:
                  - data
          headers: {}
        '400':
          description: ''
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                    example: Error message
                  details:
                    type: object
                    description: Additional error details
                    properties: {}
                required:
                  - message
          headers: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                    example: Error message
                  details:
                    type: object
                    description: Additional error details
                    properties: {}
                required:
                  - message
          headers: {}
        '500':
          description: ''
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                    example: Error message
                  details:
                    type: object
                    description: Additional error details
                    properties: {}
                required:
                  - message
          headers: {}
      security:
        - api-token: []
  /private-fleets/deployments:
    post:
      summary: Deploy to Fleet
      deprecated: false
      description: >-
        <strong>[Rate Limit: 40/seconds]</strong> Initiate a new private fleet
        deployment. A deployment is a containerized server instance of an
        application version running on the Edgegap platform.
      operationId: private-fleets-deployment-create
      tags: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateFleetDeploymentCreate'
            examples: {}
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  request_id:
                    type: string
                    description: Request ID. Unique identifier of the deployment request
                    example: a69f8e3e0555
                required:
                  - request_id
          headers: {}
        '400':
          description: >-
            Invalid Application or Application Version. No deployment has been
            created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers: {}
        '401':
          description: Unauthorized. No deployment has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers: {}
        '422':
          description: >-
            Could not allocate an Edge Server for the deployment. A deployment
            has been created. Deployment is in error state. You can delete it
            manually or it will be deleted automatically by our system after
            some some times
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterError422'
          headers: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers: {}
      security:
        - api-token: []
components:
  schemas:
    DeploymentResponse:
      required:
        - request_id
      properties:
        request_id:
          type: string
          description: Request ID. Unique identifier of the deployment request
          example: a69f8e3e0555
      type: object
    ParameterError422:
      required:
        - message
        - request_id
      properties:
        request_id:
          type: string
          description: Request ID. Unique identifier of the deployment request
          example: a69f8e3e0555
        message:
          type: string
          description: Error message
          example: Error message
      type: object
    Error:
      required:
        - message
      properties:
        message:
          type: string
          description: Error message
          example: Error message
        details:
          type: object
          description: Additional error details
          properties: {}
      type: object
    PrivateFleetDeploymentCreate:
      type: object
      properties:
        application:
          type: string
          description: Name of the application that will be deployed
          example: my-app
        version:
          type: string
          description: Name of the version within the application that will be deployed
          example: 25.05.30-16.45.19-04
        require_cached_locations:
          type: boolean
          default: false
          description: Deploy faster by limiting placement to locations with cached image.
          nullable: true
        private_host_ids:
          type: array
          items:
            type: string
            example: alpha-north-america-95fab093
          description: >-
            Preferred and prioritized Private Host IDs to try before overflowing
            to cloud.
          minItems: 1
          uniqueItems: true
        users:
          type: array
          description: >-
            List of users. These users will be used to select the locations for
            the deployment
          minItems: 1
          items:
            $ref: '#/components/schemas/User'
          example:
            - user_type: ip_address
              user_data:
                ip_address: 75.28.35.192
            - user_type: geo_coordinates
              user_data:
                latitude: 45.508888
                longitude: -73.561668
        environment_variables:
          type: array
          description: List of environment variables to inject into the deployment
          items:
            $ref: '#/components/schemas/DeploymentEnvironmentVariable'
        tags:
          type: array
          description: List of tags to associate with the deployment
          items:
            type: string
            example: my-custom-tag
        webhook_on_ready:
          description: Webhook to call when the deployment is ready
          allOf:
            - $ref: '#/components/schemas/BasicWebhook'
        webhook_on_error:
          description: Webhook to call when the deployment is in error
          allOf:
            - $ref: '#/components/schemas/BasicWebhook'
        webhook_on_terminated:
          description: Webhook to call when the deployment is terminated
          allOf:
            - $ref: '#/components/schemas/BasicWebhook'
      required:
        - application
        - users
        - version
        - private_host_ids
    DeploymentCreate:
      required:
        - application
        - users
        - version
      properties:
        application:
          type: string
          description: Name of the application that will be deployed
          example: my-app
        version:
          type: string
          description: Name of the version within the application that will be deployed
          example: 25.05.30-16.45.19-04
        require_cached_locations:
          type: boolean
          default: false
          description: Deploy faster by limiting placement to locations with cached image.
          nullable: true
        users:
          type: array
          description: >-
            List of users. These users will be used to select the locations for
            the deployment
          minItems: 1
          items:
            $ref: '#/components/schemas/User'
          example:
            - user_type: ip_address
              user_data:
                ip_address: 75.28.35.192
            - user_type: geo_coordinates
              user_data:
                latitude: 45.508888
                longitude: -73.561668
        environment_variables:
          type: array
          description: List of environment variables to inject into the deployment
          items:
            $ref: '#/components/schemas/DeploymentEnvironmentVariable'
        tags:
          type: array
          description: List of tags to associate with the deployment
          items:
            type: string
            example: my-custom-tag
        webhook_on_ready:
          description: Webhook to call when the deployment is ready
          allOf:
            - $ref: '#/components/schemas/BasicWebhook'
        webhook_on_error:
          description: Webhook to call when the deployment is in error
          allOf:
            - $ref: '#/components/schemas/BasicWebhook'
        webhook_on_terminated:
          description: Webhook to call when the deployment is terminated
          allOf:
            - $ref: '#/components/schemas/BasicWebhook'
      type: object
    User:
      required:
        - user_data
        - user_type
      properties:
        user_type:
          type: string
          description: Type of user (e.g., ip_address or geo_coordinates)
        user_data:
          type: object
          description: Dynamic user data depending on user_type
          properties: {}
          example:
            ip_address: 75.28.35.192
      type: object
    DeploymentEnvironmentVariable:
      required:
        - is_hidden
        - key
        - value
      properties:
        key:
          type: string
          description: Environment variable key
          example: MY_ENVIRONMENT_VARIABLE
        value:
          type: string
          description: Environment variable value
          example: my-value
        is_hidden:
          type: boolean
          description: An hidden environment variable is not shown in the UI
          example: false
      type: object
    BasicWebhook:
      required:
        - url
      properties:
        url:
          type: string
          description: Webhook URL
          example: https://my-webhook.com
      type: object
  responses: {}
  securitySchemes:
    api-token:
      type: apiKey
      in: header
      name: Authorization
servers:
  - url: https://api.edgegap.com/v2
    description: Edgegap V2
security:
  - api-token: []