Appearance
Sandbox API Overview
Sufy Sandbox Open API lets you manage sandbox instances, templates, and secret injection rules over HTTP. All APIs use a region-specific host. Choose the endpoint that matches the region where your sandbox is deployed.
Service Endpoints
| Region | Region ID | API Endpoint |
|---|---|---|
| United States (Dallas 1) | us-south-1 | https://us-south-1-sandbox.sufyapi.com |
Authentication
Sandbox instance and template management APIs use the X-API-Key request header:
http
X-API-Key: <SUFY_API_KEY>Some template build APIs also accept an API key in Bearer format:
http
Authorization: Bearer <SUFY_API_KEY>For template build APIs, send the API key as a Bearer token when the endpoint requires it.
Secret injection rule management APIs use the Sufy account authorization header:
http
Authorization: Sufy <SignedToken>SignedToken is generated by signing the request with your Sufy AK/SK.
You can get SUFY_API_KEY from Sufy API Key Management.
Common Headers
| Header | Required | Description |
|---|---|---|
X-API-Key | Required by some APIs | API key for sandbox instance and template management APIs |
Authorization | Required by some APIs | Bearer API key for template build APIs, or Sufy signature for secret injection rule APIs |
Content-Type | Required when a request body is present | Always application/json |
API Groups
| Group | Documentation | Description |
|---|---|---|
| Sandbox Instances | Sandbox Instances | Create, query, connect, pause, resume, and delete sandboxes, and query logs and metrics |
| Templates | Templates | Create templates, upload build files, start builds, and query template and build status |
| Secret Injection | Secret Injection | Manage reusable HTTPS request secret injection rules stored by the platform |
| Sandbox Runtime | Sandbox Runtime | Access envd runtime status, environment variables, and resource metrics |
| Processes and Terminals | Processes and Terminals | Start commands through envd, connect to processes, send input, and manage PTYs |
| File System | File System | Read and write files through envd, list directories, move or delete files, and watch directory changes |
Error Responses
API errors are returned as JSON:
| Field | Type | Description |
|---|---|---|
code | integer | Error code |
message | string | Error message |
Example:
json
{
"code": 400,
"message": "invalid request"
}Status Codes
| Status Code | Description |
|---|---|
200 | Request succeeded |
201 | Resource created |
202 | Request accepted and an async task has started |
204 | Request succeeded with no response body |
400 | Invalid request parameters |
401 | Authentication failed |
403 | Permission denied |
404 | Resource not found |
409 | Current resource state conflicts with the request |
500 | Server error |
Request Example
bash
curl -X GET "$SUFY_SANDBOX_API_URL/v2/sandboxes" \
-H "X-API-Key: $SUFY_API_KEY"