Projects API
Complete API reference for managing projects. Projects help organize your sandboxes into logical groups for better management and organization of your development environments.
Authentication Required: All API requests require authentication using the X-API-Key header with your API key.
Project Concepts
Projects in ScaleBox provide a way to organize your sandboxes into logical groups for better management and organization of your development environments.
Project Features
- Organization - Group related sandboxes together by project, team, or purpose
- Default Project - Set a default project where new sandboxes are automatically placed
- Access Control - Project access is controlled by user account permissions
- Flexible Management - Move sandboxes between projects as your organization evolves
API Endpoints
Create Project
POST /v1/projects
Create a new project to organize sandboxes.
Request Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | Yes | - | Project name (2-100 characters) |
| description | string | No | - | Detailed description of the project purpose |
| is_default | boolean | No | false | Whether this should be the default project for new sandboxes |
Example
curl -X POST https://api.scalebox.dev/v1/projects \
-H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
-H "Content-Type: application/json" \
-d '{
"name": "frontend-development",
"description": "Project for all frontend development sandboxes",
"is_default": false
}'Response
{
"project_id": "prj-abc123def456789",
"name": "frontend-development",
"description": "Project for all frontend development sandboxes",
"is_default": false,
"owner_user_id": "usr-xyz789abc123456",
"owner_account_id": "acc-123456789",
"sandbox_count": 0,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}List Projects
GET /v1/projects
List all projects accessible to the authenticated user.
Example
curl -X GET https://api.scalebox.dev/v1/projects \
-H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"Response
{
"projects": [
{
"project_id": "prj-abc123def456789",
"name": "frontend-development",
"description": "Project for all frontend development sandboxes",
"is_default": false,
"owner_user_id": "usr-xyz789abc123456",
"owner_account_id": "acc-123456789",
"sandbox_count": 5,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
},
{
"project_id": "prj-def456ghi789012",
"name": "backend-services",
"description": "API and microservices development",
"is_default": true,
"owner_user_id": "usr-xyz789abc123456",
"owner_account_id": "acc-123456789",
"sandbox_count": 3,
"created_at": "2024-01-14T09:15:00Z",
"updated_at": "2024-01-15T08:45:00Z"
}
],
"total": 2
}Get Project
GET /v1/projects/{project_id}
Get detailed information about a specific project.
Example
curl -X GET https://api.scalebox.dev/v1/projects/prj-abc123def456789 \
-H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"Update Project
PUT /v1/projects/{project_id}
Update project name, description, and settings.
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | No | Updated project name |
| description | string | No | Updated project description |
| is_default | boolean | No | Whether this should be the default project |
Example
curl -X PUT https://api.scalebox.dev/v1/projects/prj-abc123def456789 \
-H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678" \
-H "Content-Type: application/json" \
-d '{
"name": "full-stack-development",
"description": "Updated project for full-stack development work"
}'Delete Project
DELETE /v1/projects/{project_id}
Delete a project (must be empty of sandboxes).
Example
curl -X DELETE https://api.scalebox.dev/v1/projects/prj-abc123def456789 \
-H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"Get Project Sandboxes
GET /v1/projects/{project_id}/sandboxes
List all sandboxes in a specific project.
Example
curl -X GET https://api.scalebox.dev/v1/projects/prj-abc123def456789/sandboxes \
-H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"Response
{
"project_id": "prj-abc123def456789",
"sandboxes": [
{
"sandbox_id": "sbx-abc123def456789",
"name": "react-frontend-dev",
"status": "running",
"template_id": "tpl-react-dev",
"cpu_count": 2,
"memory_mb": 4096,
"created_at": "2024-01-15T10:30:00Z",
"sandbox_domain": "sbx-abc123def456789.scalebox.dev"
}
],
"total": 1
}Add Sandbox to Project
POST /v1/projects/{project_id}/sandboxes/{sandbox_id}/add
Add an existing sandbox to a project.
Example
curl -X POST https://api.scalebox.dev/v1/projects/prj-abc123def456789/sandboxes/sbx-def456ghi789012/add \
-H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"Evict Sandbox from Project
POST /v1/projects/{project_id}/sandboxes/{sandbox_id}/evict
Remove a sandbox from a project.
Example
curl -X POST https://api.scalebox.dev/v1/projects/prj-abc123def456789/sandboxes/sbx-def456ghi789012/evict \
-H "X-API-Key: sk-1234567890abcdef1234567890abcdef12345678"Project Management
Best practices for effective project management in ScaleBox:
| Practice | Description |
|---|---|
| Default Project | Set one project as default to automatically organize new sandboxes |
| Project Naming | Use descriptive names that reflect the purpose or team (e.g., "frontend-team", "api-development") |
| Sandbox Organization | Group related sandboxes by project phase, environment type, or development team |
Sandbox Organization
Projects provide flexible ways to organize sandboxes:
| Feature | Description |
|---|---|
| Automatic Assignment | New sandboxes are automatically assigned to your default project |
| Manual Management | Use add/evict endpoints to move sandboxes between projects as needed |
| Project Deletion | Projects must be empty of sandboxes before they can be deleted |
Error Handling
Common error scenarios and how to handle them:
| Scenario | Description |
|---|---|
| Project Name Validation | Names must be 2-100 characters and follow standard naming conventions |
| Access Control | Users can only access projects within their account |
| Project Dependencies | Projects with sandboxes cannot be deleted - move or delete sandboxes first |
HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 409 | Conflict |
| 500 | Internal Server Error |
Sandbox API
Complete API reference for managing sandbox environments. Sandboxes are isolated development environments that you can create, configure, and manage through the ScaleBox API.
Template API
Complete API reference for managing environment templates. Templates define the base images and configurations used to create sandbox environments in ScaleBox.