# 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)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 1862 · updated: 2026-07-30 -->
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-<key>: <value>` 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-<key>` header is sent more than once, only the first
value is used.


## OpenAPI

```json
{
  "security": [
    {
      "SandboxAccessTokenAuth": []
    }
  ],
  "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"
          }
        }
      }
    }
  }
}
```