diff --git a/.gitignore b/.gitignore index 090a1f02..0f7e4889 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ .idea .DS_Store +node_modules/ +package-lock.json diff --git a/docs.json b/docs.json index d89e016a..c7c7f3fa 100644 --- a/docs.json +++ b/docs.json @@ -212,6 +212,22 @@ "anchor": "SDK Reference", "icon": "brackets-curly", "href": "https://e2b.dev/docs/sdk-reference" + }, + { + "anchor": "API Reference", + "icon": "code", + "openapi": { + "source": "openapi-public.yml", + "directory": "docs/api-reference" + } + }, + { + "anchor": "API Reference (Edited)", + "icon": "code", + "openapi": { + "source": "openapi-public-edited.yml", + "directory": "docs/api-reference-edited" + } } ], "global": {} diff --git a/openapi-public-edited.yml b/openapi-public-edited.yml new file mode 100644 index 00000000..a6a71e62 --- /dev/null +++ b/openapi-public-edited.yml @@ -0,0 +1,3011 @@ +openapi: 3.0.0 +info: + version: 0.1.0 + title: E2B API + description: | + The E2B API allows you to programmatically create, manage, and interact with cloud sandboxes - secure, isolated environments for running code. + + ## Overview + + The API is split into two parts: + + ### Control Plane API (`api.e2b.app`) + Use this API to manage the lifecycle of sandboxes and templates: + - **Sandboxes**: Create, list, pause, resume, and terminate sandboxes + - **Templates**: Build and manage custom sandbox templates + - **Metrics**: Monitor usage and resource consumption + + ### Data Plane API (`{port}-{sandboxId}.e2b.app`) + Use this API to interact with a running sandbox: + - **Files**: Upload and download files + - **Filesystem**: Create directories, list contents, move and delete files + - **Processes**: Start, monitor, and control processes + + ## Authentication + + ### Control Plane (X-API-Key) + All Control Plane endpoints require your API key in the `X-API-Key` header. + Get your API key from the [E2B Dashboard](https://e2b.dev/dashboard?tab=keys). + + ```bash + curl -H "X-API-Key: e2b_YOUR_API_KEY" https://api.e2b.app/sandboxes + ``` + + ### Data Plane (X-Access-Token) + Data Plane endpoints require the `X-Access-Token` header with the access token + returned when you create a sandbox. + + ```bash + # 1. Create a sandbox (returns sandboxId and envdAccessToken) + curl -X POST -H "X-API-Key: e2b_YOUR_API_KEY" \ + -d '{"templateID": "base"}' \ + https://api.e2b.app/sandboxes + + # 2. Use the token to interact with the sandbox + curl -H "X-Access-Token: YOUR_ACCESS_TOKEN" \ + https://49982-YOUR_SANDBOX_ID.e2b.app/files?path=/home/user/file.txt + ``` + + ## Quick Start + + 1. **Create a sandbox** from a template using `POST /sandboxes` + 2. **Get the access token** from the response (`envdAccessToken`) + 3. **Interact with the sandbox** using the Data Plane API + 4. **Clean up** by deleting the sandbox with `DELETE /sandboxes/{sandboxID}` + + ## Rate Limits + + API requests are rate limited. Contact support if you need higher limits. + + ## SDKs + + We provide official SDKs for Python, JavaScript/TypeScript, and Go. + See [SDK Reference](https://e2b.dev/docs/sdk-reference) for details. +servers: + - url: https://api.e2b.app + description: E2B Control Plane API +tags: + - name: Sandboxes + description: | + Create and manage sandbox instances. Sandboxes are isolated cloud environments + where you can safely run code, install packages, and execute processes. + + **Common workflows:** + - Create a sandbox → Run code → Delete sandbox + - Create a sandbox → Pause → Resume later → Delete + - List running sandboxes → Get metrics → Clean up idle ones + - name: Templates + description: | + Build and manage custom templates. Templates are pre-configured sandbox images + with your preferred tools, packages, and configurations pre-installed. + + **Use templates to:** + - Speed up sandbox creation by pre-installing dependencies + - Ensure consistent environments across sandboxes + - Share configurations across your team + - name: Metrics + description: | + Monitor resource usage and track sandbox activity. Use metrics to understand + your usage patterns and optimize costs. + - name: Teams + description: | + List and manage your teams. Teams are organizational units that own + sandboxes, templates, and API keys. + - name: Sandbox Filesystem + description: | + Perform filesystem operations inside a running sandbox. Create directories, + list contents, move files, delete files, and watch for changes. + + **Base URL:** `https://{port}-{sandboxId}.e2b.app` + + These endpoints use Connect RPC protocol over HTTP. + - name: Sandbox Process + description: | + Start and manage processes inside a running sandbox. Execute commands, + stream output, send input, and control running processes. + + **Base URL:** `https://{port}-{sandboxId}.e2b.app` + + These endpoints use Connect RPC protocol over HTTP. +components: + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + AccessTokenAuth: + type: apiKey + in: header + name: X-Access-Token + parameters: + templateID: + name: templateID + in: path + required: true + description: Unique identifier of the template (e.g., `base`, `python`, or a custom template ID) + schema: + type: string + example: base + buildID: + name: buildID + in: path + required: true + description: Unique identifier of a template build (UUID format) + schema: + type: string + format: uuid + example: 550e8400-e29b-41d4-a716-446655440000 + sandboxID: + name: sandboxID + in: path + required: true + description: Unique identifier of the sandbox + schema: + type: string + example: sandbox-abc123 + teamID: + name: teamID + in: path + required: true + description: Unique identifier of your team + schema: + type: string + paginationLimit: + name: limit + in: query + description: Maximum number of items to return per page (1-100) + required: false + schema: + type: integer + format: int32 + minimum: 1 + default: 100 + maximum: 100 + example: 50 + paginationNextToken: + name: nextToken + in: query + description: Cursor for pagination. Use the value from the previous response to get the next page. + required: false + schema: + type: string + SandboxFilePath: + name: path + in: query + required: false + description: | + Path to the file inside the sandbox. Can be absolute (e.g., `/home/user/file.txt`) + or relative to the user's home directory (e.g., `file.txt`). + Must be URL encoded. + schema: + type: string + example: /home/user/data.json + SandboxSignature: + name: signature + in: query + required: false + description: Signature used for file access permission verification. + schema: + type: string + SandboxSignatureExpiration: + name: signature_expiration + in: query + required: false + description: Signature expiration used for defining the expiration time of the signature. + schema: + type: integer + SandboxUser: + name: username + in: query + required: false + description: Username for file ownership and resolving relative paths. Defaults to `user`. + schema: + type: string + default: user + example: user + responses: + "400": + description: Bad Request - The request was malformed or missing required parameters + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: 400 + message: "Invalid request: templateID is required" + "401": + description: Unauthorized - Invalid or missing API key + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: 401 + message: Invalid API key + "403": + description: Forbidden - You don't have permission to access this resource + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: 403 + message: Access denied + "404": + description: Not Found - The requested resource doesn't exist + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: 404 + message: Sandbox not found + "409": + description: Conflict - The request conflicts with the current state + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: 409 + message: Sandbox is already paused + "500": + description: Internal Server Error - Something went wrong on our end + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + code: 500 + message: Internal server error + schemas: + Error: + type: object + description: Error response returned when a request fails + required: + - code + - message + properties: + code: + type: integer + description: HTTP status code + example: 400 + message: + type: string + description: Human-readable error message + example: Invalid request parameters + NewSandbox: + type: object + description: Request body for creating a new sandbox + required: + - templateID + properties: + templateID: + type: string + description: | + ID of the template to use. Can be a built-in template (`base`, `python`, `node`) + or a custom template ID. + example: base + timeout: + type: integer + format: int32 + minimum: 0 + default: 15 + description: | + How long the sandbox should stay alive in seconds, measured from creation time. + The sandbox will automatically terminate after this duration unless extended. + Maximum: 24 hours (86400 seconds). + example: 300 + autoPause: + type: boolean + default: false + description: | + If true, the sandbox will automatically pause instead of terminating when + the timeout expires. Paused sandboxes can be resumed later but don't consume + compute resources while paused. + example: true + metadata: + type: object + additionalProperties: + type: string + description: | + Custom key-value metadata to attach to the sandbox. Useful for filtering + and organizing sandboxes. Keys and values must be strings. + example: + user: user-123 + project: code-review + environment: staging + envVars: + type: object + additionalProperties: + type: string + description: | + Environment variables to set in the sandbox. These will be available + to all processes running in the sandbox. + example: + NODE_ENV: production + API_URL: https://api.example.com + secure: + type: boolean + description: Secure all system communication with sandbox + allow_internet_access: + type: boolean + description: Allow sandbox to access the internet. When set to false, it behaves the same as specifying denyOut to 0.0.0.0/0 in the network config. + network: + type: object + description: Network configuration for the sandbox + properties: + allowPublicTraffic: + type: boolean + default: true + description: Specify if the sandbox URLs should be accessible only with authentication. + allowOut: + type: array + description: List of allowed CIDR blocks or IP addresses for egress traffic. Allowed addresses always take precedence over blocked addresses. + items: + type: string + denyOut: + type: array + description: List of denied CIDR blocks or IP addresses for egress traffic + items: + type: string + maskRequestHost: + type: string + description: Specify host mask which will be used for all sandbox requests + mcp: + type: object + description: MCP configuration for the sandbox + additionalProperties: {} + nullable: true + Sandbox: + type: object + description: A sandbox instance that was just created + required: + - templateID + - sandboxID + - clientID + - envdVersion + properties: + sandboxID: + type: string + description: Unique identifier of the sandbox. Use this to interact with the sandbox. + example: sandbox-abc123xyz + templateID: + type: string + description: ID of the template this sandbox was created from + example: base + envdAccessToken: + type: string + description: | + Access token for Data Plane API calls. Use this as the `X-Access-Token` + header when calling sandbox endpoints (files, filesystem, process). + example: eyJhbGciOiJIUzI1NiIs... + clientID: + type: string + deprecated: true + description: Legacy field, use sandboxID instead + envdVersion: + type: string + description: Version of the sandbox runtime + example: 0.1.0 + trafficAccessToken: + type: string + nullable: true + description: Token required for accessing sandbox via proxy. + domain: + type: string + nullable: true + description: Base domain for accessing the sandbox + example: e2b.app + SandboxDetail: + type: object + description: Detailed information about a sandbox + required: + - templateID + - sandboxID + - clientID + - startedAt + - cpuCount + - memoryMB + - diskSizeMB + - endAt + - state + - envdVersion + properties: + sandboxID: + type: string + description: Unique identifier of the sandbox + example: sandbox-abc123xyz + templateID: + type: string + description: ID of the template this sandbox was created from + example: base + alias: + type: string + description: Human-readable alias for the template + example: my-python-template + startedAt: + type: string + format: date-time + description: When the sandbox was created + example: "2024-01-15T10:30:00Z" + endAt: + type: string + format: date-time + description: When the sandbox will automatically terminate (can be extended) + example: "2024-01-15T10:45:00Z" + state: + type: string + enum: + - running + - paused + description: Current state of the sandbox + example: running + cpuCount: + type: integer + description: Number of CPU cores allocated + example: 2 + memoryMB: + type: integer + description: Memory allocated in megabytes + example: 512 + diskSizeMB: + type: integer + description: Disk space allocated in megabytes + example: 1024 + metadata: + type: object + additionalProperties: + type: string + description: Custom metadata attached to the sandbox + example: + user: user-123 + envdVersion: + type: string + description: Version of the sandbox runtime + envdAccessToken: + type: string + description: Access token for Data Plane API calls + clientID: + type: string + deprecated: true + domain: + type: string + nullable: true + ListedSandbox: + type: object + description: Summary information about a sandbox in a list + required: + - templateID + - sandboxID + - clientID + - startedAt + - cpuCount + - memoryMB + - diskSizeMB + - endAt + - state + - envdVersion + properties: + sandboxID: + type: string + description: Unique identifier of the sandbox + templateID: + type: string + description: ID of the template + alias: + type: string + description: Template alias + startedAt: + type: string + format: date-time + description: When the sandbox was created + endAt: + type: string + format: date-time + description: When the sandbox will terminate + state: + type: string + enum: + - running + - paused + description: Current state + cpuCount: + type: integer + memoryMB: + type: integer + diskSizeMB: + type: integer + metadata: + type: object + additionalProperties: + type: string + envdVersion: + type: string + clientID: + type: string + deprecated: true + SandboxMetric: + type: object + description: Resource usage metrics for a sandbox at a point in time + required: + - timestamp + - timestampUnix + - cpuCount + - cpuUsedPct + - memUsed + - memTotal + - diskUsed + - diskTotal + properties: + timestamp: + type: string + format: date-time + deprecated: true + description: Timestamp of the metric entry + timestampUnix: + type: integer + format: int64 + description: Unix timestamp (seconds since epoch) + example: 1705315800 + cpuCount: + type: integer + description: Number of CPU cores + example: 2 + cpuUsedPct: + type: number + format: float + description: CPU usage as a percentage (0-100 per core, so max is cpuCount * 100) + example: 45.5 + memUsed: + type: integer + format: int64 + description: Memory used in bytes + example: 268435456 + memTotal: + type: integer + format: int64 + description: Total memory available in bytes + example: 536870912 + diskUsed: + type: integer + format: int64 + description: Disk space used in bytes + example: 104857600 + diskTotal: + type: integer + format: int64 + description: Total disk space in bytes + example: 1073741824 + Template: + type: object + description: A sandbox template with pre-installed tools and configurations + required: + - templateID + - buildID + - cpuCount + - memoryMB + - diskSizeMB + - public + - createdAt + - updatedAt + - createdBy + - lastSpawnedAt + - spawnCount + - buildCount + - envdVersion + - aliases + - names + - buildStatus + properties: + templateID: + type: string + description: Unique identifier of the template + example: tpl-abc123 + buildID: + type: string + description: ID of the current (latest successful) build + example: 550e8400-e29b-41d4-a716-446655440000 + names: + type: array + items: + type: string + description: Human-readable names/aliases for the template + example: + - my-python-env + - team/python-ml + aliases: + type: array + deprecated: true + description: Aliases of the template + items: + type: string + public: + type: boolean + description: Whether the template is publicly accessible + example: false + cpuCount: + type: integer + format: int32 + minimum: 1 + description: Default CPU cores for sandboxes + example: 2 + memoryMB: + type: integer + format: int32 + minimum: 128 + description: Default memory in MB + example: 512 + diskSizeMB: + type: integer + format: int32 + minimum: 0 + description: Default disk size in MB + example: 1024 + createdAt: + type: string + format: date-time + description: When the template was created + updatedAt: + type: string + format: date-time + description: When the template was last modified + createdBy: + type: object + nullable: true + description: User who created the template + properties: + id: + type: string + format: uuid + email: + type: string + lastSpawnedAt: + type: string + format: date-time + nullable: true + description: When a sandbox was last created from this template + spawnCount: + type: integer + format: int64 + description: Total number of sandboxes created from this template + example: 1542 + buildCount: + type: integer + format: int32 + description: Number of builds for this template + example: 5 + envdVersion: + type: string + description: Runtime version + buildStatus: + type: string + description: Status of the template build + enum: + - building + - waiting + - ready + - error + TemplateBuildRequest: + type: object + description: Request body for creating or rebuilding a template (legacy) + required: + - dockerfile + properties: + alias: + type: string + description: Alias for the template + cpuCount: + type: integer + format: int32 + minimum: 1 + description: CPU cores for the template + dockerfile: + type: string + description: Dockerfile content for the template + memoryMB: + type: integer + format: int32 + minimum: 128 + description: Memory in MB for the template + readyCmd: + type: string + description: Ready check command to execute after the build + startCmd: + type: string + description: Start command to execute after the build + teamID: + type: string + description: Team identifier + TemplateLegacy: + type: object + description: Legacy template response + required: + - templateID + - buildID + - cpuCount + - memoryMB + - diskSizeMB + - public + - createdAt + - updatedAt + - createdBy + - lastSpawnedAt + - spawnCount + - buildCount + - envdVersion + - aliases + properties: + templateID: + type: string + description: Unique identifier of the template + buildID: + type: string + description: ID of the last successful build + aliases: + type: array + items: + type: string + description: Aliases of the template + public: + type: boolean + description: Whether the template is publicly accessible + cpuCount: + type: integer + format: int32 + description: CPU cores + memoryMB: + type: integer + format: int32 + description: Memory in MB + diskSizeMB: + type: integer + format: int32 + description: Disk size in MB + createdAt: + type: string + format: date-time + description: When the template was created + updatedAt: + type: string + format: date-time + description: When the template was last modified + createdBy: + type: object + nullable: true + description: User who created the template + properties: + id: + type: string + format: uuid + email: + type: string + lastSpawnedAt: + type: string + format: date-time + nullable: true + description: When a sandbox was last created from this template + spawnCount: + type: integer + format: int64 + description: Total number of sandboxes created + buildCount: + type: integer + format: int32 + description: Number of builds + envdVersion: + type: string + description: Runtime version + Team: + type: object + description: A team in the E2B platform + required: + - teamID + - name + - apiKey + - isDefault + properties: + teamID: + type: string + description: Unique identifier of the team + name: + type: string + description: Name of the team + apiKey: + type: string + description: API key for the team + isDefault: + type: boolean + description: Whether this is the default team +paths: + /init: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Initialize sandbox connection + description: | + Initializes the sandbox connection and syncs environment variables, + time, and other metadata with the host. + operationId: initSandbox + tags: + - Sandboxes + security: + - AccessTokenAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + hyperloopIP: + type: string + description: IP address of the hyperloop server to connect to + envVars: + type: object + additionalProperties: + type: string + description: Environment variables to set + accessToken: + type: string + description: Access token for secure access to envd service + timestamp: + type: string + format: date-time + description: Current timestamp for time sync + defaultUser: + type: string + description: Default user for operations + example: user + defaultWorkdir: + type: string + description: Default working directory + example: /home/user + responses: + "204": + description: Sandbox initialized successfully + /sandboxes: + get: + summary: List running sandboxes + description: | + Returns a list of all currently running sandboxes for your team. + Use the `metadata` parameter to filter sandboxes by custom metadata. + + **Note:** This endpoint only returns running sandboxes. Paused sandboxes + are not included. Use `GET /v2/sandboxes` with state filter for more options. + operationId: listSandboxes + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - name: metadata + in: query + description: | + Filter sandboxes by metadata. Format: `key=value&key2=value2` + Each key and value must be URL encoded. + required: false + schema: + type: string + example: user=user-123&project=demo + responses: + "200": + description: List of running sandboxes + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ListedSandbox" + example: + - sandboxID: sandbox-abc123 + templateID: base + state: running + startedAt: "2024-01-15T10:30:00Z" + endAt: "2024-01-15T10:45:00Z" + cpuCount: 2 + memoryMB: 512 + diskSizeMB: 1024 + metadata: + user: user-123 + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + post: + summary: Create a sandbox + description: | + Creates a new sandbox from the specified template. The sandbox starts + immediately and is ready to use within a few seconds. + + **Returns:** + - `sandboxID`: Use this to identify the sandbox in subsequent API calls + - `envdAccessToken`: Use this as `X-Access-Token` for Data Plane API calls + operationId: createSandbox + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NewSandbox" + example: + templateID: base + timeout: 300 + metadata: + user: user-123 + project: code-review + envVars: + NODE_ENV: development + responses: + "201": + description: Sandbox created successfully + content: + application/json: + schema: + $ref: "#/components/schemas/Sandbox" + example: + sandboxID: sandbox-abc123xyz + templateID: base + envdAccessToken: eyJhbGciOiJIUzI1NiIs... + envdVersion: 0.1.0 + domain: e2b.app + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /sandboxes/{sandboxID}: + get: + summary: Get sandbox details + description: | + Returns detailed information about a specific sandbox, including its + current state, resource allocation, and metadata. + operationId: getSandbox + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + responses: + "200": + description: Sandbox details + content: + application/json: + schema: + $ref: "#/components/schemas/SandboxDetail" + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + delete: + summary: Terminate a sandbox + description: | + Immediately terminates and deletes a sandbox. All data in the sandbox + is permanently lost. + + **Warning:** This action cannot be undone. If you want to preserve the + sandbox state for later, use `POST /sandboxes/{sandboxID}/pause` instead. + operationId: deleteSandbox + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + responses: + "204": + description: Sandbox terminated successfully + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /sandboxes/{sandboxID}/pause: + post: + summary: Pause a sandbox + description: | + Pauses a running sandbox. The sandbox state is preserved and can be + resumed later with `POST /sandboxes/{sandboxID}/connect`. + + **Benefits of pausing:** + - No compute charges while paused + - State is preserved (files, installed packages, etc.) + - Resume in seconds instead of creating a new sandbox + + **Limitations:** + - Running processes are stopped + - Network connections are closed + - Paused sandboxes have a maximum retention period + operationId: pauseSandbox + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + responses: + "204": + description: Sandbox paused successfully + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "409": + description: Sandbox is already paused + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "500": + $ref: "#/components/responses/500" + /sandboxes/{sandboxID}/connect: + post: + summary: Connect to or resume a sandbox + description: | + Returns sandbox connection details. If the sandbox is paused, it will + be automatically resumed. + + Use this endpoint to: + - Resume a paused sandbox + - Get connection details for a running sandbox + - Extend the sandbox timeout + + **Note:** The timeout is extended from the current time, not added to + the existing timeout. + operationId: connectSandbox + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - timeout + properties: + timeout: + type: integer + format: int32 + minimum: 0 + description: New timeout in seconds from now + example: 300 + example: + timeout: 300 + responses: + "200": + description: Sandbox was already running + content: + application/json: + schema: + $ref: "#/components/schemas/Sandbox" + "201": + description: Sandbox was resumed + content: + application/json: + schema: + $ref: "#/components/schemas/Sandbox" + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /sandboxes/{sandboxID}/timeout: + post: + summary: Set sandbox timeout + description: | + Sets a new timeout for the sandbox. The sandbox will automatically + terminate after the specified number of seconds from now. + + **Note:** This replaces any existing timeout. Each call resets the + countdown from the current time. + operationId: setSandboxTimeout + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - timeout + properties: + timeout: + type: integer + format: int32 + minimum: 0 + description: Timeout in seconds from now + example: 600 + example: + timeout: 600 + responses: + "204": + description: Timeout updated successfully + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /sandboxes/{sandboxID}/refreshes: + post: + summary: Extend sandbox lifetime + description: | + Extends the sandbox lifetime by the specified duration. Unlike + `/timeout`, this adds time to the existing expiration. + operationId: refreshSandbox + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + requestBody: + content: + application/json: + schema: + type: object + properties: + duration: + type: integer + minimum: 0 + maximum: 3600 + description: Duration to add in seconds (max 1 hour) + example: 300 + example: + duration: 300 + responses: + "204": + description: Sandbox lifetime extended + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + /v2/sandboxes: + get: + summary: List all sandboxes (v2) + description: | + Returns all sandboxes, including paused ones. Supports filtering by + state and metadata, and pagination. + operationId: listSandboxesV2 + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - name: metadata + in: query + description: Filter by metadata (e.g., `user=abc&app=prod`) + required: false + schema: + type: string + - name: state + in: query + description: Filter by one or more states + required: false + schema: + type: array + items: + type: string + enum: + - running + - paused + style: form + explode: false + - $ref: "#/components/parameters/paginationNextToken" + - $ref: "#/components/parameters/paginationLimit" + responses: + "200": + description: List of sandboxes + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ListedSandbox" + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /sandboxes/metrics: + get: + summary: Get metrics for multiple sandboxes + description: | + Returns the latest metrics for a batch of sandboxes. Useful for + monitoring dashboards. + operationId: getSandboxesMetrics + tags: + - Metrics + security: + - ApiKeyAuth: [] + parameters: + - name: sandbox_ids + in: query + required: true + description: Comma-separated list of sandbox IDs (max 100) + explode: false + schema: + type: array + items: + type: string + maxItems: 100 + uniqueItems: true + responses: + "200": + description: Metrics per sandbox + content: + application/json: + schema: + type: object + properties: + sandboxes: + type: object + additionalProperties: + $ref: "#/components/schemas/SandboxMetric" + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /sandboxes/{sandboxID}/resume: + post: + summary: Resume a paused sandbox + deprecated: true + description: | + Resumes a previously paused sandbox. + + **Deprecated:** Use `POST /sandboxes/{sandboxID}/connect` instead, + which handles both running and paused sandboxes. + operationId: resumeSandbox + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + timeout: + type: integer + format: int32 + minimum: 0 + default: 15 + description: Time to live in seconds + autoPause: + type: boolean + deprecated: true + description: Automatically pauses the sandbox after the timeout + responses: + "201": + description: Sandbox resumed + content: + application/json: + schema: + $ref: "#/components/schemas/Sandbox" + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "409": + $ref: "#/components/responses/409" + "500": + $ref: "#/components/responses/500" + /sandboxes/{sandboxID}/logs: + get: + summary: Get sandbox logs + description: | + Returns system logs from the sandbox. These include sandbox startup logs + and system-level events. + operationId: getSandboxLogs + tags: + - Sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + - name: start + in: query + description: Start timestamp in milliseconds (Unix epoch) + schema: + type: integer + format: int64 + minimum: 0 + - name: limit + in: query + description: Maximum number of log entries to return + schema: + type: integer + format: int32 + default: 1000 + minimum: 0 + responses: + "200": + description: Sandbox logs + content: + application/json: + schema: + type: object + properties: + logs: + type: array + items: + type: object + properties: + timestamp: + type: string + format: date-time + line: + type: string + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /sandboxes/{sandboxID}/metrics: + get: + summary: Get sandbox metrics + description: | + Returns resource usage metrics (CPU, memory, disk) for a specific sandbox + over a time range. + operationId: getSandboxMetrics + tags: + - Metrics + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/sandboxID" + - name: start + in: query + description: Start timestamp in seconds (Unix epoch) + schema: + type: integer + format: int64 + minimum: 0 + - name: end + in: query + description: End timestamp in seconds (Unix epoch) + schema: + type: integer + format: int64 + minimum: 0 + responses: + "200": + description: Sandbox metrics + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/SandboxMetric" + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /teams/{teamID}/metrics: + get: + summary: Get team metrics + description: | + Returns usage metrics for your team over a time range, including + concurrent sandbox count and sandbox start rate. + operationId: getTeamMetrics + tags: + - Metrics + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/teamID" + - name: start + in: query + description: Start timestamp in seconds (Unix epoch) + schema: + type: integer + format: int64 + minimum: 0 + - name: end + in: query + description: End timestamp in seconds (Unix epoch) + schema: + type: integer + format: int64 + minimum: 0 + responses: + "200": + description: Team metrics + content: + application/json: + schema: + type: array + items: + type: object + properties: + timestampUnix: + type: integer + format: int64 + description: Unix timestamp + concurrentSandboxes: + type: integer + description: Number of sandboxes running at this time + sandboxStartRate: + type: number + format: float + description: Sandboxes started per second + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "403": + $ref: "#/components/responses/403" + "500": + $ref: "#/components/responses/500" + /teams/{teamID}/metrics/max: + get: + summary: Get max team metrics + description: | + Returns the maximum value of a specific metric for your team + over a time range. + operationId: getTeamMetricsMax + tags: + - Metrics + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/teamID" + - name: start + in: query + description: Start timestamp in seconds (Unix epoch) + schema: + type: integer + format: int64 + minimum: 0 + - name: end + in: query + description: End timestamp in seconds (Unix epoch) + schema: + type: integer + format: int64 + minimum: 0 + - name: metric + in: query + required: true + description: Which metric to get the maximum value for + schema: + type: string + enum: + - concurrent_sandboxes + - sandbox_start_rate + responses: + "200": + description: Maximum metric value + content: + application/json: + schema: + type: object + properties: + timestampUnix: + type: integer + format: int64 + description: When the max value occurred + value: + type: number + description: The maximum value + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "403": + $ref: "#/components/responses/403" + "500": + $ref: "#/components/responses/500" + /teams: + get: + summary: List teams + description: | + Returns all teams accessible to the authenticated user. + operationId: listTeams + tags: + - Teams + security: + - ApiKeyAuth: [] + responses: + "200": + description: List of teams + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Team" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /templates: + get: + summary: List templates + description: | + Returns all templates accessible to your team, including both custom + templates you've created and public templates. + operationId: listTemplates + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - name: teamID + in: query + required: false + description: Filter templates by team ID + schema: + type: string + responses: + "200": + description: List of templates + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Template" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + post: + summary: Create a new template (legacy) + deprecated: true + description: | + Creates a new template from a Dockerfile. + + **Deprecated:** Use `POST /v3/templates` instead. + operationId: createTemplateLegacy + tags: + - Templates + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TemplateBuildRequest" + responses: + "202": + description: Build accepted + content: + application/json: + schema: + $ref: "#/components/schemas/TemplateLegacy" + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /templates/{templateID}: + get: + summary: Get template details + description: | + Returns detailed information about a template, including all its builds. + operationId: getTemplate + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + - $ref: "#/components/parameters/paginationNextToken" + - $ref: "#/components/parameters/paginationLimit" + responses: + "200": + description: Template details with builds + content: + application/json: + schema: + type: object + properties: + templateID: + type: string + public: + type: boolean + names: + type: array + items: + type: string + builds: + type: array + items: + type: object + properties: + buildID: + type: string + status: + type: string + enum: + - building + - waiting + - ready + - error + createdAt: + type: string + format: date-time + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + delete: + summary: Delete a template + description: | + Permanently deletes a template and all its builds. + + **Warning:** This action cannot be undone. Existing sandboxes created + from this template will continue to work, but no new sandboxes can be + created from it. + operationId: deleteTemplate + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + responses: + "204": + description: Template deleted successfully + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + patch: + summary: Update template + deprecated: true + description: | + Updates template properties (e.g., public/private visibility). + + **Deprecated:** Use `PATCH /v2/templates/{templateID}` instead. + operationId: updateTemplate + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + public: + type: boolean + description: Whether the template is public + responses: + "200": + description: Template updated + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + post: + summary: Rebuild a template (legacy) + deprecated: true + description: | + Triggers a rebuild of an existing template from a Dockerfile. + + **Deprecated:** Use `POST /v3/templates` instead. + operationId: rebuildTemplateLegacy + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TemplateBuildRequest" + responses: + "202": + description: Build accepted + content: + application/json: + schema: + $ref: "#/components/schemas/TemplateLegacy" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /v3/templates: + post: + summary: Create a new template + description: | + Creates a new template and initiates a build. Returns the template ID + and build ID to track the build progress. + operationId: createTemplateV3 + tags: + - Templates + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - dockerfile + properties: + dockerfile: + type: string + description: Dockerfile content for the template + name: + type: string + description: Template name/alias + startCmd: + type: string + description: Command to run on sandbox start + cpuCount: + type: integer + description: Default CPU cores + memoryMB: + type: integer + description: Default memory in MB + diskSizeMB: + type: integer + description: Default disk size in MB + responses: + "202": + description: Build started + content: + application/json: + schema: + type: object + properties: + templateID: + type: string + buildID: + type: string + public: + type: boolean + names: + type: array + items: + type: string + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /v2/templates: + post: + summary: Create a new template (v2) + deprecated: true + description: | + Creates a new template. + + **Deprecated:** Use `POST /v3/templates` instead. + operationId: createTemplateV2 + tags: + - Templates + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + "202": + description: Build started + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /v2/templates/{templateID}: + patch: + summary: Update template (v2) + description: | + Updates template properties such as visibility (public/private). + operationId: updateTemplateV2 + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + public: + type: boolean + description: Whether the template is public + responses: + "200": + description: Template updated + content: + application/json: + schema: + type: object + properties: + names: + type: array + items: + type: string + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /templates/{templateID}/files/{hash}: + get: + summary: Get build file upload link + description: | + Returns a pre-signed upload URL for uploading build layer files + as a tar archive. + operationId: getTemplateFileUploadLink + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + - name: hash + in: path + required: true + description: SHA256 hash of the tar file + schema: + type: string + responses: + "201": + description: Upload link + content: + application/json: + schema: + type: object + properties: + uploadUrl: + type: string + description: Pre-signed URL for uploading the tar file + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /templates/{templateID}/builds/{buildID}: + post: + summary: Start a template build (legacy) + deprecated: true + description: | + Starts a previously created template build. + + **Deprecated:** Use `POST /v2/templates/{templateID}/builds/{buildID}` instead. + operationId: startTemplateBuildLegacy + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + - $ref: "#/components/parameters/buildID" + responses: + "202": + description: Build started + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /v2/templates/{templateID}/builds/{buildID}: + post: + summary: Start a template build + description: | + Triggers the build process for a template. The build must have been + previously created and files uploaded. + operationId: startTemplateBuild + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + - $ref: "#/components/parameters/buildID" + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + "202": + description: Build started + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /templates/{templateID}/builds/{buildID}/status: + get: + summary: Get build status + description: | + Returns the current status and logs for a template build. + operationId: getTemplateBuildStatus + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + - $ref: "#/components/parameters/buildID" + - name: logsOffset + in: query + description: Starting log index + schema: + type: integer + format: int32 + default: 0 + minimum: 0 + - name: limit + in: query + description: Maximum number of logs to return + schema: + type: integer + format: int32 + default: 100 + minimum: 0 + maximum: 100 + - name: level + in: query + description: Filter logs by level + schema: + type: string + enum: + - debug + - info + - warn + - error + responses: + "200": + description: Build status and logs + content: + application/json: + schema: + type: object + properties: + status: + type: string + enum: + - building + - waiting + - ready + - error + logs: + type: array + items: + type: string + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /templates/{templateID}/builds/{buildID}/logs: + get: + summary: Get build logs + description: | + Returns logs from a template build with pagination and filtering options. + operationId: getTemplateBuildLogs + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + - $ref: "#/components/parameters/buildID" + - name: cursor + in: query + description: Starting timestamp in milliseconds for pagination + schema: + type: integer + format: int64 + minimum: 0 + - name: limit + in: query + description: Maximum number of logs to return + schema: + type: integer + format: int32 + default: 100 + minimum: 0 + maximum: 100 + - name: direction + in: query + description: Direction of the logs that should be returned + schema: + type: string + enum: + - forward + - backward + - name: level + in: query + description: Filter logs by level + schema: + type: string + enum: + - debug + - info + - warn + - error + - name: source + in: query + description: Source of the logs that should be returned from + schema: + type: string + enum: + - temporary + - persistent + responses: + "200": + description: Build logs + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /templates/tags: + post: + summary: Assign tags to a template build + description: | + Assigns one or more tags to a specific template build. Tags can be used + to version and identify specific builds (e.g., "latest", "v1.0"). + operationId: assignTemplateTags + tags: + - Templates + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - templateID + - buildID + - tags + properties: + templateID: + type: string + buildID: + type: string + tags: + type: array + items: + type: string + example: + - latest + - v1.0 + responses: + "201": + description: Tags assigned + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + delete: + summary: Delete tags from templates + description: | + Removes tags from template builds. + operationId: deleteTemplateTags + tags: + - Templates + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + "204": + description: Tags deleted + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /templates/aliases/{alias}: + get: + summary: Check template by alias + description: | + Checks if a template with the given alias exists and returns its ID. + operationId: getTemplateByAlias + tags: + - Templates + security: + - ApiKeyAuth: [] + parameters: + - name: alias + in: path + required: true + description: Template alias to look up + schema: + type: string + responses: + "200": + description: Template found + content: + application/json: + schema: + type: object + properties: + templateID: + type: string + "400": + $ref: "#/components/responses/400" + "403": + $ref: "#/components/responses/403" + "404": + $ref: "#/components/responses/404" + "500": + $ref: "#/components/responses/500" + /files: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + description: API port (always 49982) + sandboxId: + default: your-sandbox-id + description: Your sandbox ID from the create response + get: + summary: Download a file + description: | + Downloads a file from the sandbox. The file is returned as binary data. + operationId: downloadFile + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + parameters: + - $ref: "#/components/parameters/SandboxFilePath" + - $ref: "#/components/parameters/SandboxUser" + - $ref: "#/components/parameters/SandboxSignature" + - $ref: "#/components/parameters/SandboxSignatureExpiration" + responses: + "200": + description: File contents + content: + application/octet-stream: + schema: + type: string + format: binary + "400": + description: Invalid path + "401": + description: Invalid user + "404": + description: File not found + "500": + description: Server error + post: + summary: Upload a file + description: | + Uploads a file to the sandbox. Parent directories are created automatically + if they don't exist. If the file already exists, it will be overwritten. + operationId: uploadFile + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + parameters: + - $ref: "#/components/parameters/SandboxFilePath" + - $ref: "#/components/parameters/SandboxUser" + - $ref: "#/components/parameters/SandboxSignature" + - $ref: "#/components/parameters/SandboxSignatureExpiration" + requestBody: + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + responses: + "200": + description: File uploaded successfully + content: + application/json: + schema: + type: array + items: + type: object + properties: + name: + type: string + description: File name + type: + type: string + enum: + - file + - dir + path: + type: string + description: Full path to the file + "400": + description: Invalid path + "401": + description: Invalid user + "500": + description: Server error + "507": + description: Not enough disk space + /filesystem.Filesystem/ListDir: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: List directory contents + description: | + Lists files and subdirectories in the specified directory. + + **Request body:** + ```json + { + "path": "/home/user", + "depth": 1 + } + ``` + operationId: listDirectory + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - path + properties: + path: + type: string + description: Directory path to list + example: /home/user + depth: + type: integer + description: How many levels deep to list (1 = immediate children only) + default: 1 + example: 1 + responses: + "200": + description: Directory listing + content: + application/json: + schema: + type: object + properties: + entries: + type: array + items: + type: object + properties: + name: + type: string + type: + type: string + enum: + - file + - dir + path: + type: string + size: + type: integer + format: int64 + /filesystem.Filesystem/MakeDir: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Create a directory + description: | + Creates a directory at the specified path. Parent directories are + created automatically if they don't exist (like `mkdir -p`). + operationId: makeDirectory + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - path + properties: + path: + type: string + description: Path for the new directory + example: /home/user/projects/new-project + responses: + "200": + description: Directory created + /filesystem.Filesystem/Remove: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Delete a file or directory + description: | + Deletes a file or directory. For directories, all contents are + deleted recursively (like `rm -rf`). + + **Warning:** This action cannot be undone. + operationId: removeFile + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - path + properties: + path: + type: string + description: Path to delete + example: /home/user/temp-file.txt + responses: + "200": + description: File or directory deleted + /filesystem.Filesystem/Move: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Move or rename a file + description: | + Moves a file or directory to a new location. Can also be used to rename. + operationId: moveFile + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - source + - destination + properties: + source: + type: string + description: Current path + example: /home/user/old-name.txt + destination: + type: string + description: New path + example: /home/user/new-name.txt + responses: + "200": + description: File moved + /filesystem.Filesystem/Stat: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Get file information + description: | + Returns metadata about a file or directory (size, type, permissions, etc.). + operationId: statFile + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - path + properties: + path: + type: string + description: Path to inspect + example: /home/user/file.txt + responses: + "200": + description: File information + content: + application/json: + schema: + type: object + properties: + name: + type: string + type: + type: string + enum: + - file + - dir + size: + type: integer + format: int64 + permissions: + type: string + /filesystem.Filesystem/CreateWatcher: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Create a filesystem watcher + description: | + Creates a watcher that monitors a directory for changes. Use + `GetWatcherEvents` to poll for events. This is the non-streaming + alternative to `WatchDir`. + operationId: createWatcher + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - path + properties: + path: + type: string + description: Directory path to watch + example: /home/user/project + responses: + "200": + description: Watcher created + content: + application/json: + schema: + type: object + properties: + watcherID: + type: string + description: ID to use with GetWatcherEvents and RemoveWatcher + /filesystem.Filesystem/GetWatcherEvents: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Get filesystem watcher events + description: | + Retrieves pending filesystem change events from a watcher created + with `CreateWatcher`. Returns events since the last poll. + operationId: getWatcherEvents + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - watcherID + properties: + watcherID: + type: string + description: Watcher ID from CreateWatcher + responses: + "200": + description: Watcher events + content: + application/json: + schema: + type: object + properties: + events: + type: array + items: + type: object + properties: + type: + type: string + enum: + - create + - write + - remove + - rename + path: + type: string + /filesystem.Filesystem/RemoveWatcher: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Remove a filesystem watcher + description: | + Stops and removes a filesystem watcher. No more events will be + generated after this call. + operationId: removeWatcher + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - watcherID + properties: + watcherID: + type: string + description: Watcher ID to remove + responses: + "200": + description: Watcher removed + /filesystem.Filesystem/WatchDir: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Watch directory (streaming) + description: | + Streams filesystem change events for a directory in real-time. + This is the streaming alternative to CreateWatcher + GetWatcherEvents. + + Uses server-sent events (SSE) to push changes as they happen. + operationId: watchDir + tags: + - Sandbox Filesystem + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - path + properties: + path: + type: string + description: Directory path to watch + example: /home/user/project + responses: + "200": + description: Stream of filesystem events + /process.Process/Start: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Start a process + description: | + Starts a new process in the sandbox. Returns a process ID that can be + used to monitor, send input to, or terminate the process. + + **Example - Run a Python script:** + ```json + { + "cmd": "python", + "args": ["script.py"], + "cwd": "/home/user", + "envVars": { + "PYTHONPATH": "/home/user/lib" + } + } + ``` + + **Example - Run a shell command:** + ```json + { + "cmd": "/bin/bash", + "args": ["-c", "echo 'Hello World' && sleep 5"] + } + ``` + operationId: startProcess + tags: + - Sandbox Process + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - cmd + properties: + cmd: + type: string + description: Command to execute + example: python + args: + type: array + items: + type: string + description: Command arguments + example: + - script.py + - "--verbose" + cwd: + type: string + description: Working directory + example: /home/user + envVars: + type: object + additionalProperties: + type: string + description: Environment variables + example: + NODE_ENV: production + responses: + "200": + description: Process started + content: + application/json: + schema: + type: object + properties: + pid: + type: string + description: Process ID for subsequent operations + /process.Process/List: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: List running processes + description: | + Returns a list of all processes currently running in the sandbox. + operationId: listProcesses + tags: + - Sandbox Process + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + responses: + "200": + description: List of processes + content: + application/json: + schema: + type: object + properties: + processes: + type: array + items: + type: object + properties: + pid: + type: string + cmd: + type: string + /process.Process/SendSignal: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Send a signal to a process + description: | + Sends a Unix signal to a process. Common signals: + - `SIGTERM` (15): Request graceful termination + - `SIGKILL` (9): Force immediate termination + - `SIGINT` (2): Interrupt (like Ctrl+C) + operationId: sendSignal + tags: + - Sandbox Process + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - pid + - signal + properties: + pid: + type: string + description: Process ID + signal: + type: integer + description: Signal number (e.g., 9 for SIGKILL, 15 for SIGTERM) + example: 15 + responses: + "200": + description: Signal sent + /process.Process/SendInput: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Send input to a process + description: | + Sends input to the stdin of a running process. Useful for interactive + programs that expect user input. + operationId: sendInput + tags: + - Sandbox Process + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - pid + - input + properties: + pid: + type: string + description: Process ID + input: + type: string + description: Input to send (will be written to stdin) + example: | + yes + responses: + "200": + description: Input sent + /process.Process/Connect: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Connect to a running process + description: | + Connects to an existing running process to stream its output + (stdout/stderr). Use this to monitor long-running processes. + operationId: connectProcess + tags: + - Sandbox Process + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - pid + properties: + pid: + type: string + description: Process ID to connect to + responses: + "200": + description: Stream of process output + /process.Process/StreamInput: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Stream input to a process + description: | + Opens a streaming connection to send continuous input to a process's + stdin. Use this for interactive sessions where you need to send + multiple inputs over time. + operationId: streamInput + tags: + - Sandbox Process + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - pid + properties: + pid: + type: string + description: Process ID + responses: + "200": + description: Streaming input connection established + /process.Process/Update: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox Data Plane API + variables: + port: + default: "49982" + sandboxId: + default: your-sandbox-id + post: + summary: Update a running process + description: | + Updates properties of a running process, such as its environment + variables or resource limits. + operationId: updateProcess + tags: + - Sandbox Process + security: + - AccessTokenAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - pid + properties: + pid: + type: string + description: Process ID to update + responses: + "200": + description: Process updated diff --git a/openapi-public.yml b/openapi-public.yml new file mode 100644 index 00000000..545073a1 --- /dev/null +++ b/openapi-public.yml @@ -0,0 +1,4258 @@ +openapi: 3.0.0 +info: + version: 0.1.0 + title: E2B API + description: | + API for managing and interacting with E2B sandboxes. + + ## REST API (api.e2b.app) + Endpoints for creating and managing sandboxes and templates. + - **Authentication**: `X-API-Key` header with your API key from the [E2B Dashboard](https://e2b.dev/dashboard?tab=keys) + - **Base URL**: `https://api.e2b.app` + + ## Sandbox API ({sandboxID}.e2b.app) + Endpoints for interacting with files and processes inside a running sandbox. + - **Authentication**: `X-Access-Token` header with the access token received when creating a sandbox + - **Base URL**: `https://{sandboxID}.e2b.app` +servers: + - url: https://api.e2b.app +components: + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + AccessTokenAuth: + type: apiKey + in: header + name: X-Access-Token + description: Access token received when creating a sandbox (for Sandbox API endpoints) + parameters: + templateID: + name: templateID + in: path + required: true + schema: + type: string + buildID: + name: buildID + in: path + required: true + schema: + type: string + sandboxID: + name: sandboxID + in: path + required: true + schema: + type: string + teamID: + name: teamID + in: path + required: true + schema: + type: string + nodeID: + name: nodeID + in: path + required: true + schema: + type: string + apiKeyID: + name: apiKeyID + in: path + required: true + schema: + type: string + accessTokenID: + name: accessTokenID + in: path + required: true + schema: + type: string + tag: + name: tag + in: path + required: true + schema: + type: string + description: Tag name + paginationLimit: + name: limit + in: query + description: Maximum number of items to return per page + required: false + schema: + type: integer + format: int32 + minimum: 1 + default: 100 + maximum: 100 + paginationNextToken: + name: nextToken + in: query + description: Cursor to start the list from + required: false + schema: + type: string + SandboxFilePath: + name: path + in: query + required: false + description: Path to the file, URL encoded. Can be relative to user's home directory. + schema: + type: string + SandboxUser: + name: username + in: query + required: false + description: User used for setting the owner, or resolving relative paths. + schema: + type: string + SandboxSignature: + name: signature + in: query + required: false + description: Signature used for file access permission verification. + schema: + type: string + SandboxSignatureExpiration: + name: signature_expiration + in: query + required: false + description: Signature expiration used for defining the expiration time of the signature. + schema: + type: integer + responses: + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + SandboxUploadSuccess: + description: The file was uploaded successfully. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SandboxEntryInfo' + SandboxDownloadSuccess: + description: Entire file downloaded successfully. + content: + application/octet-stream: + schema: + type: string + format: binary + description: The file content + SandboxInvalidPath: + description: Invalid path + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + SandboxInternalServerError: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + SandboxFileNotFound: + description: File not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + SandboxInvalidUser: + description: Invalid user + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + SandboxNotEnoughDiskSpace: + description: Not enough disk space + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + schemas: + Team: + required: + - teamID + - name + - apiKey + - isDefault + properties: + teamID: + type: string + description: Identifier of the team + name: + type: string + description: Name of the team + apiKey: + type: string + description: API key for the team + isDefault: + type: boolean + description: Whether the team is the default team + TeamUser: + required: + - id + - email + properties: + id: + type: string + format: uuid + description: Identifier of the user + email: + type: string + description: Email of the user + TemplateUpdateRequest: + properties: + public: + type: boolean + description: Whether the template is public or only accessible by the team + TemplateUpdateResponse: + required: + - names + properties: + names: + type: array + description: Names of the template (namespace/alias format when namespaced) + items: + type: string + CPUCount: + type: integer + format: int32 + minimum: 1 + description: CPU cores for the sandbox + MemoryMB: + type: integer + format: int32 + minimum: 128 + description: Memory for the sandbox in MiB + DiskSizeMB: + type: integer + format: int32 + minimum: 0 + description: Disk size for the sandbox in MiB + EnvdVersion: + type: string + description: Version of the envd running in the sandbox + SandboxMetadata: + additionalProperties: + type: string + description: Metadata of the sandbox + SandboxState: + type: string + description: State of the sandbox + enum: + - running + - paused + EnvVars: + additionalProperties: + type: string + description: Environment variables for the sandbox + Mcp: + type: object + description: MCP configuration for the sandbox + additionalProperties: {} + nullable: true + SandboxNetworkConfig: + type: object + properties: + allowPublicTraffic: + type: boolean + default: true + description: Specify if the sandbox URLs should be accessible only with authentication. + allowOut: + type: array + description: List of allowed CIDR blocks or IP addresses for egress traffic. Allowed addresses always take precedence over blocked addresses. + items: + type: string + denyOut: + type: array + description: List of denied CIDR blocks or IP addresses for egress traffic + items: + type: string + maskRequestHost: + type: string + description: Specify host mask which will be used for all sandbox requests + SandboxLog: + description: Log entry with timestamp and line + required: + - timestamp + - line + properties: + timestamp: + type: string + format: date-time + description: Timestamp of the log entry + line: + type: string + description: Log line content + SandboxLogEntry: + required: + - timestamp + - level + - message + - fields + properties: + timestamp: + type: string + format: date-time + description: Timestamp of the log entry + message: + type: string + description: Log message content + level: + $ref: '#/components/schemas/SandboxLogLevel' + fields: + type: object + additionalProperties: + type: string + SandboxLogs: + required: + - logs + - logEntries + properties: + logs: + description: Logs of the sandbox + type: array + items: + $ref: '#/components/schemas/SandboxSandboxLog' + logEntries: + description: Structured logs of the sandbox + type: array + items: + $ref: '#/components/schemas/SandboxSandboxLogEntry' + SandboxMetric: + description: Metric entry with timestamp and line + required: + - timestamp + - timestampUnix + - cpuCount + - cpuUsedPct + - memUsed + - memTotal + - diskUsed + - diskTotal + properties: + timestamp: + type: string + format: date-time + deprecated: true + description: Timestamp of the metric entry + timestampUnix: + type: integer + format: int64 + description: Timestamp of the metric entry in Unix time (seconds since epoch) + cpuCount: + type: integer + format: int32 + description: Number of CPU cores + cpuUsedPct: + type: number + format: float + description: CPU usage percentage + memUsed: + type: integer + format: int64 + description: Memory used in bytes + memTotal: + type: integer + format: int64 + description: Total memory in bytes + diskUsed: + type: integer + format: int64 + description: Disk used in bytes + diskTotal: + type: integer + format: int64 + description: Total disk space in bytes + Sandbox: + required: + - templateID + - sandboxID + - clientID + - envdVersion + properties: + templateID: + type: string + description: Identifier of the template from which is the sandbox created + sandboxID: + type: string + description: Identifier of the sandbox + alias: + type: string + description: Alias of the template + clientID: + type: string + deprecated: true + description: Identifier of the client + envdVersion: + $ref: '#/components/schemas/SandboxEnvdVersion' + envdAccessToken: + type: string + description: Access token used for envd communication + trafficAccessToken: + type: string + nullable: true + description: Token required for accessing sandbox via proxy. + domain: + type: string + nullable: true + description: Base domain where the sandbox traffic is accessible + SandboxDetail: + required: + - templateID + - sandboxID + - clientID + - startedAt + - cpuCount + - memoryMB + - diskSizeMB + - endAt + - state + - envdVersion + properties: + templateID: + type: string + description: Identifier of the template from which is the sandbox created + alias: + type: string + description: Alias of the template + sandboxID: + type: string + description: Identifier of the sandbox + clientID: + type: string + deprecated: true + description: Identifier of the client + startedAt: + type: string + format: date-time + description: Time when the sandbox was started + endAt: + type: string + format: date-time + description: Time when the sandbox will expire + envdVersion: + $ref: '#/components/schemas/SandboxEnvdVersion' + envdAccessToken: + type: string + description: Access token used for envd communication + domain: + type: string + nullable: true + description: Base domain where the sandbox traffic is accessible + cpuCount: + $ref: '#/components/schemas/SandboxCPUCount' + memoryMB: + $ref: '#/components/schemas/SandboxMemoryMB' + diskSizeMB: + $ref: '#/components/schemas/SandboxDiskSizeMB' + metadata: + $ref: '#/components/schemas/SandboxSandboxMetadata' + state: + $ref: '#/components/schemas/SandboxSandboxState' + ListedSandbox: + required: + - templateID + - sandboxID + - clientID + - startedAt + - cpuCount + - memoryMB + - diskSizeMB + - endAt + - state + - envdVersion + properties: + templateID: + type: string + description: Identifier of the template from which is the sandbox created + alias: + type: string + description: Alias of the template + sandboxID: + type: string + description: Identifier of the sandbox + clientID: + type: string + deprecated: true + description: Identifier of the client + startedAt: + type: string + format: date-time + description: Time when the sandbox was started + endAt: + type: string + format: date-time + description: Time when the sandbox will expire + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + metadata: + $ref: '#/components/schemas/SandboxMetadata' + state: + $ref: '#/components/schemas/SandboxState' + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + SandboxesWithMetrics: + required: + - sandboxes + properties: + sandboxes: + additionalProperties: + $ref: '#/components/schemas/SandboxSandboxMetric' + NewSandbox: + required: + - templateID + properties: + templateID: + type: string + description: Identifier of the required template + timeout: + type: integer + format: int32 + minimum: 0 + default: 15 + description: Time to live for the sandbox in seconds. + autoPause: + type: boolean + default: false + description: Automatically pauses the sandbox after the timeout + secure: + type: boolean + description: Secure all system communication with sandbox + allow_internet_access: + type: boolean + description: Allow sandbox to access the internet. When set to false, it behaves the same as specifying denyOut to 0.0.0.0/0 in the network config. + network: + $ref: '#/components/schemas/SandboxNetworkConfig' + metadata: + $ref: '#/components/schemas/SandboxMetadata' + envVars: + $ref: '#/components/schemas/EnvVars' + mcp: + $ref: '#/components/schemas/Mcp' + ResumedSandbox: + properties: + timeout: + type: integer + format: int32 + minimum: 0 + default: 15 + description: Time to live for the sandbox in seconds. + autoPause: + type: boolean + deprecated: true + description: Automatically pauses the sandbox after the timeout + ConnectSandbox: + type: object + required: + - timeout + properties: + timeout: + description: Timeout in seconds from the current time after which the sandbox should expire + type: integer + format: int32 + minimum: 0 + TeamMetric: + description: Team metric with timestamp + required: + - timestamp + - timestampUnix + - concurrentSandboxes + - sandboxStartRate + properties: + timestamp: + type: string + format: date-time + deprecated: true + description: Timestamp of the metric entry + timestampUnix: + type: integer + format: int64 + description: Timestamp of the metric entry in Unix time (seconds since epoch) + concurrentSandboxes: + type: integer + format: int32 + description: The number of concurrent sandboxes for the team + sandboxStartRate: + type: number + format: float + description: Number of sandboxes started per second + MaxTeamMetric: + description: Team metric with timestamp + required: + - timestamp + - timestampUnix + - value + properties: + timestamp: + type: string + format: date-time + deprecated: true + description: Timestamp of the metric entry + timestampUnix: + type: integer + format: int64 + description: Timestamp of the metric entry in Unix time (seconds since epoch) + value: + type: number + description: The maximum value of the requested metric in the given interval + AdminSandboxKillResult: + required: + - killedCount + - failedCount + properties: + killedCount: + type: integer + description: Number of sandboxes successfully killed + failedCount: + type: integer + description: Number of sandboxes that failed to kill + Template: + required: + - templateID + - buildID + - cpuCount + - memoryMB + - diskSizeMB + - public + - createdAt + - updatedAt + - createdBy + - lastSpawnedAt + - spawnCount + - buildCount + - envdVersion + - aliases + - names + - buildStatus + properties: + templateID: + type: string + description: Identifier of the template + buildID: + type: string + description: Identifier of the last successful build for given template + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + public: + type: boolean + description: Whether the template is public or only accessible by the team + aliases: + type: array + description: Aliases of the template + deprecated: true + items: + type: string + names: + type: array + description: Names of the template (namespace/alias format when namespaced) + items: + type: string + createdAt: + type: string + format: date-time + description: Time when the template was created + updatedAt: + type: string + format: date-time + description: Time when the template was last updated + createdBy: + allOf: + - $ref: '#/components/schemas/TeamUser' + nullable: true + lastSpawnedAt: + type: string + nullable: true + format: date-time + description: Time when the template was last used + spawnCount: + type: integer + format: int64 + description: Number of times the template was used + buildCount: + type: integer + format: int32 + description: Number of times the template was built + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + buildStatus: + $ref: '#/components/schemas/TemplateBuildStatus' + TemplateRequestResponseV3: + required: + - templateID + - buildID + - public + - aliases + - names + - tags + properties: + templateID: + type: string + description: Identifier of the template + buildID: + type: string + description: Identifier of the last successful build for given template + public: + type: boolean + description: Whether the template is public or only accessible by the team + names: + type: array + description: Names of the template + items: + type: string + tags: + type: array + description: Tags assigned to the template build + items: + type: string + aliases: + type: array + description: Aliases of the template + deprecated: true + items: + type: string + TemplateLegacy: + required: + - templateID + - buildID + - cpuCount + - memoryMB + - diskSizeMB + - public + - createdAt + - updatedAt + - createdBy + - lastSpawnedAt + - spawnCount + - buildCount + - envdVersion + - aliases + properties: + templateID: + type: string + description: Identifier of the template + buildID: + type: string + description: Identifier of the last successful build for given template + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + public: + type: boolean + description: Whether the template is public or only accessible by the team + aliases: + type: array + description: Aliases of the template + items: + type: string + createdAt: + type: string + format: date-time + description: Time when the template was created + updatedAt: + type: string + format: date-time + description: Time when the template was last updated + createdBy: + allOf: + - $ref: '#/components/schemas/TeamUser' + nullable: true + lastSpawnedAt: + type: string + nullable: true + format: date-time + description: Time when the template was last used + spawnCount: + type: integer + format: int64 + description: Number of times the template was used + buildCount: + type: integer + format: int32 + description: Number of times the template was built + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + TemplateBuild: + required: + - buildID + - status + - createdAt + - updatedAt + - cpuCount + - memoryMB + properties: + buildID: + type: string + format: uuid + description: Identifier of the build + status: + $ref: '#/components/schemas/TemplateBuildStatus' + createdAt: + type: string + format: date-time + description: Time when the build was created + updatedAt: + type: string + format: date-time + description: Time when the build was last updated + finishedAt: + type: string + format: date-time + description: Time when the build was finished + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + diskSizeMB: + $ref: '#/components/schemas/DiskSizeMB' + envdVersion: + $ref: '#/components/schemas/EnvdVersion' + TemplateWithBuilds: + required: + - templateID + - public + - aliases + - names + - createdAt + - updatedAt + - lastSpawnedAt + - spawnCount + - builds + properties: + templateID: + type: string + description: Identifier of the template + public: + type: boolean + description: Whether the template is public or only accessible by the team + aliases: + type: array + description: Aliases of the template + deprecated: true + items: + type: string + names: + type: array + description: Names of the template (namespace/alias format when namespaced) + items: + type: string + createdAt: + type: string + format: date-time + description: Time when the template was created + updatedAt: + type: string + format: date-time + description: Time when the template was last updated + lastSpawnedAt: + type: string + nullable: true + format: date-time + description: Time when the template was last used + spawnCount: + type: integer + format: int64 + description: Number of times the template was used + builds: + type: array + description: List of builds for the template + items: + $ref: '#/components/schemas/TemplateBuild' + TemplateAliasResponse: + required: + - templateID + - public + properties: + templateID: + type: string + description: Identifier of the template + public: + type: boolean + description: Whether the template is public or only accessible by the team + TemplateBuildRequest: + required: + - dockerfile + properties: + alias: + description: Alias of the template + type: string + dockerfile: + description: Dockerfile for the template + type: string + teamID: + type: string + description: Identifier of the team + startCmd: + description: Start command to execute in the template after the build + type: string + readyCmd: + description: Ready check command to execute in the template after the build + type: string + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + TemplateStep: + description: Step in the template build process + required: + - type + properties: + type: + type: string + description: Type of the step + args: + default: [] + type: array + description: Arguments for the step + items: + type: string + filesHash: + type: string + description: Hash of the files used in the step + force: + default: false + type: boolean + description: Whether the step should be forced to run regardless of the cache + TemplateBuildRequestV3: + properties: + name: + description: Name of the template. Can include a tag with colon separator (e.g. "my-template" or "my-template:v1"). If tag is included, it will be treated as if the tag was provided in the tags array. + type: string + tags: + type: array + description: Tags to assign to the template build + items: + type: string + alias: + description: Alias of the template. Deprecated, use name instead. + type: string + deprecated: true + teamID: + deprecated: true + type: string + description: Identifier of the team + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + TemplateBuildRequestV2: + required: + - alias + properties: + alias: + description: Alias of the template + type: string + teamID: + deprecated: true + type: string + description: Identifier of the team + cpuCount: + $ref: '#/components/schemas/CPUCount' + memoryMB: + $ref: '#/components/schemas/MemoryMB' + FromImageRegistry: + oneOf: + - $ref: '#/components/schemas/AWSRegistry' + - $ref: '#/components/schemas/GCPRegistry' + - $ref: '#/components/schemas/GeneralRegistry' + discriminator: + propertyName: type + mapping: + aws: '#/components/schemas/AWSRegistry' + gcp: '#/components/schemas/GCPRegistry' + registry: '#/components/schemas/GeneralRegistry' + AWSRegistry: + type: object + required: + - type + - awsAccessKeyId + - awsSecretAccessKey + - awsRegion + properties: + type: + type: string + enum: + - aws + description: Type of registry authentication + awsAccessKeyId: + type: string + description: AWS Access Key ID for ECR authentication + awsSecretAccessKey: + type: string + description: AWS Secret Access Key for ECR authentication + awsRegion: + type: string + description: AWS Region where the ECR registry is located + GCPRegistry: + type: object + required: + - type + - serviceAccountJson + properties: + type: + type: string + enum: + - gcp + description: Type of registry authentication + serviceAccountJson: + type: string + description: Service Account JSON for GCP authentication + GeneralRegistry: + type: object + required: + - type + - username + - password + properties: + type: + type: string + enum: + - registry + description: Type of registry authentication + username: + type: string + description: Username to use for the registry + password: + type: string + description: Password to use for the registry + TemplateBuildStartV2: + type: object + properties: + fromImage: + type: string + description: Image to use as a base for the template build + fromTemplate: + type: string + description: Template to use as a base for the template build + fromImageRegistry: + $ref: '#/components/schemas/FromImageRegistry' + force: + default: false + type: boolean + description: Whether the whole build should be forced to run regardless of the cache + steps: + default: [] + description: List of steps to execute in the template build + type: array + items: + $ref: '#/components/schemas/TemplateStep' + startCmd: + description: Start command to execute in the template after the build + type: string + readyCmd: + description: Ready check command to execute in the template after the build + type: string + TemplateBuildFileUpload: + required: + - present + properties: + present: + type: boolean + description: Whether the file is already present in the cache + url: + description: Url where the file should be uploaded to + type: string + LogLevel: + type: string + description: State of the sandbox + enum: + - debug + - info + - warn + - error + BuildLogEntry: + required: + - timestamp + - message + - level + properties: + timestamp: + type: string + format: date-time + description: Timestamp of the log entry + message: + type: string + description: Log message content + level: + $ref: '#/components/schemas/LogLevel' + step: + type: string + description: Step in the build process related to the log entry + BuildStatusReason: + required: + - message + properties: + message: + type: string + description: Message with the status reason, currently reporting only for error status + step: + type: string + description: Step that failed + logEntries: + default: [] + description: Log entries related to the status reason + type: array + items: + $ref: '#/components/schemas/BuildLogEntry' + TemplateBuildStatus: + type: string + description: Status of the template build + enum: + - building + - waiting + - ready + - error + TemplateBuildInfo: + required: + - templateID + - buildID + - status + - logs + - logEntries + properties: + logs: + default: [] + description: Build logs + type: array + items: + type: string + logEntries: + default: [] + description: Build logs structured + type: array + items: + $ref: '#/components/schemas/BuildLogEntry' + templateID: + type: string + description: Identifier of the template + buildID: + type: string + description: Identifier of the build + status: + $ref: '#/components/schemas/TemplateBuildStatus' + reason: + $ref: '#/components/schemas/BuildStatusReason' + TemplateBuildLogsResponse: + required: + - logs + properties: + logs: + default: [] + description: Build logs structured + type: array + items: + $ref: '#/components/schemas/BuildLogEntry' + LogsDirection: + type: string + description: Direction of the logs that should be returned + enum: + - forward + - backward + x-enum-varnames: + - LogsDirectionForward + - LogsDirectionBackward + LogsSource: + type: string + description: Source of the logs that should be returned + enum: + - temporary + - persistent + x-enum-varnames: + - LogsSourceTemporary + - LogsSourcePersistent + NodeStatus: + type: string + description: Status of the node + enum: + - ready + - draining + - connecting + - unhealthy + x-enum-varnames: + - NodeStatusReady + - NodeStatusDraining + - NodeStatusConnecting + - NodeStatusUnhealthy + NodeStatusChange: + required: + - status + properties: + clusterID: + type: string + format: uuid + description: Identifier of the cluster + status: + $ref: '#/components/schemas/NodeStatus' + DiskMetrics: + required: + - mountPoint + - device + - filesystemType + - usedBytes + - totalBytes + properties: + mountPoint: + type: string + description: Mount point of the disk + device: + type: string + description: Device name + filesystemType: + type: string + description: Filesystem type (e.g., ext4, xfs) + usedBytes: + type: integer + format: uint64 + description: Used space in bytes + totalBytes: + type: integer + format: uint64 + description: Total space in bytes + NodeMetrics: + description: Node metrics + required: + - allocatedCPU + - allocatedMemoryBytes + - cpuPercent + - memoryUsedBytes + - cpuCount + - memoryTotalBytes + - disks + properties: + allocatedCPU: + type: integer + format: uint32 + description: Number of allocated CPU cores + cpuPercent: + type: integer + format: uint32 + description: Node CPU usage percentage + cpuCount: + type: integer + format: uint32 + description: Total number of CPU cores on the node + allocatedMemoryBytes: + type: integer + format: uint64 + description: Amount of allocated memory in bytes + memoryUsedBytes: + type: integer + format: uint64 + description: Node memory used in bytes + memoryTotalBytes: + type: integer + format: uint64 + description: Total node memory in bytes + disks: + type: array + description: Detailed metrics for each disk/mount point + items: + $ref: '#/components/schemas/DiskMetrics' + MachineInfo: + required: + - cpuFamily + - cpuModel + - cpuModelName + - cpuArchitecture + properties: + cpuFamily: + type: string + description: CPU family of the node + cpuModel: + type: string + description: CPU model of the node + cpuModelName: + type: string + description: CPU model name of the node + cpuArchitecture: + type: string + description: CPU architecture of the node + Node: + required: + - nodeID + - id + - serviceInstanceID + - clusterID + - status + - sandboxCount + - metrics + - createSuccesses + - createFails + - sandboxStartingCount + - version + - commit + - machineInfo + properties: + version: + type: string + description: Version of the orchestrator + commit: + type: string + description: Commit of the orchestrator + nodeID: + type: string + deprecated: true + description: Identifier of the nomad node + id: + type: string + description: Identifier of the node + serviceInstanceID: + type: string + description: Service instance identifier of the node + clusterID: + type: string + description: Identifier of the cluster + machineInfo: + $ref: '#/components/schemas/MachineInfo' + status: + $ref: '#/components/schemas/NodeStatus' + sandboxCount: + type: integer + format: uint32 + description: Number of sandboxes running on the node + metrics: + $ref: '#/components/schemas/NodeMetrics' + createSuccesses: + type: integer + format: uint64 + description: Number of sandbox create successes + createFails: + type: integer + format: uint64 + description: Number of sandbox create fails + sandboxStartingCount: + type: integer + format: int + description: Number of starting Sandboxes + NodeDetail: + required: + - nodeID + - id + - serviceInstanceID + - clusterID + - status + - sandboxes + - cachedBuilds + - createSuccesses + - createFails + - version + - commit + - metrics + - machineInfo + properties: + clusterID: + type: string + description: Identifier of the cluster + version: + type: string + description: Version of the orchestrator + commit: + type: string + description: Commit of the orchestrator + id: + type: string + description: Identifier of the node + serviceInstanceID: + type: string + description: Service instance identifier of the node + nodeID: + type: string + deprecated: true + description: Identifier of the nomad node + machineInfo: + $ref: '#/components/schemas/MachineInfo' + status: + $ref: '#/components/schemas/NodeStatus' + sandboxes: + type: array + description: List of sandboxes running on the node + items: + $ref: '#/components/schemas/ListedSandbox' + metrics: + $ref: '#/components/schemas/NodeMetrics' + cachedBuilds: + type: array + description: List of cached builds id on the node + items: + type: string + createSuccesses: + type: integer + format: uint64 + description: Number of sandbox create successes + createFails: + type: integer + format: uint64 + description: Number of sandbox create fails + CreatedAccessToken: + required: + - id + - name + - token + - mask + - createdAt + properties: + id: + type: string + format: uuid + description: Identifier of the access token + name: + type: string + description: Name of the access token + token: + type: string + description: The fully created access token + mask: + $ref: '#/components/schemas/IdentifierMaskingDetails' + createdAt: + type: string + format: date-time + description: Timestamp of access token creation + NewAccessToken: + required: + - name + properties: + name: + type: string + description: Name of the access token + TeamAPIKey: + required: + - id + - name + - mask + - createdAt + properties: + id: + type: string + format: uuid + description: Identifier of the API key + name: + type: string + description: Name of the API key + mask: + $ref: '#/components/schemas/IdentifierMaskingDetails' + createdAt: + type: string + format: date-time + description: Timestamp of API key creation + createdBy: + allOf: + - $ref: '#/components/schemas/TeamUser' + nullable: true + lastUsed: + type: string + format: date-time + description: Last time this API key was used + nullable: true + CreatedTeamAPIKey: + required: + - id + - key + - mask + - name + - createdAt + properties: + id: + type: string + format: uuid + description: Identifier of the API key + key: + type: string + description: Raw value of the API key + mask: + $ref: '#/components/schemas/IdentifierMaskingDetails' + name: + type: string + description: Name of the API key + createdAt: + type: string + format: date-time + description: Timestamp of API key creation + createdBy: + allOf: + - $ref: '#/components/schemas/TeamUser' + nullable: true + lastUsed: + type: string + format: date-time + description: Last time this API key was used + nullable: true + NewTeamAPIKey: + required: + - name + properties: + name: + type: string + description: Name of the API key + UpdateTeamAPIKey: + required: + - name + properties: + name: + type: string + description: New name for the API key + AssignedTemplateTags: + required: + - tags + - buildID + properties: + tags: + type: array + items: + type: string + description: Assigned tags of the template + buildID: + type: string + format: uuid + description: Identifier of the build associated with these tags + AssignTemplateTagsRequest: + required: + - target + - tags + properties: + target: + type: string + description: Target template in "name:tag" format + tags: + description: Tags to assign to the template + type: array + items: + type: string + DeleteTemplateTagsRequest: + required: + - name + - tags + properties: + name: + type: string + description: Name of the template + tags: + description: Tags to delete + type: array + items: + type: string + Error: + required: + - code + - message + properties: + code: + type: integer + format: int32 + description: Error code + message: + type: string + description: Error + IdentifierMaskingDetails: + required: + - prefix + - valueLength + - maskedValuePrefix + - maskedValueSuffix + properties: + prefix: + type: string + description: Prefix that identifies the token or key type + valueLength: + type: integer + description: Length of the token or key + maskedValuePrefix: + type: string + description: Prefix used in masked version of the token or key + maskedValueSuffix: + type: string + description: Suffix used in masked version of the token or key + SandboxError: + required: + - message + - code + properties: + message: + type: string + description: Error message + code: + type: integer + description: Error code + SandboxEntryInfo: + required: + - path + - name + - type + properties: + path: + type: string + description: Path to the file + name: + type: string + description: Name of the file + type: + type: string + description: Type of the file + enum: + - file + SandboxEnvVars: + type: object + description: Environment variables to set + additionalProperties: + type: string + SandboxMetrics: + type: object + description: Resource usage metrics + properties: + ts: + type: integer + format: int64 + description: Unix timestamp in UTC for current sandbox time + cpu_count: + type: integer + description: Number of CPU cores + cpu_used_pct: + type: number + format: float + description: CPU usage percentage + mem_total: + type: integer + description: Total virtual memory in bytes + mem_used: + type: integer + description: Used virtual memory in bytes + disk_used: + type: integer + description: Used disk space in bytes + disk_total: + type: integer + description: Total disk space in bytes + Sandboxconnect.error_details.Any: + type: object + properties: + type: + type: string + description: 'A URL that acts as a globally unique identifier for the type of the serialized message. For example: `type.googleapis.com/google.rpc.ErrorInfo`. This is used to determine the schema of the data in the `value` field and is the discriminator for the `debug` field.' + value: + type: string + format: binary + description: The Protobuf message, serialized as bytes and base64-encoded. The specific message type is identified by the `type` field. + debug: + oneOf: + - type: object + title: Any + additionalProperties: true + description: Detailed error information. + discriminator: + propertyName: type + title: Debug + description: Deserialized error detail payload. The 'type' field indicates the schema. This field is for easier debugging and should not be relied upon for application logic. + additionalProperties: true + description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message, with an additional debug field for ConnectRPC error details. + Sandboxfilesystem.CreateWatcherRequest: + type: object + properties: + path: + type: string + title: path + recursive: + type: boolean + title: recursive + title: CreateWatcherRequest + additionalProperties: false + Sandboxfilesystem.CreateWatcherResponse: + type: object + properties: + watcherId: + type: string + title: watcher_id + title: CreateWatcherResponse + additionalProperties: false + Sandboxfilesystem.EntryInfo: + type: object + properties: + name: + type: string + title: name + type: + title: type + $ref: '#/components/schemas/Sandboxfilesystem.FileType' + path: + type: string + title: path + size: + type: integer + title: size + format: int64 + mode: + type: integer + title: mode + permissions: + type: string + title: permissions + owner: + type: string + title: owner + group: + type: string + title: group + modifiedTime: + title: modified_time + $ref: '#/components/schemas/Sandboxgoogle.protobuf.Timestamp' + symlinkTarget: + type: string + title: symlink_target + description: If the entry is a symlink, this field contains the target of the symlink. + title: EntryInfo + additionalProperties: false + Sandboxfilesystem.EventType: + type: string + title: EventType + enum: + - EVENT_TYPE_UNSPECIFIED + - EVENT_TYPE_CREATE + - EVENT_TYPE_WRITE + - EVENT_TYPE_REMOVE + - EVENT_TYPE_RENAME + - EVENT_TYPE_CHMOD + Sandboxfilesystem.FileType: + type: string + title: FileType + enum: + - FILE_TYPE_UNSPECIFIED + - FILE_TYPE_FILE + - FILE_TYPE_DIRECTORY + Sandboxfilesystem.FilesystemEvent: + type: object + properties: + name: + type: string + title: name + type: + title: type + $ref: '#/components/schemas/Sandboxfilesystem.EventType' + title: FilesystemEvent + additionalProperties: false + Sandboxfilesystem.GetWatcherEventsRequest: + type: object + properties: + watcherId: + type: string + title: watcher_id + title: GetWatcherEventsRequest + additionalProperties: false + Sandboxfilesystem.GetWatcherEventsResponse: + type: object + properties: + events: + type: array + items: + $ref: '#/components/schemas/Sandboxfilesystem.FilesystemEvent' + title: events + title: GetWatcherEventsResponse + additionalProperties: false + Sandboxfilesystem.ListDirRequest: + type: object + properties: + path: + type: string + title: path + depth: + type: integer + title: depth + title: ListDirRequest + additionalProperties: false + Sandboxfilesystem.ListDirResponse: + type: object + properties: + entries: + type: array + items: + $ref: '#/components/schemas/Sandboxfilesystem.EntryInfo' + title: entries + title: ListDirResponse + additionalProperties: false + Sandboxfilesystem.MakeDirRequest: + type: object + properties: + path: + type: string + title: path + title: MakeDirRequest + additionalProperties: false + Sandboxfilesystem.MakeDirResponse: + type: object + properties: + entry: + title: entry + $ref: '#/components/schemas/Sandboxfilesystem.EntryInfo' + title: MakeDirResponse + additionalProperties: false + Sandboxfilesystem.MoveRequest: + type: object + properties: + source: + type: string + title: source + destination: + type: string + title: destination + title: MoveRequest + additionalProperties: false + Sandboxfilesystem.MoveResponse: + type: object + properties: + entry: + title: entry + $ref: '#/components/schemas/Sandboxfilesystem.EntryInfo' + title: MoveResponse + additionalProperties: false + Sandboxfilesystem.RemoveRequest: + type: object + properties: + path: + type: string + title: path + title: RemoveRequest + additionalProperties: false + Sandboxfilesystem.RemoveResponse: + type: object + title: RemoveResponse + additionalProperties: false + Sandboxfilesystem.RemoveWatcherRequest: + type: object + properties: + watcherId: + type: string + title: watcher_id + title: RemoveWatcherRequest + additionalProperties: false + Sandboxfilesystem.RemoveWatcherResponse: + type: object + title: RemoveWatcherResponse + additionalProperties: false + Sandboxfilesystem.StatRequest: + type: object + properties: + path: + type: string + title: path + title: StatRequest + additionalProperties: false + Sandboxfilesystem.StatResponse: + type: object + properties: + entry: + title: entry + $ref: '#/components/schemas/Sandboxfilesystem.EntryInfo' + title: StatResponse + additionalProperties: false + Sandboxfilesystem.WatchDirRequest: + type: object + properties: + path: + type: string + title: path + recursive: + type: boolean + title: recursive + title: WatchDirRequest + additionalProperties: false + Sandboxfilesystem.WatchDirResponse: + type: object + oneOf: + - properties: + filesystem: + title: filesystem + $ref: '#/components/schemas/Sandboxfilesystem.FilesystemEvent' + title: filesystem + required: + - filesystem + - properties: + keepalive: + title: keepalive + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse.KeepAlive' + title: keepalive + required: + - keepalive + - properties: + start: + title: start + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse.StartEvent' + title: start + required: + - start + title: WatchDirResponse + additionalProperties: false + Sandboxfilesystem.WatchDirResponse.KeepAlive: + type: object + title: KeepAlive + additionalProperties: false + Sandboxfilesystem.WatchDirResponse.StartEvent: + type: object + title: StartEvent + additionalProperties: false + Sandboxgoogle.protobuf.Timestamp: + type: string + format: date-time + description: |- + A Timestamp represents a point in time independent of any time zone or local + calendar, encoded as a count of seconds and fractions of seconds at + nanosecond resolution. The count is relative to an epoch at UTC midnight on + January 1, 1970, in the proleptic Gregorian calendar which extends the + Gregorian calendar backwards to year one. + + All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap + second table is needed for interpretation, using a [24-hour linear + smear](https://developers.google.com/time/smear). + + The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By + restricting to that range, we ensure that we can convert to and from [RFC + 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. + + # Examples + + Example 1: Compute Timestamp from POSIX `time()`. + + Timestamp timestamp; + timestamp.set_seconds(time(NULL)); + timestamp.set_nanos(0); + + Example 2: Compute Timestamp from POSIX `gettimeofday()`. + + struct timeval tv; + gettimeofday(&tv, NULL); + + Timestamp timestamp; + timestamp.set_seconds(tv.tv_sec); + timestamp.set_nanos(tv.tv_usec * 1000); + + Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + + FILETIME ft; + GetSystemTimeAsFileTime(&ft); + UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + + // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + Timestamp timestamp; + timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + + Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + + long millis = System.currentTimeMillis(); + + Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + .setNanos((int) ((millis % 1000) * 1000000)).build(); + + Example 5: Compute Timestamp from Java `Instant.now()`. + + Instant now = Instant.now(); + + Timestamp timestamp = + Timestamp.newBuilder().setSeconds(now.getEpochSecond()) + .setNanos(now.getNano()).build(); + + Example 6: Compute Timestamp from current time in Python. + + timestamp = Timestamp() + timestamp.GetCurrentTime() + + # JSON Mapping + + In JSON format, the Timestamp type is encoded as a string in the + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the + format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" + where {year} is always expressed using four digits while {month}, {day}, + {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional + seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), + are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone + is required. A proto3 JSON serializer should always use UTC (as indicated by + "Z") when printing the Timestamp type and a proto3 JSON parser should be + able to accept both UTC and other timezones (as indicated by an offset). + + For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past + 01:30 UTC on January 15, 2017. + + In JavaScript, one can convert a Date object to this format using the + standard + [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) + method. In Python, a standard `datetime.datetime` object can be converted + to this format using + [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with + the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use + the Joda Time's [`ISODateTimeFormat.dateTime()`]( + http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() + ) to obtain a formatter capable of generating timestamps in this format. + example: '2023-01-15T01:30:15.01Z' + Sandboxprocess.ConnectRequest: + type: object + properties: + process: + title: process + $ref: '#/components/schemas/Sandboxprocess.ProcessSelector' + title: ConnectRequest + additionalProperties: false + Sandboxprocess.ConnectResponse: + type: object + properties: + event: + title: event + $ref: '#/components/schemas/Sandboxprocess.ProcessEvent' + title: ConnectResponse + additionalProperties: false + Sandboxprocess.ListRequest: + type: object + title: ListRequest + additionalProperties: false + Sandboxprocess.ListResponse: + type: object + properties: + processes: + type: array + items: + $ref: '#/components/schemas/Sandboxprocess.ProcessInfo' + title: processes + title: ListResponse + additionalProperties: false + Sandboxprocess.PTY: + type: object + properties: + size: + title: size + $ref: '#/components/schemas/Sandboxprocess.PTY.Size' + title: PTY + additionalProperties: false + Sandboxprocess.PTY.Size: + type: object + properties: + cols: + type: integer + title: cols + rows: + type: integer + title: rows + title: Size + additionalProperties: false + Sandboxprocess.ProcessConfig: + type: object + properties: + cmd: + type: string + title: cmd + args: + type: array + items: + type: string + title: args + envs: + type: object + title: envs + additionalProperties: + type: string + title: value + cwd: + type: string + title: cwd + title: ProcessConfig + additionalProperties: false + Sandboxprocess.ProcessConfig.EnvsEntry: + type: object + properties: + key: + type: string + title: key + value: + type: string + title: value + title: EnvsEntry + additionalProperties: false + Sandboxprocess.ProcessEvent: + type: object + oneOf: + - properties: + data: + title: data + $ref: '#/components/schemas/Sandboxprocess.ProcessEvent.DataEvent' + title: data + required: + - data + - properties: + end: + title: end + $ref: '#/components/schemas/Sandboxprocess.ProcessEvent.EndEvent' + title: end + required: + - end + - properties: + keepalive: + title: keepalive + $ref: '#/components/schemas/Sandboxprocess.ProcessEvent.KeepAlive' + title: keepalive + required: + - keepalive + - properties: + start: + title: start + $ref: '#/components/schemas/Sandboxprocess.ProcessEvent.StartEvent' + title: start + required: + - start + title: ProcessEvent + additionalProperties: false + Sandboxprocess.ProcessEvent.DataEvent: + type: object + oneOf: + - properties: + pty: + type: string + title: pty + format: byte + title: pty + required: + - pty + - properties: + stderr: + type: string + title: stderr + format: byte + title: stderr + required: + - stderr + - properties: + stdout: + type: string + title: stdout + format: byte + title: stdout + required: + - stdout + title: DataEvent + additionalProperties: false + Sandboxprocess.ProcessEvent.EndEvent: + type: object + properties: + exitCode: + type: integer + title: exit_code + format: int32 + exited: + type: boolean + title: exited + status: + type: string + title: status + error: + type: string + title: error + title: EndEvent + additionalProperties: false + Sandboxprocess.ProcessEvent.KeepAlive: + type: object + title: KeepAlive + additionalProperties: false + Sandboxprocess.ProcessEvent.StartEvent: + type: object + properties: + pid: + type: integer + title: pid + title: StartEvent + additionalProperties: false + Sandboxprocess.ProcessInfo: + type: object + properties: + config: + title: config + $ref: '#/components/schemas/Sandboxprocess.ProcessConfig' + pid: + type: integer + title: pid + tag: + type: string + title: tag + title: ProcessInfo + additionalProperties: false + Sandboxprocess.ProcessInput: + type: object + oneOf: + - properties: + pty: + type: string + title: pty + format: byte + title: pty + required: + - pty + - properties: + stdin: + type: string + title: stdin + format: byte + title: stdin + required: + - stdin + title: ProcessInput + additionalProperties: false + Sandboxprocess.ProcessSelector: + type: object + oneOf: + - properties: + pid: + type: integer + title: pid + title: pid + required: + - pid + - properties: + tag: + type: string + title: tag + title: tag + required: + - tag + title: ProcessSelector + additionalProperties: false + Sandboxprocess.SendInputRequest: + type: object + properties: + process: + title: process + $ref: '#/components/schemas/Sandboxprocess.ProcessSelector' + input: + title: input + $ref: '#/components/schemas/Sandboxprocess.ProcessInput' + title: SendInputRequest + additionalProperties: false + Sandboxprocess.SendInputResponse: + type: object + title: SendInputResponse + additionalProperties: false + Sandboxprocess.SendSignalRequest: + type: object + properties: + process: + title: process + $ref: '#/components/schemas/Sandboxprocess.ProcessSelector' + signal: + title: signal + $ref: '#/components/schemas/Sandboxprocess.Signal' + title: SendSignalRequest + additionalProperties: false + Sandboxprocess.SendSignalResponse: + type: object + title: SendSignalResponse + additionalProperties: false + Sandboxprocess.Signal: + type: string + title: Signal + enum: + - SIGNAL_UNSPECIFIED + - SIGNAL_SIGTERM + - SIGNAL_SIGKILL + Sandboxprocess.StartRequest: + type: object + properties: + process: + title: process + $ref: '#/components/schemas/Sandboxprocess.ProcessConfig' + pty: + title: pty + nullable: true + $ref: '#/components/schemas/Sandboxprocess.PTY' + tag: + type: string + title: tag + stdin: + type: boolean + title: stdin + description: |- + This is optional for backwards compatibility. + We default to true. New SDK versions will set this to false by default. + title: StartRequest + additionalProperties: false + Sandboxprocess.StartResponse: + type: object + properties: + event: + title: event + $ref: '#/components/schemas/Sandboxprocess.ProcessEvent' + title: StartResponse + additionalProperties: false + Sandboxprocess.StreamInputRequest: + type: object + oneOf: + - properties: + data: + title: data + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest.DataEvent' + title: data + required: + - data + - properties: + keepalive: + title: keepalive + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest.KeepAlive' + title: keepalive + required: + - keepalive + - properties: + start: + title: start + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest.StartEvent' + title: start + required: + - start + title: StreamInputRequest + additionalProperties: false + Sandboxprocess.StreamInputRequest.DataEvent: + type: object + properties: + input: + title: input + $ref: '#/components/schemas/Sandboxprocess.ProcessInput' + title: DataEvent + additionalProperties: false + Sandboxprocess.StreamInputRequest.KeepAlive: + type: object + title: KeepAlive + additionalProperties: false + Sandboxprocess.StreamInputRequest.StartEvent: + type: object + properties: + process: + title: process + $ref: '#/components/schemas/Sandboxprocess.ProcessSelector' + title: StartEvent + additionalProperties: false + Sandboxprocess.StreamInputResponse: + type: object + title: StreamInputResponse + additionalProperties: false + Sandboxprocess.UpdateRequest: + type: object + properties: + process: + title: process + $ref: '#/components/schemas/Sandboxprocess.ProcessSelector' + pty: + title: pty + nullable: true + $ref: '#/components/schemas/Sandboxprocess.PTY' + title: UpdateRequest + additionalProperties: false + Sandboxprocess.UpdateResponse: + type: object + title: UpdateResponse + additionalProperties: false + requestBodies: + SandboxFile: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary +tags: + - name: templates + - name: sandboxes + - name: auth + - name: access-tokens + - name: api-keys + - name: tags + - name: Sandbox + description: Sandbox initialization + - name: Sandbox Files + description: Upload and download files in sandbox + - name: Sandbox Filesystem + description: Filesystem operations (list, create, move, delete) + - name: Sandbox Process + description: Process management (start, stop, send input) +paths: + /teams/{teamID}/metrics: + get: + description: Get metrics for the team + tags: + - auth + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/teamID' + - in: query + name: start + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the start of the interval, in seconds, for which the metrics + - in: query + name: end + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the end of the interval, in seconds, for which the metrics + responses: + '200': + description: Successfully returned the team metrics + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TeamMetric' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '403': + $ref: '#/components/responses/403' + '500': + $ref: '#/components/responses/500' + /teams/{teamID}/metrics/max: + get: + description: Get the maximum metrics for the team in the given interval + tags: + - auth + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/teamID' + - in: query + name: start + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the start of the interval, in seconds, for which the metrics + - in: query + name: end + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the end of the interval, in seconds, for which the metrics + - in: query + name: metric + required: true + schema: + type: string + enum: + - concurrent_sandboxes + - sandbox_start_rate + description: Metric to retrieve the maximum value for + responses: + '200': + description: Successfully returned the team metrics + content: + application/json: + schema: + $ref: '#/components/schemas/MaxTeamMetric' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '403': + $ref: '#/components/responses/403' + '500': + $ref: '#/components/responses/500' + /sandboxes: + get: + description: List all running sandboxes + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - name: metadata + in: query + description: Metadata query used to filter the sandboxes (e.g. "user=abc&app=prod"). Each key and values must be URL encoded. + required: false + schema: + type: string + responses: + '200': + description: Successfully returned all running sandboxes + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/ListedSandbox' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + post: + description: Create a sandbox from the template + tags: + - sandboxes + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/NewSandbox' + responses: + '201': + description: The sandbox was created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Sandbox' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /v2/sandboxes: + get: + description: List all sandboxes + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - name: metadata + in: query + description: Metadata query used to filter the sandboxes (e.g. "user=abc&app=prod"). Each key and values must be URL encoded. + required: false + schema: + type: string + - name: state + in: query + description: Filter sandboxes by one or more states + required: false + schema: + type: array + items: + $ref: '#/components/schemas/SandboxState' + style: form + explode: false + - $ref: '#/components/parameters/paginationNextToken' + - $ref: '#/components/parameters/paginationLimit' + responses: + '200': + description: Successfully returned all running sandboxes + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/ListedSandbox' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /sandboxes/metrics: + get: + description: List metrics for given sandboxes + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - name: sandbox_ids + in: query + required: true + description: Comma-separated list of sandbox IDs to get metrics for + explode: false + schema: + type: array + items: + type: string + maxItems: 100 + uniqueItems: true + responses: + '200': + description: Successfully returned all running sandboxes with metrics + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxesWithMetrics' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /sandboxes/{sandboxID}/logs: + get: + description: Get sandbox logs + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + - in: query + name: start + schema: + type: integer + format: int64 + minimum: 0 + description: Starting timestamp of the logs that should be returned in milliseconds + - in: query + name: limit + schema: + default: 1000 + format: int32 + minimum: 0 + type: integer + description: Maximum number of logs that should be returned + responses: + '200': + description: Successfully returned the sandbox logs + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxLogs' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /sandboxes/{sandboxID}: + get: + description: Get a sandbox by id + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '200': + description: Successfully returned the sandbox + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxDetail' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + delete: + description: Kill a sandbox + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '204': + description: The sandbox was killed successfully + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /sandboxes/{sandboxID}/metrics: + get: + description: Get sandbox metrics + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + - in: query + name: start + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the start of the interval, in seconds, for which the metrics + - in: query + name: end + schema: + type: integer + format: int64 + minimum: 0 + description: Unix timestamp for the end of the interval, in seconds, for which the metrics + responses: + '200': + description: Successfully returned the sandbox metrics + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/SandboxMetric' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /sandboxes/{sandboxID}/pause: + post: + description: Pause the sandbox + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '204': + description: The sandbox was paused successfully and can be resumed + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '409': + $ref: '#/components/responses/409' + '500': + $ref: '#/components/responses/500' + /sandboxes/{sandboxID}/resume: + post: + deprecated: true + description: Resume the sandbox + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ResumedSandbox' + responses: + '201': + description: The sandbox was resumed successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Sandbox' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '409': + $ref: '#/components/responses/409' + '500': + $ref: '#/components/responses/500' + /sandboxes/{sandboxID}/connect: + post: + description: Returns sandbox details. If the sandbox is paused, it will be resumed. TTL is only extended. + tags: + - sandboxes + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/sandboxID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ConnectSandbox' + responses: + '200': + description: The sandbox was already running + content: + application/json: + schema: + $ref: '#/components/schemas/Sandbox' + '201': + description: The sandbox was resumed successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Sandbox' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /sandboxes/{sandboxID}/timeout: + post: + description: Set the timeout for the sandbox. The sandbox will expire x seconds from the time of the request. Calling this method multiple times overwrites the TTL, each time using the current timestamp as the starting point to measure the timeout duration. + security: + - ApiKeyAuth: [] + tags: + - sandboxes + requestBody: + content: + application/json: + schema: + type: object + required: + - timeout + properties: + timeout: + description: Timeout in seconds from the current time after which the sandbox should expire + type: integer + format: int32 + minimum: 0 + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '204': + description: Successfully set the sandbox timeout + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /sandboxes/{sandboxID}/refreshes: + post: + description: Refresh the sandbox extending its time to live + security: + - ApiKeyAuth: [] + tags: + - sandboxes + requestBody: + content: + application/json: + schema: + type: object + properties: + duration: + description: Duration for which the sandbox should be kept alive in seconds + type: integer + maximum: 3600 + minimum: 0 + parameters: + - $ref: '#/components/parameters/sandboxID' + responses: + '204': + description: Successfully refreshed the sandbox + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + /v3/templates: + post: + description: Create a new template + tags: + - templates + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildRequestV3' + responses: + '202': + description: The build was requested successfully + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateRequestResponseV3' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /v2/templates: + post: + description: Create a new template + deprecated: true + tags: + - templates + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildRequestV2' + responses: + '202': + description: The build was requested successfully + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateLegacy' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /templates/{templateID}/files/{hash}: + get: + description: Get an upload link for a tar file containing build layer files + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - in: path + name: hash + required: true + schema: + type: string + description: Hash of the files + responses: + '201': + description: The upload link where to upload the tar file + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildFileUpload' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /templates: + get: + description: List all templates + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - in: query + required: false + name: teamID + schema: + type: string + description: Identifier of the team + responses: + '200': + description: Successfully returned all templates + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Template' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /templates/{templateID}: + get: + description: List all builds for a template + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - $ref: '#/components/parameters/paginationNextToken' + - $ref: '#/components/parameters/paginationLimit' + responses: + '200': + description: Successfully returned the template with its builds + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateWithBuilds' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + delete: + description: Delete a template + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + responses: + '204': + description: The template was deleted successfully + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + patch: + description: Update template + deprecated: true + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateUpdateRequest' + responses: + '200': + description: The template was updated successfully + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /v2/templates/{templateID}/builds/{buildID}: + post: + description: Start the build + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - $ref: '#/components/parameters/buildID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildStartV2' + responses: + '202': + description: The build has started + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /v2/templates/{templateID}: + patch: + description: Update template + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateUpdateRequest' + responses: + '200': + description: The template was updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateUpdateResponse' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '500': + $ref: '#/components/responses/500' + /templates/{templateID}/builds/{buildID}/status: + get: + description: Get template build info + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - $ref: '#/components/parameters/buildID' + - in: query + name: logsOffset + schema: + default: 0 + type: integer + format: int32 + minimum: 0 + description: Index of the starting build log that should be returned with the template + - in: query + name: limit + schema: + default: 100 + type: integer + format: int32 + minimum: 0 + maximum: 100 + description: Maximum number of logs that should be returned + - in: query + name: level + schema: + $ref: '#/components/schemas/LogLevel' + responses: + '200': + description: Successfully returned the template + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildInfo' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /templates/{templateID}/builds/{buildID}/logs: + get: + description: Get template build logs + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - $ref: '#/components/parameters/templateID' + - $ref: '#/components/parameters/buildID' + - in: query + name: cursor + schema: + type: integer + format: int64 + minimum: 0 + description: Starting timestamp of the logs that should be returned in milliseconds + - in: query + name: limit + schema: + default: 100 + type: integer + format: int32 + minimum: 0 + maximum: 100 + description: Maximum number of logs that should be returned + - in: query + name: direction + schema: + $ref: '#/components/schemas/LogsDirection' + - in: query + name: level + schema: + $ref: '#/components/schemas/LogLevel' + - in: query + name: source + schema: + $ref: '#/components/schemas/LogsSource' + description: Source of the logs that should be returned from + responses: + '200': + description: Successfully returned the template build logs + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateBuildLogsResponse' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /templates/tags: + post: + description: Assign tag(s) to a template build + tags: + - tags + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AssignTemplateTagsRequest' + responses: + '201': + description: Tag assigned successfully + content: + application/json: + schema: + $ref: '#/components/schemas/AssignedTemplateTags' + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + delete: + description: Delete multiple tags from templates + tags: + - tags + security: + - ApiKeyAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteTemplateTagsRequest' + responses: + '204': + description: Tags deleted successfully + '400': + $ref: '#/components/responses/400' + '401': + $ref: '#/components/responses/401' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /templates/aliases/{alias}: + get: + description: Check if template with given alias exists + tags: + - templates + security: + - ApiKeyAuth: [] + parameters: + - name: alias + in: path + required: true + schema: + type: string + description: Template alias + responses: + '200': + description: Successfully queried template by alias + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateAliasResponse' + '400': + $ref: '#/components/responses/400' + '403': + $ref: '#/components/responses/403' + '404': + $ref: '#/components/responses/404' + '500': + $ref: '#/components/responses/500' + /init: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + summary: Set initial vars, ensure the time and metadata is synced with the host + security: + - AccessTokenAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + hyperloopIP: + type: string + description: IP address of the hyperloop server to connect to + envVars: + $ref: '#/components/schemas/SandboxEnvVars' + accessToken: + type: string + description: Access token for secure access to envd service + x-go-type: SecureToken + timestamp: + type: string + format: date-time + description: The current timestamp in RFC3339 format + defaultUser: + type: string + description: The default user to use for operations + defaultWorkdir: + type: string + description: The default working directory to use for operations + responses: + '204': + description: Env vars set, the time and metadata is synced with the host + tags: + - Sandbox + /files: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + get: + summary: Download a file + tags: + - Sandbox Files + security: + - AccessTokenAuth: [] + parameters: + - $ref: '#/components/parameters/SandboxFilePath' + - $ref: '#/components/parameters/SandboxUser' + - $ref: '#/components/parameters/SandboxSignature' + - $ref: '#/components/parameters/SandboxSignatureExpiration' + responses: + '200': + $ref: '#/components/responses/SandboxDownloadSuccess' + '400': + $ref: '#/components/responses/SandboxInvalidPath' + '401': + $ref: '#/components/responses/SandboxInvalidUser' + '404': + $ref: '#/components/responses/SandboxFileNotFound' + '500': + $ref: '#/components/responses/SandboxInternalServerError' + post: + summary: Upload a file and ensure the parent directories exist. If the file exists, it will be overwritten. + tags: + - Sandbox Files + security: + - AccessTokenAuth: [] + parameters: + - $ref: '#/components/parameters/SandboxFilePath' + - $ref: '#/components/parameters/SandboxUser' + - $ref: '#/components/parameters/SandboxSignature' + - $ref: '#/components/parameters/SandboxSignatureExpiration' + requestBody: + $ref: '#/components/requestBodies/SandboxFile' + responses: + '200': + $ref: '#/components/responses/SandboxUploadSuccess' + '400': + $ref: '#/components/responses/SandboxInvalidPath' + '401': + $ref: '#/components/responses/SandboxInvalidUser' + '500': + $ref: '#/components/responses/SandboxInternalServerError' + '507': + $ref: '#/components/responses/SandboxNotEnoughDiskSpace' + /filesystem.Filesystem/CreateWatcher: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: CreateWatcher + description: Non-streaming versions of WatchDir + operationId: filesystem.Filesystem.CreateWatcher + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.CreateWatcherRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.CreateWatcherResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /filesystem.Filesystem/GetWatcherEvents: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: GetWatcherEvents + operationId: filesystem.Filesystem.GetWatcherEvents + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.GetWatcherEventsRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.GetWatcherEventsResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /filesystem.Filesystem/ListDir: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: ListDir + operationId: filesystem.Filesystem.ListDir + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.ListDirRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.ListDirResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /filesystem.Filesystem/MakeDir: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: MakeDir + operationId: filesystem.Filesystem.MakeDir + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.MakeDirRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.MakeDirResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /filesystem.Filesystem/Move: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: Move + operationId: filesystem.Filesystem.Move + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.MoveRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.MoveResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /filesystem.Filesystem/Remove: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: Remove + operationId: filesystem.Filesystem.Remove + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.RemoveRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.RemoveResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /filesystem.Filesystem/RemoveWatcher: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: RemoveWatcher + operationId: filesystem.Filesystem.RemoveWatcher + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.RemoveWatcherRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.RemoveWatcherResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /filesystem.Filesystem/Stat: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: Stat + operationId: filesystem.Filesystem.Stat + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.StatRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.StatResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /filesystem.Filesystem/WatchDir: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Filesystem + summary: WatchDir + operationId: filesystem.Filesystem.WatchDir + parameters: [] + requestBody: + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirRequest' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirRequest' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirRequest' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirRequest' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirRequest' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirRequest' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirRequest' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirRequest' + required: true + responses: + '200': + description: Success + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxfilesystem.WatchDirResponse' + default: + description: Error + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + security: + - AccessTokenAuth: [] + /process.Process/Connect: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Process + summary: Connect + operationId: process.Process.Connect + parameters: [] + requestBody: + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectRequest' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectRequest' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectRequest' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectRequest' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectRequest' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectRequest' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectRequest' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectRequest' + required: true + responses: + '200': + description: Success + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectResponse' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectResponse' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectResponse' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectResponse' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectResponse' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectResponse' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectResponse' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.ConnectResponse' + default: + description: Error + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + security: + - AccessTokenAuth: [] + /process.Process/List: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Process + summary: List + operationId: process.Process.List + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxprocess.ListRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxprocess.ListResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /process.Process/SendInput: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Process + summary: SendInput + operationId: process.Process.SendInput + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxprocess.SendInputRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxprocess.SendInputResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /process.Process/SendSignal: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Process + summary: SendSignal + operationId: process.Process.SendSignal + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxprocess.SendSignalRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxprocess.SendSignalResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] + /process.Process/Start: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Process + summary: Start + operationId: process.Process.Start + parameters: [] + requestBody: + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartRequest' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartRequest' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartRequest' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartRequest' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartRequest' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartRequest' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartRequest' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartRequest' + required: true + responses: + '200': + description: Success + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartResponse' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartResponse' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartResponse' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartResponse' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartResponse' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartResponse' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartResponse' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StartResponse' + default: + description: Error + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + security: + - AccessTokenAuth: [] + /process.Process/StreamInput: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Process + summary: StreamInput + description: Client input stream ensures ordering of messages + operationId: process.Process.StreamInput + parameters: [] + requestBody: + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputRequest' + required: true + responses: + '200': + description: Success + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputResponse' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputResponse' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputResponse' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputResponse' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputResponse' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputResponse' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputResponse' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxprocess.StreamInputResponse' + default: + description: Error + content: + application/connect+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/connect+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web+proto: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + application/grpc-web+json: + schema: + $ref: '#/components/schemas/Sandboxconnect.error' + security: + - AccessTokenAuth: [] + /process.Process/Update: + servers: + - url: https://{port}-{sandboxId}.e2b.app + description: Sandbox API + variables: + port: + default: '49982' + description: Port number for the sandbox API + sandboxId: + default: sandbox-id + description: Sandbox ID returned when creating a sandbox + post: + tags: + - Sandbox Process + summary: Update + operationId: process.Process.Update + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxprocess.UpdateRequest' + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Sandboxprocess.UpdateResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - AccessTokenAuth: [] diff --git a/package.json b/package.json new file mode 100644 index 00000000..1cdb7ee6 --- /dev/null +++ b/package.json @@ -0,0 +1,12 @@ +{ + "name": "e2b-docs", + "version": "1.0.0", + "private": true, + "description": "E2B Documentation", + "scripts": { + "sync-openapi": "node scripts/sync-openapi.js" + }, + "dependencies": { + "js-yaml": "^4.1.0" + } +} diff --git a/scripts/sync-openapi.js b/scripts/sync-openapi.js new file mode 100644 index 00000000..315d86f4 --- /dev/null +++ b/scripts/sync-openapi.js @@ -0,0 +1,569 @@ +#!/usr/bin/env node + +/** + * OpenAPI Spec Sync Script + * + * Fetches OpenAPI specs from e2b-dev/infra repository, transforms them + * for public documentation, and saves them to the docs repo. + * + * Usage: node scripts/sync-openapi.js + */ + +const fs = require('fs'); +const path = require('path'); +const { execSync } = require('child_process'); + +// Try to load js-yaml, install if not available +let yaml; +try { + yaml = require('js-yaml'); +} catch (e) { + console.log('Installing js-yaml...'); + execSync('npm install js-yaml', { stdio: 'inherit' }); + yaml = require('js-yaml'); +} + +const INFRA_RAW_BASE = 'https://raw.githubusercontent.com/e2b-dev/infra/main'; + +// === CONFIGURATION === + +const CONFIG = { + output: 'openapi-public.yml', + + // REST API configuration + restApi: { + source: `${INFRA_RAW_BASE}/spec/openapi.yml`, + excludePaths: [ + '/access-tokens', + '/access-tokens/{accessTokenID}', + '/admin/teams/{teamID}/sandboxes/kill', + '/api-keys', + '/api-keys/{apiKeyID}', + '/health', + '/nodes', + '/nodes/{nodeID}', + '/teams', + ], + removeSecuritySchemes: [ + 'Supabase1TokenAuth', + 'Supabase2TeamAuth', + 'AccessTokenAuth', + 'AdminTokenAuth', + ], + }, + + // Sandbox API configuration + sandboxApi: { + envdSource: `${INFRA_RAW_BASE}/packages/envd/spec/envd.yaml`, + filesystemProto: `${INFRA_RAW_BASE}/packages/envd/spec/filesystem/filesystem.proto`, + processProto: `${INFRA_RAW_BASE}/packages/envd/spec/process/process.proto`, + excludePaths: [ + '/metrics', + '/envs', + '/health' + ], + removeSchemas: [ + 'connect-protocol-version', + 'connect-timeout-header', + 'connect.error' + ], + removeHeaders: [ + 'Connect-Protocol-Version', + 'Connect-Timeout-Ms' + ], + // Tag renames for sandbox endpoints + tagRenames: { + 'filesystem.Filesystem': 'Sandbox Filesystem', + 'process.Process': 'Sandbox Process', + 'files': 'Sandbox Files' + } + }, + + info: { + title: 'E2B API', + description: `API for managing and interacting with E2B sandboxes. + +## REST API (api.e2b.app) +Endpoints for creating and managing sandboxes and templates. +- **Authentication**: \`X-API-Key\` header with your API key from the [E2B Dashboard](https://e2b.dev/dashboard?tab=keys) +- **Base URL**: \`https://api.e2b.app\` + +## Sandbox API ({sandboxID}.e2b.app) +Endpoints for interacting with files and processes inside a running sandbox. +- **Authentication**: \`X-Access-Token\` header with the access token received when creating a sandbox +- **Base URL**: \`https://{sandboxID}.e2b.app\` +` + } +}; + +// === UTILITY FUNCTIONS === + +async function fetchYaml(url) { + console.log(`Fetching: ${url}`); + const response = await fetch(url); + if (!response.ok) { + throw new Error(`Failed to fetch ${url}: ${response.status}`); + } + const text = await response.text(); + return yaml.load(text); +} + +async function fetchText(url) { + console.log(`Fetching: ${url}`); + const response = await fetch(url); + if (!response.ok) { + throw new Error(`Failed to fetch ${url}: ${response.status}`); + } + return response.text(); +} + +function saveYaml(filename, data) { + const outputPath = path.join(process.cwd(), filename); + fs.writeFileSync(outputPath, yaml.dump(data, { lineWidth: -1, noRefs: true })); + console.log(`Saved: ${outputPath}`); +} + +// === REST API PROCESSING === + +async function fetchRestApiSpec() { + console.log('\n=== Fetching REST API Spec ===\n'); + + const spec = await fetchYaml(CONFIG.restApi.source); + + // Filter out excluded paths AND endpoints that only use Supabase tokens + const filteredPaths = {}; + for (const [path, methods] of Object.entries(spec.paths || {})) { + if (CONFIG.restApi.excludePaths.includes(path)) { + continue; + } + + const filteredMethods = {}; + for (const [method, operation] of Object.entries(methods)) { + if (!operation.security && !operation.responses) { + filteredMethods[method] = operation; + continue; + } + + const hasApiKeyAuth = operation.security?.some(secObj => + Object.keys(secObj).includes('ApiKeyAuth') + ); + + if (hasApiKeyAuth || !operation.security) { + filteredMethods[method] = operation; + } + } + + if (Object.keys(filteredMethods).length > 0) { + filteredPaths[path] = filteredMethods; + } + } + spec.paths = filteredPaths; + console.log(`REST API: ${Object.keys(filteredPaths).length} endpoints`); + + // Keep only ApiKeyAuth security scheme + if (spec.components?.securitySchemes?.ApiKeyAuth) { + spec.components.securitySchemes = { + ApiKeyAuth: spec.components.securitySchemes.ApiKeyAuth + }; + } + + // Clean up security references + for (const [path, methods] of Object.entries(spec.paths || {})) { + for (const [method, operation] of Object.entries(methods)) { + if (operation.security) { + operation.security = operation.security.filter(secObj => { + const schemes = Object.keys(secObj); + return schemes.length === 0 || schemes.includes('ApiKeyAuth'); + }); + if (operation.security.length === 0) { + delete operation.security; + } + } + } + } + + return spec; +} + +// === SANDBOX API PROCESSING === + +async function fetchSandboxApiSpec() { + console.log('\n=== Fetching Sandbox API Spec ===\n'); + + const spec = await fetchYaml(CONFIG.sandboxApi.envdSource); + + // Fix security scheme + if (spec.components?.securitySchemes?.AccessTokenAuth) { + spec.components.securitySchemes.AccessTokenAuth = { + type: 'apiKey', + in: 'header', + name: 'X-Access-Token', + description: 'Access token received when creating a sandbox' + }; + } + + // Try to merge proto-based specs + try { + await mergeProtoSpecs(spec); + } catch (e) { + console.warn(`Warning: Could not generate proto specs: ${e.message}`); + } + + // Filter out internal endpoints + for (const excludePath of CONFIG.sandboxApi.excludePaths) { + if (spec.paths[excludePath]) { + delete spec.paths[excludePath]; + console.log(`Excluded: ${excludePath}`); + } + } + + // Rename tags to include "Sandbox" prefix + for (const [path, methods] of Object.entries(spec.paths || {})) { + for (const [method, operation] of Object.entries(methods)) { + if (operation.tags) { + operation.tags = operation.tags.map(tag => + CONFIG.sandboxApi.tagRenames[tag] || `Sandbox ${tag}` + ); + } else { + // Add default tag for untagged endpoints + operation.tags = ['Sandbox']; + } + } + } + + // Apply schema fixes + applySchemaFixes(spec); + + console.log(`Sandbox API: ${Object.keys(spec.paths || {}).length} endpoints`); + return spec; +} + +async function mergeProtoSpecs(spec) { + try { + execSync('which buf', { stdio: 'pipe' }); + execSync('which protoc-gen-connect-openapi', { stdio: 'pipe' }); + } catch (e) { + throw new Error('buf or protoc-gen-connect-openapi not installed'); + } + + const tempDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'openapi-')); + console.log(`Using temp directory: ${tempDir}`); + + try { + const filesystemProto = await fetchText(CONFIG.sandboxApi.filesystemProto); + const processProto = await fetchText(CONFIG.sandboxApi.processProto); + + fs.mkdirSync(path.join(tempDir, 'filesystem'), { recursive: true }); + fs.mkdirSync(path.join(tempDir, 'process'), { recursive: true }); + fs.writeFileSync(path.join(tempDir, 'filesystem', 'filesystem.proto'), filesystemProto); + fs.writeFileSync(path.join(tempDir, 'process', 'process.proto'), processProto); + + fs.writeFileSync(path.join(tempDir, 'buf.yaml'), 'version: v1\n'); + + const bufGenYaml = `version: v2 +plugins: + - local: protoc-gen-connect-openapi + out: . + opt: + - with-streaming +`; + fs.writeFileSync(path.join(tempDir, 'buf.gen.yaml'), bufGenYaml); + + console.log('Running buf generate...'); + execSync('buf generate', { cwd: tempDir, stdio: 'pipe' }); + + const filesystemSpecPath = path.join(tempDir, 'filesystem', 'filesystem.openapi.yaml'); + const processSpecPath = path.join(tempDir, 'process', 'process.openapi.yaml'); + + if (fs.existsSync(filesystemSpecPath)) { + const filesystemSpec = yaml.load(fs.readFileSync(filesystemSpecPath, 'utf8')); + mergeSpecPaths(spec, filesystemSpec, '/filesystem.'); + } + + if (fs.existsSync(processSpecPath)) { + const processSpec = yaml.load(fs.readFileSync(processSpecPath, 'utf8')); + mergeSpecPaths(spec, processSpec, '/process.'); + } + + console.log('Merged filesystem and process endpoints'); + + } finally { + fs.rmSync(tempDir, { recursive: true, force: true }); + } +} + +function mergeSpecPaths(target, source, pathPrefix) { + for (const [path, methods] of Object.entries(source.paths || {})) { + if (path.startsWith(pathPrefix)) { + target.paths[path] = methods; + } + } + + if (source.components?.schemas) { + target.components = target.components || {}; + target.components.schemas = target.components.schemas || {}; + Object.assign(target.components.schemas, source.components.schemas); + } +} + +function applySchemaFixes(spec) { + if (spec.components?.schemas) { + for (const schemaName of CONFIG.sandboxApi.removeSchemas) { + if (spec.components.schemas[schemaName]) { + delete spec.components.schemas[schemaName]; + } + } + fixInvalidTypeArrays(spec.components.schemas); + } + + for (const [path, methods] of Object.entries(spec.paths || {})) { + for (const [method, operation] of Object.entries(methods)) { + if (operation.parameters) { + operation.parameters = operation.parameters.filter(p => + !CONFIG.sandboxApi.removeHeaders.includes(p.name) + ); + } + + if (operation.responses) { + for (const [code, response] of Object.entries(operation.responses)) { + if (response.content?.['application/json']?.schema?.$ref === '#/components/schemas/connect.error') { + response.content['application/json'].schema.$ref = '#/components/schemas/Error'; + } + } + } + } + } +} + +function fixInvalidTypeArrays(schemas) { + for (const [name, schema] of Object.entries(schemas)) { + fixTypeArraysRecursive(schema); + } +} + +function fixTypeArraysRecursive(obj) { + if (!obj || typeof obj !== 'object') return; + + if (Array.isArray(obj.type)) { + const mainType = obj.type.find(t => t !== 'null') || obj.type[0]; + obj.type = mainType; + } + + if (obj.examples && !obj.example) { + obj.example = Array.isArray(obj.examples) ? obj.examples[0] : obj.examples; + delete obj.examples; + } + + if (Array.isArray(obj.oneOf)) { + const nullIndex = obj.oneOf.findIndex(item => item.type === 'null'); + if (nullIndex !== -1) { + obj.oneOf.splice(nullIndex, 1); + obj.nullable = true; + if (obj.oneOf.length === 1) { + const remaining = obj.oneOf[0]; + delete obj.oneOf; + Object.assign(obj, remaining); + } else if (obj.oneOf.length === 0) { + delete obj.oneOf; + } + } + } + + if (obj.properties) { + for (const prop of Object.values(obj.properties)) { + fixTypeArraysRecursive(prop); + } + } + + if (obj.items) { + fixTypeArraysRecursive(obj.items); + } + + if (obj.additionalProperties && typeof obj.additionalProperties === 'object') { + fixTypeArraysRecursive(obj.additionalProperties); + } + + for (const key of ['allOf', 'oneOf', 'anyOf']) { + if (Array.isArray(obj[key])) { + for (const item of obj[key]) { + fixTypeArraysRecursive(item); + } + } + } +} + +// === MERGE SPECS === + +function mergeSpecs(restSpec, sandboxSpec) { + console.log('\n=== Merging Specs ===\n'); + + // Start with REST API spec as base + const merged = restSpec; + + // Update info + merged.info.title = CONFIG.info.title; + merged.info.description = CONFIG.info.description; + + // Add AccessTokenAuth security scheme for sandbox endpoints + merged.components.securitySchemes.AccessTokenAuth = { + type: 'apiKey', + in: 'header', + name: 'X-Access-Token', + description: 'Access token received when creating a sandbox (for Sandbox API endpoints)' + }; + + // Track sandbox paths for ref updates + const sandboxPaths = new Set(Object.keys(sandboxSpec.paths || {})); + + // Sandbox API server (different host) + const sandboxServer = { + url: 'https://{port}-{sandboxId}.e2b.app', + description: 'Sandbox API', + variables: { + port: { + default: '49982', + description: 'Port number for the sandbox API' + }, + sandboxId: { + default: 'sandbox-id', + description: 'Sandbox ID returned when creating a sandbox' + } + } + }; + + // Merge sandbox paths with per-path server override + for (const [path, methods] of Object.entries(sandboxSpec.paths || {})) { + // Add server override for this path + merged.paths[path] = { + servers: [sandboxServer], + ...methods + }; + + // Update security to use AccessTokenAuth for sandbox endpoints + for (const [method, operation] of Object.entries(methods)) { + if (typeof operation === 'object' && operation !== null && !Array.isArray(operation)) { + operation.security = [{ AccessTokenAuth: [] }]; + } + } + } + + // Merge sandbox components (schemas, requestBodies, responses, parameters) + const componentTypes = ['schemas', 'requestBodies', 'responses', 'parameters']; + for (const componentType of componentTypes) { + if (sandboxSpec.components?.[componentType]) { + merged.components[componentType] = merged.components[componentType] || {}; + for (const [name, component] of Object.entries(sandboxSpec.components[componentType])) { + const prefixedName = `Sandbox${name}`; + merged.components[componentType][prefixedName] = component; + } + } + } + + // Update $ref references in sandbox paths and components + for (const [path, methods] of Object.entries(merged.paths)) { + if (sandboxPaths.has(path)) { + updateSchemaRefs(methods, 'Sandbox'); + } + } + // Also update refs within sandbox components themselves + for (const componentType of componentTypes) { + for (const [name, component] of Object.entries(merged.components[componentType] || {})) { + if (name.startsWith('Sandbox')) { + updateSchemaRefs(component, 'Sandbox'); + } + } + } + + // Add tags + merged.tags = [ + ...(merged.tags || []), + { name: 'Sandbox', description: 'Sandbox initialization' }, + { name: 'Sandbox Files', description: 'Upload and download files in sandbox' }, + { name: 'Sandbox Filesystem', description: 'Filesystem operations (list, create, move, delete)' }, + { name: 'Sandbox Process', description: 'Process management (start, stop, send input)' } + ]; + + const totalEndpoints = Object.keys(merged.paths).length; + console.log(`Total endpoints: ${totalEndpoints}`); + + return merged; +} + +function updateSchemaRefs(obj, prefix) { + if (!obj || typeof obj !== 'object') return; + + // Handle all component $ref types + if (obj.$ref && obj.$ref.startsWith('#/components/')) { + const match = obj.$ref.match(/^#\/components\/(\w+)\/(.+)$/); + if (match) { + const [, componentType, name] = match; + // Don't prefix common schemas that exist in REST API + if (!['Error'].includes(name)) { + obj.$ref = `#/components/${componentType}/${prefix}${name}`; + } + } + } + + for (const value of Object.values(obj)) { + if (typeof value === 'object') { + updateSchemaRefs(value, prefix); + } + } +} + +// === VALIDATION === + +function validateSpec(filename) { + try { + execSync(`mintlify openapi-check ${filename}`, { stdio: 'pipe' }); + console.log(`✓ ${filename} is valid`); + return true; + } catch (e) { + const output = e.stdout?.toString() || e.stderr?.toString() || e.message; + console.error(`✗ ${filename} validation failed:\n${output}`); + return false; + } +} + +// === MAIN === + +async function main() { + console.log('OpenAPI Spec Sync Script'); + console.log('========================\n'); + + try { + // Fetch both specs + const restSpec = await fetchRestApiSpec(); + const sandboxSpec = await fetchSandboxApiSpec(); + + // Merge into single spec + const merged = mergeSpecs(restSpec, sandboxSpec); + + // Save merged spec + saveYaml(CONFIG.output, merged); + + // Remove old sandbox spec if exists + const oldSandboxSpec = 'openapi-sandbox.yml'; + if (fs.existsSync(oldSandboxSpec)) { + fs.unlinkSync(oldSandboxSpec); + console.log(`Removed old: ${oldSandboxSpec}`); + } + + console.log('\n=== Validation ===\n'); + + try { + execSync('which mintlify', { stdio: 'pipe' }); + validateSpec(CONFIG.output); + } catch (e) { + console.log('mintlify CLI not available, skipping validation'); + } + + console.log('\n✓ Done!\n'); + + } catch (error) { + console.error(`\n✗ Error: ${error.message}\n`); + process.exit(1); + } +} + +main();