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
}
'import requests
url = "https://api.klavis.ai/sandbox/{server_name}"
payload = {
"test_account_email": "<string>",
"tag": "<string>",
"ttl_seconds": 7200
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({test_account_email: '<string>', tag: '<string>', ttl_seconds: 7200})
};
fetch('https://api.klavis.ai/sandbox/{server_name}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({test_account_email: '<string>', tag: '<string>', ttl_seconds: 7200})
};
fetch('https://api.klavis.ai/sandbox/{server_name}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"sandbox_id": "<string>",
"server_name": "jira",
"status": "idle",
"message": "<string>",
"server_urls": {},
"metadata": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Acquire a sandbox
Acquire an idle sandbox instance for a specific MCP server. The sandbox will be marked as ‘occupied’. Optionally choose a benchmark (e.g., ‘MCP_Atlas’, ‘Toolathlon’) to configure the sandbox. IMPORTANT: The benchmark parameter may affect BOTH (1) the initial data environment (e.g., preloaded data for supported servers like Airtable, Notion, Slack, MongoDB) AND (2) the MCP server implementation itself — some servers are routed to a benchmark-specific MCP server URL (e.g., GitHub, Notion, Google Sheets). You may also specify a test_account_email to acquire a specific test account.
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
}
'import requests
url = "https://api.klavis.ai/sandbox/{server_name}"
payload = {
"test_account_email": "<string>",
"tag": "<string>",
"ttl_seconds": 7200
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({test_account_email: '<string>', tag: '<string>', ttl_seconds: 7200})
};
fetch('https://api.klavis.ai/sandbox/{server_name}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({test_account_email: '<string>', tag: '<string>', ttl_seconds: 7200})
};
fetch('https://api.klavis.ai/sandbox/{server_name}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"sandbox_id": "<string>",
"server_name": "jira",
"status": "idle",
"message": "<string>",
"server_urls": {},
"metadata": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Your Klavis AI API key.
Path Parameters
The MCP server name
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, mock_notion, 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
Request model for acquiring a sandbox
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).
MCP_Atlas, Toolathlon, MCP_Mark 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.
Optional sandbox tag used when acquiring specific sandboxes. For mock_notion this is REQUIRED and names the template/category to clone (e.g. 'online_resume')
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.
60 <= x <= 86400Response
Successful Response
Response model for sandbox acquisition
Unique identifier for the acquired sandbox
The MCP server name
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, mock_notion, 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 Current status of the sandbox
idle, occupied, error Status message
MCP server URLs keyed by server name
Show child attributes
Show child attributes
Per-server extras. For now only mock_notion: { task_page_id: str }.
