# 专用服务器
## ⚡ 部署
## \[v2] Deploy
> \\[Rate Limit: 40/seconds]\ Initiate a new deployment. A deployment is a containerized server instance of an application version running on the Edgegap platform.
```json
{"openapi":"3.0.1","info":{"title":"Edgegap v2 API","version":"2026.03.16"},"servers":[{"url":"https://api.edgegap.com/v2","description":"Edgegap V2"}],"security":[{"api-token":[]}],"components":{"securitySchemes":{"api-token":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"DeploymentCreate":{"required":["application","users","version"],"properties":{"application":{"type":"string","description":"Name of the application that will be deployed"},"version":{"type":"string","description":"Name of the version within the application that will be deployed"},"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"}},"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"}},"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":{}}},"type":"object"},"DeploymentEnvironmentVariable":{"required":["is_hidden","key","value"],"properties":{"key":{"type":"string","description":"Environment variable key"},"value":{"type":"string","description":"Environment variable value"},"is_hidden":{"type":"boolean","description":"An hidden environment variable is not shown in the UI"}},"type":"object"},"BasicWebhook":{"required":["url"],"properties":{"url":{"type":"string","description":"Webhook URL"}},"type":"object"}}},"paths":{"/deployments":{"post":{"summary":"[v2] Deploy","deprecated":false,"description":"[Rate Limit: 40/seconds] 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"}}}},"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"}},"required":["request_id"]}}},"headers":{}},"400":{"description":"Client Side Request Error","content":{"application/json":{"schema":{"title":"","type":"object","properties":{"message":{"type":"string","description":"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"},"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"},"message":{"type":"string","description":"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"},"details":{"type":"object","description":"Additional error details","properties":{}}},"required":["message"]}}},"headers":{}}}}}}}
```
{% openapi src="" path="/v1/status/{request\_id}" method="get" %}
{% endopenapi %}
{% openapi src="" path="/v1/stop/{request\_id}" method="delete" %}
{% endopenapi %}
{% openapi src="" path="/v1/self/stop/{request\_id}/{access\_point\_id}" method="delete" %}
{% endopenapi %}
{% openapi src="" path="/v1/deployments/bulk-stop" method="post" %}
{% endopenapi %}
{% openapi src="" path="/v1/deployments" method="get" %}
{% endopenapi %}
{% openapi src="" path="/v1/locations" method="get" %}
{% endopenapi %}
{% openapi src="" path="/v1/deployment/{request\_id}/container-logs" method="get" %}
{% endopenapi %}
{% openapi src="" path="/v1/metrics/deployment/{request\_id}" method="get" %}
{% endopenapi %}
### 传统版 \[v1]
{% hint style="warning" %}
传统 v1/deploy API 端点是 **过时，已被 v2 API 取代** - 参见 [#deployments](#deployments "mention").
{% endhint %}
## Create a Deployment request.
> \[Rate Limit: 40/second] Create a new deployment. A deployment is a containerized instance of an application version running on the Edgegap platform.
```json
{"openapi":"3.1.1","info":{"title":"Edgegap V1","version":"0.0.0"},"tags":[{"name":"Deployments","description":"Deployments Control API - Please refer to this documentation to get started with deployments."}],"servers":[{"url":"https://api.edgegap.com"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"authorization","description":"To access Edgegap API, generate (and view) your secret tokens in Dashboard - User Settings / Tokens. Add your secret token with each API request as an HTTP header (include the word token): `Authorization: token xxxxxxxx-e458-4592-b607-c2c28afd8b62`"}},"schemas":{"Request":{"required":["request_app","request_dns","request_id","request_user_count","request_version"],"properties":{"request_id":{"type":"string","description":"The identifier of the deployment request. This is used to track the deployment."},"request_dns":{"type":"string","description":"This is the FQDN that allow to connect to your Deployment. It will not resolve until the deployment is ready."},"request_app":{"type":"string","description":"The application that has been deployed."},"filters":{"type":"array","description":"List of filters applied to choose the location of the deployment.","items":{"$ref":"#/components/schemas/DeploymentFilterModel"}},"request_version":{"type":"string","description":"The version of the application that has been deployed."},"request_user_count":{"type":"integer","description":"This is the number of IP you have provided in the deployment request."},"tags":{"type":"array","description":"List of tags that have been injected in the deployment request. This field will only be present if tags were provided in the request.","items":{"type":"string"}},"container_log_storage":{"description":"Endpoint storage configuration that will be used to store the container logs when the deployment will be deleted. This field will only be present if container log storage was provided in the request.","$ref":"#/components/schemas/ContainerLogStorageModel"},"location":{"description":"The desired location centroid of the deployment. This field will only be present if a location was provided in the request.","$ref":"#/components/schemas/LocationModel"},"ap_sort_strategy":{"type":"string","description":"(DEPRECATED) - Will only be present if the request was made with the ap_sort_strategy field.","enum":["basic","weighted"]}},"type":"object"},"DeploymentFilterModel":{"required":["field","filter_type","values"],"properties":{"field":{"type":"string","description":"The deployment's field to filter on. See https://docs.edgegap.com/learn/advanced-features/deployments#filter-deployments for more details."},"values":{"type":"array","description":"The values to filter on.","items":{"type":"string"}},"filter_type":{"type":"string","description":"The type of filter.","enum":["any","all","not"]}},"type":"object"},"ContainerLogStorageModel":{"required":["enabled"],"properties":{"enabled":{"type":"boolean","description":"If true, the container logs will be stored in the provided endpoint storage at the end of the request. If false, the container logs will not be stored, even if set up in the app version."},"endpoint_storage":{"type":"string","description":"The name of the endpoint storage to be used. It must be the same as the one set on the dashboard when created. If container log storage is enabled without this parameter, we will try to take the app version endpoint storage. If there is no endpoint storage in your app version, the container logs will not be stored. If we don't find any endpointstorage associated with this name, the container logs will not be stored."}},"type":"object"},"LocationModel":{"required":["latitude","longitude"],"properties":{"latitude":{"type":"number","description":"Desired Latitude"},"longitude":{"type":"number","description":"Desired Longitude"}},"type":"object"},"Error":{"required":["message"],"properties":{"message":{"type":"string","description":"A message depending of the request termination"}},"type":"object"},"DeployModel":{"required":["app_name"],"properties":{"app_name":{"type":"string","description":"The application you want to deploy a version of."},"version_name":{"type":"string","description":"The application version you want to deploy a container, if not present, the last version created is automatically chosen."},"is_public_app":{"type":"boolean","description":"(DEPRECATED) - No longer used and you don't need to set it.","default":false},"ip_list":{"type":"array","description":"This parameter is not optional, but mutually exclusive with the geo_ip_list parameter. One of them is required. List of IP representing your users. These will be used to determine the best location for your deployment.","items":{"type":"string"}},"geo_ip_list":{"type":"array","description":"This parameter is not optional, but mutually exclusive with the ip_list parameter. One of them is required. List of IP of your user with their location (latitude, longitude). We will use the coordinates instead of the IPs to determine the best location for your deployment.","items":{"$ref":"#/components/schemas/GeoIpListModel"}},"telemetry_profile_uuid_list":{"type":"array","description":"(DEPRECATED)","items":{"type":"string"}},"env_vars":{"type":"array","description":"List of environment variables to set in your deployment instance. These variables will be available in your container.","items":{"$ref":"#/components/schemas/DeployEnvModel"}},"skip_telemetry":{"type":"boolean","description":"If true, the deployment will skip the telemetry measurement. This result in a faster time to deploy.","default":true},"location":{"description":"Specify the centroid of the deployment instead of letting the system choose the best location. The system will do a best effort to deploy the container in the closest location to the specified coordinates.","$ref":"#/components/schemas/LocationModel"},"webhook_url":{"type":"string","description":"A URL to send a POST request when the deployment is ready. The request will contain the deployment status. The content of the request is the same as the `v1/status/{request_id}` endpoint."},"tags":{"type":"array","description":"List of tags associated with the deployment. These tags will be shown in the dashboard.","items":{"type":"string"}},"container_log_storage":{"description":"Configuration for the container log storage. This will override the app version default configuration if set.","$ref":"#/components/schemas/ContainerLogStorageModel"},"filters":{"type":"array","description":"List of filters to apply to the deployment. The deployment will be deployed in a location that match the filters.","items":{"$ref":"#/components/schemas/DeploymentFilterModel"}},"ap_sort_strategy":{"type":"string","description":"(DEPRECATED) - No longer used and you don't need to set it.","enum":["basic","weighted"]},"command":{"type":["string","null"],"description":"Allows to override the container command for this deployment. This is an advanced feature and should be used with caution.If set to null, the default command of the container will be used."},"arguments":{"type":["string","null"],"description":"Allows to override the container arguments for this deployment. This is an advanced feature and should be used with caution.If set to null, the default arguments of the container will be used."}},"type":"object"},"GeoIpListModel":{"required":["ip","latitude","longitude"],"properties":{"ip":{"type":"string","description":"IP address"},"latitude":{"type":"number","description":"Latitude of the IP/User"},"longitude":{"type":"number","description":"Longitude of the IP/User"}},"type":"object"},"DeployEnvModel":{"required":["key","value"],"properties":{"key":{"type":"string","description":"Key of the environment variable. This key will be used to access the value in your container."},"value":{"type":"string","description":"Value of the environment variable. This value will be set in your container. Max 4096 characters."},"is_hidden":{"type":"boolean","description":"If true, the environment variable will be encrypted and only decrypted in the container."}},"type":"object"}}},"paths":{"/v1/deploy":{"post":{"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Create a Deployment request.","description":"[Rate Limit: 40/second] Create a new deployment. A deployment is a containerized instance of an application version running on the Edgegap platform.","operationId":"deploy","tags":["Deployments"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployModel"}}},"required":true}}}}}
```
## 🗺️ 私有舰队
## Deploy to Fleet
> \\[Rate Limit: 40/seconds]\ Initiate a new private fleet deployment. A deployment is a containerized server instance of an application version running on the Edgegap platform.
```json
{"openapi":"3.0.1","info":{"title":"Edgegap v2 API","version":"2026.03.16"},"servers":[{"url":"https://api.edgegap.com/v2","description":"Edgegap V2"}],"security":[{"api-token":[]}],"components":{"securitySchemes":{"api-token":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"PrivateFleetDeploymentCreate":{"type":"object","properties":{"application":{"type":"string","description":"Name of the application that will be deployed"},"version":{"type":"string","description":"Name of the version within the application that will be deployed"},"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"},"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"}},"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"}},"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"]},"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":{}}},"type":"object"},"DeploymentEnvironmentVariable":{"required":["is_hidden","key","value"],"properties":{"key":{"type":"string","description":"Environment variable key"},"value":{"type":"string","description":"Environment variable value"},"is_hidden":{"type":"boolean","description":"An hidden environment variable is not shown in the UI"}},"type":"object"},"BasicWebhook":{"required":["url"],"properties":{"url":{"type":"string","description":"Webhook URL"}},"type":"object"},"Error":{"required":["message"],"properties":{"message":{"type":"string","description":"Error message"},"details":{"type":"object","description":"Additional error details","properties":{}}},"type":"object"},"ParameterError422":{"required":["message","request_id"],"properties":{"request_id":{"type":"string","description":"Request ID. Unique identifier of the deployment request"},"message":{"type":"string","description":"Error message"}},"type":"object"}}},"paths":{"/private-fleets/deployments":{"post":{"summary":"Deploy to Fleet","deprecated":false,"description":"[Rate Limit: 40/seconds] 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"}}}},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"title":"","type":"object","properties":{"request_id":{"type":"string","description":"Request ID. Unique identifier of the deployment request"}},"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":{}}}}}}}
```
## List Private Fleet Hosts
> \\[Rate Limit: 10/seconds]\ List all hosts in a private fleet.
```json
{"openapi":"3.0.1","info":{"title":"Edgegap v2 API","version":"2026.03.16"},"servers":[{"url":"https://api.edgegap.com/v2","description":"Edgegap V2"}],"security":[{"api-token":[]}],"components":{"securitySchemes":{"api-token":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/private-fleets/{fleet-name}/hosts":{"get":{"summary":"List Private Fleet Hosts","deprecated":false,"description":"[Rate Limit: 10/seconds] 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"}}],"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."},"status":{"type":"string","description":"Lifecycle stage of the host, only ACTIVE hosts accept deployments.","enum":["PENDING","ACTIVE"]},"ip_address":{"type":"string","description":"Public IP address of the host.","nullable":true},"latitude":{"type":"number","description":"Approximate geographic latitude of the host.","nullable":true},"longitude":{"type":"number","description":"Approximate geographic longitude of the host.","nullable":true},"city":{"type":"string","description":"City in which the host is located.","nullable":true},"country":{"type":"string","description":"Country in which the host is located.","nullable":true},"continent":{"type":"string","description":"Continent in which the host is located.","nullable":true},"allocated_cpu_units":{"type":"integer","description":"Total virtual CPU units currently in use for deployments, beacons, and orchestration.","nullable":true},"allocated_memory_mb":{"type":"integer","description":"Total memory in MB currently in use for deployments, beacons, and orchestration."},"allocatable_cpu_units":{"type":"integer","description":"Total available virtual CPU units for deployments.","nullable":true},"allocatable_memory_mb":{"type":"integer","description":"Total available memory in MB for deployments.","nullable":true},"beacon":{"type":"object","properties":{"tcp_port":{"type":"integer","description":"External beacon TCP port used to perform TCP ping."},"udp_port":{"type":"integer","description":"External beacon UDP port used to perform UDP ping."},"ip_address":{"type":"string","description":"Public IP address used to perform ping measurement."}},"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."},"updated_at":{"type":"string","description":"Timestamp of last update in UTC, ISO 8601 format."},"centroid":{"type":"object","properties":{"label":{"type":"string","description":"Human readable label."},"latitude":{"type":"number","description":"Approximate geographic latitude of the centroid."},"longitude":{"type":"number","description":"Approximate geographic longitude of the centroid."},"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."}},"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."},"scheduled_at":{"type":"string","description":"Timestamp of scheduled deletion in UTC, ISO 8601 format."}},"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."},"memory_mb":{"type":"integer","description":"Host specification memory MB selected during fleet creation."},"base_clock_speed_mhz":{"type":"integer","description":"Host specification base CPU clock frequency selected during fleet creation."}},"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"},"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"},"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"},"details":{"type":"object","description":"Additional error details","properties":{}}},"required":["message"]}}},"headers":{}}}}}}}
```
## 🔖 标签
{% openapi src="" path="/v1/deployments/{request\_id}/tags" method="get" %}
{% endopenapi %}
{% openapi src="" path="/v1/deployments/{request\_id}/tags/{tag\_name}" method="get" %}
{% endopenapi %}
{% openapi src="" path="/v1/deployments/{request\_id}/tags" method="post" %}
{% endopenapi %}
{% openapi src="" path="/v1/deployments/{request\_id}/tags/{tag\_name}" method="delete" %}
{% endopenapi %}
{% openapi src="" path="/v1/deployments/{request\_id}/tags/{tag\_name}" method="patch" %}
{% endopenapi %}