Skip to main content
POST
/
sandbox
/
{server_name}
Acquire a sandbox
curl --request POST \
  --url https://api.klavis.ai/sandbox/{server_name} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "test_account_email": "<string>",
  "tag": "<string>",
  "ttl_seconds": 7200
}
'
{
  "sandbox_id": "<string>",
  "message": "<string>",
  "server_urls": {}
}

Documentation Index

Fetch the complete documentation index at: https://www.klavis.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Your Klavis AI API key.

Path Parameters

​
server_name
enum<string>
required

The MCP server name

Available options:
jira,
github,
salesforce,
hubspot,
notion,
airtable,
linear,
asana,
google_sheets,
google_drive,
google_docs,
gmail,
google_calendar,
google_forms,
clickup,
close,
monday,
motion,
onedrive,
microsoft_teams,
outlook_mail,
cal.com,
quickbooks,
moneybird,
dropbox,
shopify,
woocommerce,
outlook_calendar,
resend,
wordpress,
mem0,
supabase,
slack,
confluence,
discord,
snowflake,
postgres,
mongodb,
youtube,
googleworkspaceatlas,
huggingface,
arxiv_latex,
calculator,
clinicaltrialsgov,
fetch,
met_museum,
open_library,
osm,
pubmed,
us_weather,
duckduckgo,
whois,
wikipedia,
scholarly,
howtocook,
yahoo_finance,
12306,
youtube_transcript,
weather,
twelvedata,
national_parks,
lara_translate,
e2b,
context7,
alchemy,
weights_and_biases,
oxylabs,
google_maps,
brave_search,
exa,
serper

Body

application/json

Request model for acquiring a sandbox

​
benchmark
enum<string> | null

Optional benchmark to configure the sandbox. NOTE: This parameter may affect BOTH (1) the initial data environment (preloaded data for supported servers) AND (2) the MCP server implementation (some servers are routed to a benchmark-specific MCP server URL with potentially different tools or behaviors).

Available options:
MCP_Atlas,
Toolathlon,
MCP_Mark
​
test_account_email
string | null

Optional email of a specific test account to acquire. If provided, the system will attempt to acquire the sandbox associated with this test account email instead of a random idle sandbox.

​
tag
string | null

Optional sandbox tag used when acquiring specific sandboxes.

​
ttl_seconds
integer | null
default:7200

TTL in seconds. The sandbox will be automatically released after this duration. Default: 7200 (2 hours). Min: 60 (1 minute). Max: 86400 (24 hours). Set to null to disable auto-release.

Required range: 60 <= x <= 86400

Response

Successful Response

Response model for sandbox acquisition

​
sandbox_id
string
required

Unique identifier for the acquired sandbox

​
server_name
enum<string>
required

The MCP server name

Available options:
jira,
github,
salesforce,
hubspot,
notion,
airtable,
linear,
asana,
google_sheets,
google_drive,
google_docs,
gmail,
google_calendar,
google_forms,
clickup,
close,
monday,
motion,
onedrive,
microsoft_teams,
outlook_mail,
cal.com,
quickbooks,
moneybird,
dropbox,
shopify,
woocommerce,
outlook_calendar,
resend,
wordpress,
mem0,
supabase,
slack,
confluence,
discord,
snowflake,
postgres,
mongodb,
youtube,
googleworkspaceatlas,
huggingface,
arxiv_latex,
calculator,
clinicaltrialsgov,
fetch,
met_museum,
open_library,
osm,
pubmed,
us_weather,
duckduckgo,
whois,
wikipedia,
scholarly,
howtocook,
yahoo_finance,
12306,
youtube_transcript,
weather,
twelvedata,
national_parks,
lara_translate,
e2b,
context7,
alchemy,
weights_and_biases,
oxylabs,
google_maps,
brave_search,
exa,
serper
​
status
enum<string>
required

Current status of the sandbox

Available options:
idle,
occupied,
error
​
message
string
required

Status message

​
server_urls
Server Urls · object

MCP server URLs keyed by server name