> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buntime.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# API Reference
> Complete REST API documentation for buntime.sh
## Base URL
All API requests are made to:
```
https://api.buntime.sh
```
## Authentication
All endpoints require authentication using an API key in the Authorization header:
```bash theme={null}
Authorization: Bearer your_api_key_here
```
See [Authentication](/authentication) for details on obtaining and managing API keys.
## Request Format
All POST/PUT requests must include:
* `Content-Type: application/json` header
* JSON-encoded request body
```bash theme={null}
curl -X POST https://api.buntime.sh/execute \
-H "Authorization: Bearer $BUNTIME_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sessionId": "ses_123", "code": "console.log(\"Hello!\")"}'
```
## Response Format
All responses are JSON-encoded with appropriate HTTP status codes.
### Success Response
```json theme={null}
{
"data": {
// Response data here
}
}
```
### Error Response
```json theme={null}
{
"error": {
"code": "invalid_request",
"message": "Session not found",
"details": {
"sessionId": "ses_invalid"
}
}
}
```
## HTTP Status Codes
| Status Code | Description |
| ----------- | ------------------------------------------------------- |
| `200` | Success - Request completed successfully |
| `201` | Created - Resource created successfully |
| `400` | Bad Request - Invalid request parameters |
| `401` | Unauthorized - Invalid or missing API key |
| `403` | Forbidden - API key lacks required permissions |
| `404` | Not Found - Resource doesn't exist |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Internal Server Error - Something went wrong on our end |
| `503` | Service Unavailable - Temporary issue, retry later |
## Rate Limits
API keys are rate-limited based on your plan:
* **Free:** 100 requests/minute
* **Paid:** 1,000 requests/minute
* **Enterprise:** Custom limits
Rate limit information is included in response headers:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
```
When you exceed the rate limit, you'll receive a `429` response with a `Retry-After` header indicating when you can retry.
## Pagination
List endpoints support pagination using query parameters:
```
GET /files/list?sessionId=ses_123&limit=50&offset=0
```
| Parameter | Type | Description |
| --------- | ------- | ------------------------------------------------ |
| `limit` | integer | Number of items per page (default: 50, max: 100) |
| `offset` | integer | Number of items to skip (default: 0) |
Paginated responses include metadata:
```json theme={null}
{
"data": [...],
"pagination": {
"total": 150,
"limit": 50,
"offset": 0,
"hasMore": true
}
}
```
## Idempotency
POST requests that create resources support idempotency keys to safely retry requests:
```bash theme={null}
curl -X POST https://api.buntime.sh/sessions/create \
-H "Authorization: Bearer $BUNTIME_API_KEY" \
-H "Idempotency-Key: unique_request_id_123" \
-H "Content-Type: application/json"
```
If you retry a request with the same idempotency key within 24 hours, you'll receive the same response as the original request.
## Timeouts
All API requests have a maximum timeout:
* **Session operations:** 10 seconds
* **File operations:** 30 seconds
* **Code execution:** 30 seconds (default), up to 5 minutes (configurable)
If an operation exceeds the timeout, you'll receive a `408 Request Timeout` response.
## Webhooks
buntime.sh can send webhooks for long-running operations:
* Execution completed
* Session expired
* Resource limit exceeded
Configure webhooks in your [dashboard](https://buntime.sh/dashboard/webhooks).
## API Endpoints
### Sessions
Manage isolated execution environments:
Create a new session
Retrieve session details
Delete a session
### Execution
Run code in sessions:
Run code or commands
Stop running processes
### Files
Manage files in sessions:
Create or update files
Read file contents
List all files
### Preview
Access web applications:
Access running web apps
## SDKs
We provide official SDKs to make integration easier:
Type-safe Node.js and Bun client
## Examples
### Quick Start
```bash theme={null}
# 1. Create a session
SESSION=$(curl -s -X POST https://api.buntime.sh/sessions/create \
-H "Authorization: Bearer $BUNTIME_API_KEY" \
| jq -r '.sessionId')
# 2. Execute code
curl -X POST https://api.buntime.sh/execute \
-H "Authorization: Bearer $BUNTIME_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"sessionId\": \"$SESSION\",
\"code\": \"console.log('Hello, World!')\"
}"
```
### Multi-file Project
```bash theme={null}
# Write files
curl -X POST https://api.buntime.sh/files/write \
-H "Authorization: Bearer $BUNTIME_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"sessionId\": \"$SESSION\",
\"path\": \"utils.ts\",
\"content\": \"export const add = (a: number, b: number) => a + b;\"
}"
# Execute
curl -X POST https://api.buntime.sh/execute \
-H "Authorization: Bearer $BUNTIME_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"sessionId\": \"$SESSION\",
\"code\": \"import { add } from './utils'; console.log(add(2, 3));\"
}"
```
## Need Help?
Get help from the community
Browse code examples
Report bugs or issues
Contact our support team