> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/stackai-mcp/workflow-recipes/upload-a-larger-document.md).

# Upload a larger document

Upload a local file and obtain a temporary URL that a workflow can read. This route avoids sending the file's base64 contents inside an MCP request.

## Before you start

Your client must be able to read the local file and make an HTTP PUT request. MCP tool access alone does not provide that capability. The maximum file size is 100 MiB. For small files, [files\_upload](https://docs.stackai.com/stackai-mcp/tool-reference/file-uploads/files-upload.md) can send base64 contents directly.

If your chat client cannot read or upload bytes, use an authorized client with file and HTTP access. To run the workflow through the StackAI interface instead, open its interface, attach the file to its document input, and submit there; this is an alternative run path, not a way to obtain an MCP upload URL.

## Calculate the file size and hash

Run this locally, replacing the file path:

```python
import base64
import hashlib
import json
from pathlib import Path

path = Path("document.pdf")
content = path.read_bytes()
arguments = {
    "filename": path.name,
    "byte_length": len(content),
    "content_hash": base64.b64encode(hashlib.sha256(content).digest()).decode(),
    "mime_type": "application/pdf",
}
print(json.dumps(arguments, indent=2))
```

The hash must be base64 of the SHA-256 digest, not hexadecimal. Calculate it from the exact bytes you will upload.

## Request an upload URL

Pass the printed object to **`files_create_upload_url`**. Keep the returned `file_id`, `upload_url`, and `upload_token`. The response also gives an expiry and a `next_step` instruction.

## Upload the bytes

Make an HTTP PUT to `upload_url`. Set `Authorization: Bearer <upload_token>` and the file's content type, and send the original bytes as the body. Do not send base64 in this PUT.

The following Python example reads the URL and token privately at the terminal so they do not need to appear in a shell command or chat message:

```python
import getpass
import urllib.request
from pathlib import Path

content = Path("document.pdf").read_bytes()
url = getpass.getpass("Upload URL: ")
token = getpass.getpass("Upload token: ")
request = urllib.request.Request(
    url,
    data=content,
    method="PUT",
    headers={
        "Authorization": "Bearer " + token,
        "Content-Type": "application/pdf",
    },
)
with urllib.request.urlopen(request) as response:
    print("Upload status:", response.status)
```

Continue only after a successful 2xx response. This PUT is a client HTTP action, not another MCP tool.

## Finalize and run

Call **`files_finalize_upload`** with the same `file_id`. Save its `signed_url`, then pass it in an array under the workflow's actual document-input ID when calling `projects_run`.

If finalization reports `file_not_in_storage`, the upload is not complete. `file_already_uploaded` means it was finalized previously. Keep temporary URLs and tokens out of shared prompts, screenshots, and reports.

## Tool reference

* [files\_upload](https://docs.stackai.com/stackai-mcp/tool-reference/file-uploads/files-upload.md)
* [files\_create\_upload\_url](https://docs.stackai.com/stackai-mcp/tool-reference/file-uploads/files-create-upload-url.md)
* [files\_finalize\_upload](https://docs.stackai.com/stackai-mcp/tool-reference/file-uploads/files-finalize-upload.md)
* [projects\_run](https://docs.stackai.com/stackai-mcp/tool-reference/projects-and-workflow-authoring/projects-run.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/stackai-mcp/workflow-recipes/upload-a-larger-document.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
