> ## Documentation Index > Fetch the complete documentation index at: https://e2b.manicule.dev/llms.txt > Use this file to discover all available pages before exploring further. > For every page in one file, fetch https://e2b.manicule.dev/llms-full.txt (large). > To search and read these docs as tools, connect the MCP server at https://e2b.manicule.dev/api/mcp. > Every agent surface: https://e2b.manicule.dev/.well-known/llms-manifest.json # Upload a file and ensure the parent directories exist. If the file exists, it will be overwritten. (/docs/api-reference/filesystem/upload-a-file-and-ensure-the-parent-directories-exist-if-the-file-exists-it-will-be-overwritten) Related: [Download a file](/docs/api-reference/filesystem/download-a-file.md), [CreateWatcher](/docs/api-reference/filesystem/createwatcher.md), [GetWatcherEvents](/docs/api-reference/filesystem/getwatcherevents.md), [ListDir](/docs/api-reference/filesystem/listdir.md), [MakeDir](/docs/api-reference/filesystem/makedir.md), [Move](/docs/api-reference/filesystem/move.md) # Upload a file and ensure the parent directories exist. If the file exists, it will be overwritten. `POST /files` > Any request header of the form `X-Metadata-: ` is persisted > as a user-defined extended attribute on the uploaded file. The > `X-Metadata-` prefix is stripped and the remaining header name is > lowercased to form the metadata key; the resulting map is returned on > `EntryInfo` lookups (e.g. `Stat`, `ListDir`). > > Each upload replaces the file's metadata with the keys provided in > that request: keys previously stored but absent from the new request > are removed, and an upload that sends no `X-Metadata-*` header clears > all existing metadata. > > Both keys and values must be printable US-ASCII (bytes `0x20`-`0x7E`) > and are rejected with HTTP 400 otherwise. Each key is capped at 246 > bytes (the Linux VFS xattr-name limit minus the namespace prefix), and > the combined size of all metadata on a file (keys plus values, with the > namespace prefix counted per key) is capped at 4096 bytes to stay within > the filesystem's per-inode xattr budget. Multiple files in a single > multipart upload receive the same metadata. If the same > `X-Metadata-` header is sent more than once, only the first > value is used. Base URL: `https://sandbox.{domain}` (`domain`: any value, default `e2b.app`) ## OpenAPI ```json { "servers": [ { "url": "https://sandbox.{domain}", "variables": { "domain": { "default": "e2b.app", "description": "E2B domain" } }, "description": "Sandbox API (envd) - runs inside each sandbox" } ], "security": [ { "SandboxAccessTokenAuth": [] } ], "securitySchemes": { "SandboxAccessTokenAuth": { "type": "apiKey", "in": "header", "name": "X-Access-Token", "description": "Sandbox access token (`envdAccessToken`) for authenticating requests to a running sandbox. Returned by: [POST /sandboxes](/docs/api-reference/sandboxes/create-a-sandbox) (on create), [POST /sandboxes/{sandboxID}/connect](/docs/api-reference/sandboxes/connect-to-a-sandbox) (on connect), [POST /sandboxes/{sandboxID}/resume](/docs/api-reference/sandboxes/resume-a-sandbox) (on resume), and [GET /sandboxes/{sandboxID}](/docs/api-reference/sandboxes/get-a-sandbox) (for running or paused sandboxes)." } }, "parameters": [ { "name": "E2b-Sandbox-Id", "in": "header", "required": true, "description": "Identifier of the target sandbox. Routes the request to that sandbox's envd over the shared sandbox host.", "schema": { "type": "string" } }, { "name": "E2b-Sandbox-Port", "in": "header", "required": true, "description": "Port envd listens on inside the sandbox (default 49983).", "schema": { "type": "integer", "default": 49983 } }, { "name": "path", "in": "query", "required": false, "description": "Path to the file, URL encoded. Can be relative to user's home directory.", "schema": { "type": "string" } }, { "name": "username", "in": "query", "required": false, "description": "User used for setting the owner, or resolving relative paths.", "schema": { "type": "string" } }, { "name": "signature", "in": "query", "required": false, "description": "Signature used for file access permission verification.", "schema": { "type": "string" } }, { "name": "signature_expiration", "in": "query", "required": false, "description": "Signature expiration used for defining the expiration time of the signature.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "The file was uploaded successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "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", "directory" ] }, "metadata": { "type": "object", "description": "User-defined metadata stored as extended attributes on the file.", "additionalProperties": { "type": "string" } } }, "type": "object" } } } } }, "400": { "description": "Invalid path", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "Error code" }, "message": { "type": "string", "description": "Error" } }, "type": "object" } } } }, "401": { "description": "Invalid user", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "Error code" }, "message": { "type": "string", "description": "Error" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "Error code" }, "message": { "type": "string", "description": "Error" } }, "type": "object" } } } }, "502": { "description": "Sandbox not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "sandboxID", "message", "code" ], "properties": { "message": { "type": "string", "description": "Error message" }, "code": { "type": "integer", "description": "Error code" }, "sandboxID": { "type": "string", "description": "Identifier of the sandbox" } } } } } }, "507": { "description": "Not enough disk space", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "Error code" }, "message": { "type": "string", "description": "Error" } }, "type": "object" } } } } } } ```