Skip to main content
GET
/
v1
/
sandboxes
/
{sandboxId}
/
endpoints
/
{port}
Get Sandbox Endpoint
curl --request GET \
  --url https://api.example.com/v1/sandboxes/{sandboxId}/endpoints/{port}
{
  "200": {},
  "401": {},
  "403": {},
  "404": {},
  "500": {},
  "endpoint": "<string>",
  "headers": {},
  "X-Request-ID": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alibaba/OpenSandbox/llms.txt

Use this file to discover all available pages before exploring further.

Get the public access endpoint URL for accessing a service running on a specific port within the sandbox. The service must be listening on the specified port inside the sandbox for the endpoint to be available.

​
Path Parameters

​
sandboxId
string
required
Unique sandbox identifier
​
port
integer
required
Port number where the service is listening inside the sandbox
  • Minimum: 1
  • Maximum: 65535

​
Query Parameters

​
use_server_proxy
boolean
Whether to return a server-proxied URLDefault: false

​
Response

​
endpoint
string
Public URL to access the service from outside the sandbox.Format: {endpoint-host}/sandboxes/{sandboxId}/port/{port}Example: endpoint.opensandbox.io/sandboxes/abc123/port/8080
​
headers
object
Requests targeting the sandbox must include the corresponding header(s).Key-value pairs where keys are header names and values are header values.

​
Response Headers

​
X-Request-ID
string
Unique request identifier for tracing

​
Status Code

​
200
OK
Endpoint retrieved successfully.Returns the public URL for accessing the service on the specified port.

​
Error Responses

​
401
Unauthorized
Authentication credentials are missing or invalid
​
403
Forbidden
The authenticated user lacks permission for this operation
​
404
Not Found
The requested sandbox does not exist
​
500
Internal Server Error
An unexpected server error occurred

​
Example Request

curl -X GET http://localhost:8080/v1/sandboxes/sandbox-abc123/endpoints/8080 \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"

​
Example Response

{
  "endpoint": "endpoint.opensandbox.io/sandboxes/sandbox-abc123/port/8080",
  "headers": {
    "X-Sandbox-Token": "token-value"
  }
}

​
Usage Notes

​
Service Availability

The service must be actively listening on the specified port inside the sandbox for the endpoint to be functional. If your application hasn’t started listening yet, the endpoint URL will be returned but connections may fail until the service is ready.

​
Required Headers

When making requests to the returned endpoint URL, you must include any headers specified in the headers field of the response. These headers are required for authentication and routing to the correct sandbox.

​
Example with Headers

curl http://endpoint.opensandbox.io/sandboxes/sandbox-abc123/port/8080 \
  -H "X-Sandbox-Token: token-value"

​
Common Use Cases

  1. Web Applications: Access web servers running inside sandboxes (e.g., Flask, Express)
  2. APIs: Connect to API servers for testing or integration
  3. Development Servers: Access development tools like Jupyter notebooks or debugging interfaces
  4. Database Connections: Connect to databases running in sandboxes (though consider using internal networking for production)

​
Port Forwarding

The endpoint acts as a public gateway to services inside the sandbox. The sandbox’s internal port is mapped to the public endpoint URL, allowing external access without exposing the sandbox directly.

​
Security Considerations

  • Endpoint URLs include authentication tokens in the required headers
  • Endpoints are scoped to specific sandboxes and ports
  • Access is controlled via API key authentication
  • Consider using use_server_proxy=true for additional security layers

​
Server Proxy Mode

When use_server_proxy=true is specified, the returned endpoint URL will route through a server-side proxy for additional security and monitoring capabilities. 
curl -X GET "http://localhost:8080/v1/sandboxes/sandbox-abc123/endpoints/8080?use_server_proxy=true" \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"
Benefits of server proxy mode:
  • Enhanced security through additional authentication layers
  • Request/response logging and monitoring
  • Rate limiting and access control
  • Protocol translation and compatibility layers

Build docs developers (and LLMs) love

Get started for freeTalk to us