> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapengine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Session File

> Upload a file to the session's uploads directory. Reference it by filename in a later uploadFile task action.

## Overview

Uploads a file to the session's uploads directory. Files land in a private per-session staging area and can be referenced by `filename` in a subsequent `uploadFile` task action (for example, to attach a resume to a job application flow). Content is transported as base64 in JSON; maximum decoded size is 50 MiB.

## Path Parameters

<ParamField path="id" type="string" required={true}>
  Browser session ID (UUID).
</ParamField>

## Body

<ParamField body="filename" type="string" required={true}>
  File name (up to 255 characters). Must not contain path separators (`/`, `\`) and cannot be `.` or `..`.
</ParamField>

<ParamField body="file" type="string" required={true}>
  Base64-encoded file content. Decoded size must be 50 MiB or less.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7/files" \
    -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "filename": "resume.pdf",
      "file": "SGVsbG8gV29ybGQ="
    }'
  ```

  ```javascript JavaScript theme={null}
  import { readFile } from "node:fs/promises";

  const file = (await readFile("./resume.pdf")).toString("base64");
  const response = await fetch(
    "https://api.scrapengine.io/api/v1/browser/sessions/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7/files",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.SCRAPENGINE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ filename: "resume.pdf", file }),
    },
  );
  ```
</CodeGroup>

## Response

### Success Response (201)

<ResponseField name="filename" type="string">
  Filename stored in the session's uploads directory.
</ResponseField>

<ResponseField name="size" type="integer">
  Size in bytes of the stored file.
</ResponseField>

<ResponseField name="uploadedAt" type="string">
  ISO 8601 timestamp of when the upload was persisted.
</ResponseField>

**Example Response:**

```json theme={null}
{
  "filename": "resume.pdf",
  "size": 20813,
  "uploadedAt": "2026-04-24T09:12:44Z"
}
```

### Error Responses

| Status | Description                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid body — missing `filename`/`file`, filename contains path separators, or `file` is not valid base64. |
| `401`  | Unauthorized — invalid or missing API key.                                                                  |
| `404`  | Session not found or not owned by the caller.                                                               |
| `413`  | Decoded file exceeds the 50 MiB maximum.                                                                    |