Skip to main content
POST
/
sessions
/
create
curl -X POST https://api.buntime.sh/sessions/create \
  -H "Authorization: Bearer $BUNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 3600,
    "metadata": {
      "userId": "user_123",
      "conversationId": "conv_456"
    }
  }'

{
  "sessionId": "ses_abc123def456ghi789",
  "expiresAt": "2024-01-20T10:30:00Z",
  "previewUrl": "https://ses-abc123def456ghi789.buntime.sh",
  "createdAt": "2024-01-19T10:30:00Z",
  "resourceLimits": {
    "memory": 1024,
    "cpu": 0.25,
    "timeout": 30,
    "disk": 1024
  }
}

​
Overview

Creates a new session that provides an isolated Bun runtime environment. Sessions persist files, processes, and state across multiple API calls during a conversation or workflow.

​
Request

​
Authorization
string
required
Bearer token with your API key
​
Content-Type
string
required
Must be application/json
​
Idempotency-Key
string
Unique key to safely retry requests

​
Request Body

​
ttl
integer
Time-to-live in seconds. Default: 86400 (24 hours). Max: 604800 (7 days)
​
metadata
object
Custom metadata to attach to the session (max 16KB)
​
resourceLimits
object
Override default resource limits (paid plans only)

​
Response

​
sessionId
string
required
Unique identifier for the session (format: ses_ + alphanumeric)
​
expiresAt
string
required
ISO 8601 timestamp when the session will be deleted
​
previewUrl
string
required
URL for accessing web apps running in this session
​
createdAt
string
required
ISO 8601 timestamp when the session was created
​
resourceLimits
object
required
Applied resource limits

​
Example

curl -X POST https://api.buntime.sh/sessions/create \
  -H "Authorization: Bearer $BUNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 3600,
    "metadata": {
      "userId": "user_123",
      "conversationId": "conv_456"
    }
  }'

{
  "sessionId": "ses_abc123def456ghi789",
  "expiresAt": "2024-01-20T10:30:00Z",
  "previewUrl": "https://ses-abc123def456ghi789.buntime.sh",
  "createdAt": "2024-01-19T10:30:00Z",
  "resourceLimits": {
    "memory": 1024,
    "cpu": 0.25,
    "timeout": 30,
    "disk": 1024
  }
}

​
Session Lifecycle

  1. Active: Session is running and accepting requests
  2. Idle: No requests for 5 minutes, container sleeps (billed at reduced rate)
  3. Deep Sleep: No requests for 30 minutes, filesystem saved to storage
  4. Expired: TTL reached, session and all data deleted
Sessions automatically wake from sleep when you make a request. Wake time is typically under 3 seconds.

​
Use Cases

Create a session at the start of a conversation. Files and state persist across messages, allowing iterative development.
Give users their own isolated environment to experiment with code.
Each agent workflow gets its own session with a custom TTL based on expected duration.
Run databases or other stateful services that need to persist between API calls.

​
Best Practices

Set appropriate TTL

Use shorter TTLs (1 hour) for ephemeral tasks, longer (24 hours) for conversations

Use metadata

Track sessions with metadata for easier debugging and analytics

Idempotency keys

Use idempotency keys when retrying failed requests to avoid duplicate sessions

Clean up

Delete sessions when done to free resources and reduce costs

​
Limits

PlanConcurrent SessionsMax TTLResource Overrides
Free1024 hoursNo
Paid1007 daysYes
EnterpriseCustomCustomYes

Get Session Info

Retrieve session details

Delete Session

Delete a session

Execute Code

Run code in the session