KLklavis-ai
sandbox

Acquire a sandbox

Changed on

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.

post/sandbox/{server_name}

Request

  • Base URL
    https://api.klavis.ai
  • Auth
    HTTP bearer

Path parameters

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' required

Supported MCP servers for sandboxing

The MCP server name

Request body

benchmark'MCP_Atlas' | 'Toolathlon' | 'MCP_Mark'

Supported benchmarks for sandbox initial environment

test_account_emailstring nullable

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.

tagstring nullable

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_secondsinteger nullable

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.

Response

Successful Response

sandbox_idstring required

Unique identifier for the acquired sandbox

server_urlsobject nullable

MCP server URLs keyed by server name

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' required

Supported MCP servers for sandboxing

status'idle' | 'occupied' | 'error' required

Status of a sandbox instance - matches database enum

messagestring required

Status message

metadataobject nullable

Per-server extras. For now only mock_notion: { task_page_id: str }.

Changes

  • 1f05ced7280fRevision changes
    • warning

      removed the request property

  • 05c3b59aa353Revision changes
    • warning

      added the new mock_notion enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new enum value mock_notion to the path request parameter server_name

    • info

      added the optional property to the response with the status