Sessions

Create a session

Create a new isolated code execution session. Returns a sessionId, a short-lived gateway token, and a WebSocket URL. If externalId is supplied and an active session already exists with that id, that session is returned instead (idempotent re-attach).

AuthAPI Key
GroupSessions
Rate limitSee Rate Limits
POST/projects/{projectId}

HTTP client

Set up your HTTP client with the auth header before calling the API. Match the authentication type shown above.

const BASE_URL = 'https://api.mudbase.dev/api/sandboxes';
const HEADERS = {
  'x-api-key': 'sk_YOUR_API_KEY',
  'Content-Type': 'application/json',
};
const BASE_URL = 'https://api.mudbase.dev/api/sandboxes';
const HEADERS = {
  'x-api-key': 'sk_YOUR_API_KEY',
  'Content-Type': 'application/json',
};

Example request

Call this endpoint using the client from SDK setup. Use View HTTP for a raw cURL example.

const res = await fetch('https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID', {
  method: 'POST',
  headers: HEADERS,
  body: JSON.stringify({
      "language": "node",
      "languageVersion": "22",
      "languages": [
        "node",
        "python"
      ],
      "timeoutSeconds": 44285,
      "sizeId": "max",
      "cellName": "Maggie O'Keefe",
      "alwaysOn": false,
      "autoSuspendMinutes": 60816,
      "initialExec": {
        "cmd": [
          "circuit compress"
        ],
        "timeoutMs": 14218
      },
      "externalId": "Sp7KhpaEXqI4AJiH"
    }),
});
const data = await res.json();
const res = await fetch('https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID', {
  method: 'POST',
  headers: HEADERS,
  body: JSON.stringify({
      "language": "node",
      "languageVersion": "22",
      "languages": [
        "node",
        "python"
      ],
      "timeoutSeconds": 44285,
      "sizeId": "max",
      "cellName": "Maggie O'Keefe",
      "alwaysOn": false,
      "autoSuspendMinutes": 60816,
      "initialExec": {
        "cmd": [
          "circuit compress"
        ],
        "timeoutMs": 14218
      },
      "externalId": "Sp7KhpaEXqI4AJiH"
    }),
});
const data = await res.json();

Playground

live

Test this endpoint with your own credentials. Your requests will be sent to the live API.

Get your API key from the console

No Request Yet

Send a request to see the full inspector

Authentication

Requires API Key
Note
Include your API key in the X-API-Key: YOUR_KEY header (server-to-server, SDKs). View authentication guide →

Path Parameters

NameTypeRequiredDescription
projectIdstringYes-

Request Body

json
{
  "language": "node",
  "languageVersion": "22",
  "languages": [
    "node",
    "python"
  ],
  "timeoutSeconds": 44285,
  "sizeId": "max",
  "cellName": "Maggie O'Keefe",
  "alwaysOn": false,
  "autoSuspendMinutes": 60816,
  "initialExec": {
    "cmd": [
      "circuit compress"
    ],
    "timeoutMs": 14218
  },
  "externalId": "Sp7KhpaEXqI4AJiH"
}
{
  "language": "node",
  "languageVersion": "22",
  "languages": [
    "node",
    "python"
  ],
  "timeoutSeconds": 44285,
  "sizeId": "max",
  "cellName": "Maggie O'Keefe",
  "alwaysOn": false,
  "autoSuspendMinutes": 60816,
  "initialExec": {
    "cmd": [
      "circuit compress"
    ],
    "timeoutMs": 14218
  },
  "externalId": "Sp7KhpaEXqI4AJiH"
}

Responses

200Existing session returned (externalId match).
json
{
  "success": true,
  "sessionId": "sess_7LedsBSeQ3VvJ4AlVf",
  "wsUrl": "https://sugary-redesign.org",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfZGVtbyJ9.sig_sample",
  "expiresAt": "2026-09-01T18:17:23.983Z",
  "language": "en-US",
  "languageVersion": "en-US",
  "timeoutAt": "2026-09-12T00:13:53.593Z",
  "publicUrl": "https://peaceful-punctuation.net",
  "resumed": false,
  "usageWarning": {
    "percentUsed": 65794
  }
}
{
  "success": true,
  "sessionId": "sess_7LedsBSeQ3VvJ4AlVf",
  "wsUrl": "https://sugary-redesign.org",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfZGVtbyJ9.sig_sample",
  "expiresAt": "2026-09-01T18:17:23.983Z",
  "language": "en-US",
  "languageVersion": "en-US",
  "timeoutAt": "2026-09-12T00:13:53.593Z",
  "publicUrl": "https://peaceful-punctuation.net",
  "resumed": false,
  "usageWarning": {
    "percentUsed": 65794
  }
}
201Session created.
json
{
  "success": true,
  "sessionId": "sess_7LedsBSeQ3VvJ4AlVf",
  "wsUrl": "https://sugary-redesign.org",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfZGVtbyJ9.sig_sample",
  "expiresAt": "2026-09-01T18:17:23.983Z",
  "language": "en-US",
  "languageVersion": "en-US",
  "timeoutAt": "2026-09-12T00:13:53.593Z",
  "publicUrl": "https://peaceful-punctuation.net",
  "resumed": false,
  "usageWarning": {
    "percentUsed": 65794
  }
}
{
  "success": true,
  "sessionId": "sess_7LedsBSeQ3VvJ4AlVf",
  "wsUrl": "https://sugary-redesign.org",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfZGVtbyJ9.sig_sample",
  "expiresAt": "2026-09-01T18:17:23.983Z",
  "language": "en-US",
  "languageVersion": "en-US",
  "timeoutAt": "2026-09-12T00:13:53.593Z",
  "publicUrl": "https://peaceful-punctuation.net",
  "resumed": false,
  "usageWarning": {
    "percentUsed": 65794
  }
}
400Invalid request parameters.
json
{
  "success": false,
  "error": "program back up",
  "code": "interface synthesize"
}
{
  "success": false,
  "error": "program back up",
  "code": "interface synthesize"
}
402Monthly Small-hours quota exhausted.
json
{
  "success": false,
  "error": "program back up",
  "code": "interface synthesize"
}
{
  "success": false,
  "error": "program back up",
  "code": "interface synthesize"
}
429Concurrent session limit reached.
json
{
  "success": false,
  "error": "program back up",
  "code": "interface synthesize"
}
{
  "success": false,
  "error": "program back up",
  "code": "interface synthesize"
}
503Session creation failed (infra error).
json
{
  "success": false,
  "error": "program back up",
  "code": "interface synthesize"
}
{
  "success": false,
  "error": "program back up",
  "code": "interface synthesize"
}

Errors

CodeMeaning
400Invalid request parameters.
402Monthly Small-hours quota exhausted.
429Concurrent session limit reached.
503Session creation failed (infra error).
Run in PostmanDownload OpenAPI

Next

NEXT →API Reference OverviewBase URL, rate limits, pagination, and the full endpoint index.NEXT →AuthenticationAPI keys, Bearer tokens, and user sessions.NEXT →API PlaygroundSearch any endpoint and send a live request.
Edit this page on GitHub