API Reference

The Vibengine REST API allows you to programmatically create, manage, and interact with cloud sandboxes. You can use the API directly via HTTP requests or through our official SDKs.

Base URL

All API requests should be made to:

https://api.vibengine.ai

Authentication

Authenticate your requests by including your API key in the X-API-Key header.

curl https://api.vibengine.ai/sandboxes \
  -H "X-API-Key: $VE_API_KEY"

Never expose your API key in client-side code or public repositories. Always use environment variables or a secrets manager to store your key.

You can generate and manage API keys from the Vibengine Dashboard.

Rate Limiting

The API enforces rate limits to ensure fair usage across all users.

Plan	Requests per minute	Concurrent sandboxes
Free	60	5
Pro	300	25
Enterprise	Custom	Custom

When you exceed the rate limit, the API returns a 429 Too Many Requests response. The response includes a Retry-After header indicating how many seconds to wait before retrying.

Common Response Format

All successful responses follow a consistent JSON structure:

{
  "data": { ... },
  "status": "ok"
}

List endpoints return paginated results:

{
  "data": [ ... ],
  "has_more": false,
  "total_count": 12
}

Error Codes

When an error occurs, the API returns an appropriate HTTP status code along with a JSON error body:

{
  "error": {
    "code": "invalid_request",
    "message": "A human-readable description of the error."
  }
}

Status Code	Meaning	Description
400	Bad Request	The request body is malformed or missing required fields.
401	Unauthorized	The API key is missing or invalid.
403	Forbidden	The API key does not have permission for this operation.
404	Not Found	The requested resource does not exist.
429	Too Many Requests	You have exceeded the rate limit. Retry after the cooldown.
500	Internal Server Error	An unexpected error occurred on our side. Please retry.

Endpoint Groups

Sandboxes

Sandboxes are isolated cloud environments for running code. Each sandbox has its own filesystem, network, and process space.

Method	Endpoint	Description
`POST`	`/sandboxes`	Create a new sandbox
`GET`	`/sandboxes`	List all running sandboxes
`GET`	`/sandboxes/:id`	Get details of a specific sandbox
`DELETE`	`/sandboxes/:id`	Kill a running sandbox
`POST`	`/sandboxes/:id/timeout`	Extend sandbox timeout

Templates

Templates are pre-configured sandbox images with specific tools, languages, and dependencies pre-installed.

Method	Endpoint	Description
`GET`	`/templates`	List available templates
`POST`	`/templates`	Build a new custom template
`DELETE`	`/templates/:id`	Delete a custom template

Examples

Create a Sandbox

curl -X POST https://api.vibengine.ai/sandboxes \
  -H "X-API-Key: $VE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "base",
    "timeout": 300,
    "metadata": {
      "purpose": "data-analysis"
    }
  }'

{
  "data": {
    "sandbox_id": "sbx_a1b2c3d4e5",
    "template": "base",
    "status": "running",
    "started_at": "2026-02-21T10:30:00Z",
    "timeout": 300,
    "metadata": {
      "purpose": "data-analysis"
    }
  },
  "status": "ok"
}

List Running Sandboxes

curl https://api.vibengine.ai/sandboxes \
  -H "X-API-Key: $VE_API_KEY"

{
  "data": [
    {
      "sandbox_id": "sbx_a1b2c3d4e5",
      "template": "base",
      "status": "running",
      "started_at": "2026-02-21T10:30:00Z",
      "timeout": 300
    },
    {
      "sandbox_id": "sbx_f6g7h8i9j0",
      "template": "python-data",
      "status": "running",
      "started_at": "2026-02-21T10:25:00Z",
      "timeout": 600
    }
  ],
  "has_more": false,
  "total_count": 2
}

Detailed endpoint documentation including request/response schemas is auto-generated from our OpenAPI specification. See the individual endpoint pages in the sidebar for full parameter details and additional examples.

API Reference

On this page