--- title: "Uploads and file size" description: "How an AI assistant uploads a file through the MCP server: the tool for each kind of file, parts for large files, and the size limits." --- > Documentation Index > Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Uploads and file size An AI assistant that uses the MCP server can put a file into a workspace in four ways. This page explains which tool to use, how a large file travels in parts, the size limit for each kind of assistant, and a worked example of a 10 GiB upload. Connect the assistant first with [Coding assistants](/docs/mcp/connect/coding-assistants) or [Chat assistants](/docs/mcp/connect/chat-assistants). ## Choose the upload tool Pick the tool by where the file is. Upload tools that save a file return a `fileId`, and `tarkle_create_transfer` takes that `fileId` to create a public link. | The file is | Tool | Largest file | | --- | --- | --- | | Text the assistant holds, such as a report, notes, CSV or JSON | `tarkle_upload_text` | 3 MB of text | | At a public https address, or attached in ChatGPT | `tarkle_upload_from_url` | Up to 50 MB | | On a disk the assistant can read, and the assistant can run shell commands | `tarkle_start_upload` | see [Size limits by assistant](#size-limits-by-assistant) | | On the person's device, or a chat attachment the assistant cannot read | `tarkle_get_upload_page` | see [Size limits by assistant](#size-limits-by-assistant) | `tarkle_upload_text` saves the text as the file. Its content goes in the call itself, up to 3 MB of text. Tarkle downloads the file for `tarkle_upload_from_url`. Use it when the assistant has a link to the file but no disk or shell. Tarkle fetches a file from an address of up to 50 MB. Only https addresses can be fetched. The address must be reachable without a sign-in. A file attached in ChatGPT is passed the same way. Plan limits apply to all four tools. An organization on Free accepts files up to 1 GB each, and Pro and Agency accept files up to 200 GB each. ## Send a file with tarkle_start_upload Use `tarkle_start_upload` for a file on disk when the assistant can run shell commands. The bytes go straight to Tarkle storage through signed addresses, not through the chat. 1. **Start the upload.** Call `tarkle_start_upload` with `workspaceId`, `fileName` and `sizeBytes`, the size in bytes. Add `folderId` to save the file in a folder from `tarkle_list_folders`. Omit it for the library root. The answer has a `sessionId`, the number of parts and the signed addresses in `uploads`. 2. **Send each part.** Send the bytes with HTTP PUT to the signed address, with no `Authorization` header. A file that is one part is one PUT of the whole file to `uploads[0].url`. Otherwise each part N goes to `uploads[N-1].url`, with the exact length in `uploads[N-1].contentLength`. Parts can run in parallel and be retried. For one part of a file on disk, this shell command reads that part and sends it: ```bash dd if="" bs=1048576 skip=$(( (-1) * / 1048576 )) count=$(( / 1048576 )) 2>/dev/null | curl -fS -X PUT -H "Transfer-Encoding:" -H "Content-Length: " -T - "" ``` Replace ``, ``, `` and `` with the values for that part. The empty `Transfer-Encoding` header is required: without it curl sends chunked encoding together with `Content-Length`, and storage answers 400. 3. **Check the upload.** Call `tarkle_get_upload_status` with the `sessionId` until it reports Upload complete and gives a `fileId`. Once all bytes are uploaded this finishes the upload and returns fileId. The call is safe to repeat. 4. **Share it.** Call `tarkle_create_transfer` with that `fileId`. It asks for confirmation first, so the person approves the link before it is created. ## How parts are sized A file up to 100 MiB goes with one address, in one PUT. A file above 100 MiB and up to 1 GiB also goes with one address. It is sent as a single part of a multipart upload. A file above 1 GiB is split into parts of 512 MiB (536,870,912 bytes), each with its own address. The last part can be smaller. The first answer lists up to 20 addresses. For more parts, call `tarkle_get_upload_parts` with the `sessionId`, the first part to sign as `fromPart`, and `count` (50 by default, up to 100). Signed addresses expire after one hour. If an address expires before its part is sent, call `tarkle_get_upload_parts` for that part number and send the part to the new address. ## Worked example: a 10 GiB file from a coding assistant This example assumes the file is on the computer where the coding assistant runs, the organization is on Pro or Agency, and the assistant uses an API key that reaches the workspace. On Free, the start is refused because the file is larger than 1 GB. How long the parts take depends on the connection between the computer and Tarkle. 10 GiB is 10,737,418,240 bytes. At 512 MiB per part, the file has 20 parts, each 536,870,912 bytes, with no smaller last part. 1. Call `tarkle_start_upload` with `sizeBytes` set to `10737418240`. The answer is a multipart upload of 20 parts. It lists all 20 addresses, because the first answer lists up to 20 addresses. 2. Send parts 1 to 20 with the shell command above. For part N the command uses `bs=1048576`, skips (N-1) × 512 blocks and copies 512 blocks. Send each part with `Content-Length: 536870912` and the matching address from `uploads`. 3. If an address expires before its part is sent, for example parts 16 to 20 after an hour, call `tarkle_get_upload_parts` with the `sessionId`, `fromPart` set to 16 and `count` set to 5. Then send those parts to the new addresses. 4. Call `tarkle_get_upload_status` until it reports Upload complete and gives the `fileId`. 5. Call `tarkle_create_transfer` with that `fileId`, and approve the link when the assistant asks. ## Size limits by assistant Tarkle sets the largest file an assistant may send from how the assistant signed in. The plan limit applies on top in every case, so a Free organization stays at 1 GB even from an assistant on the person's computer. | Assistant | Largest file through the MCP server | | --- | --- | | An assistant on the person's computer: any client that uses an API key, or a browser sign-in whose app registers a local address or an app scheme | The plan's per-file limit: Free 1 GB, Pro and Agency 200 GB | | A hosted chat app such as ChatGPT, which connects by browser sign-in with a web address | 5 GiB (5,368,709,120 bytes) | | Unknown (the sign-in does not say) | 5 GiB (5,368,709,120 bytes) | An assistant that uses an API key counts as one on the person's computer. Exactly 5 GiB is allowed in a chat app, and a file one byte larger is refused. Above that limit, `tarkle_start_upload` refuses the file and points to `tarkle_get_upload_page`. ## Browser upload page Use `tarkle_get_upload_page` when the assistant cannot read the file, for example a chat attachment or a file on the person's device. The tool returns a link to a page in Tarkle, and the assistant gives that link to the person. If the person is not signed in, the page asks them to sign in first. If they have more than one workspace, they choose one. Choose files from this device. Each finished file is marked Uploaded. Then ask the person to tell the assistant the upload is done. The assistant finds the file with `tarkle_list_files` and creates a link with `tarkle_create_transfer`. ## Keys limited to some workspaces A key limited to chosen workspaces reaches only those workspaces. A call that names another workspace fails with Workspace not found. Such a key also cannot create a workspace through the MCP server. Send the key as `Authorization: Bearer `, as shown in [Coding assistants](/docs/mcp/connect/coding-assistants). Keys are created and managed in [API keys](/docs/get-started/api-keys). ## Related pages - [MCP tools](/docs/mcp/tools) lists the tools and what each one asks for. - [Authorization and security](/docs/mcp/authorization) explains how sign-in and keys are checked. - [Troubleshooting](/docs/mcp/troubleshooting) covers upload errors and what to do about them. - [Uploads](/docs/api/uploads) describes the upload calls of the REST API. Source: https://tarkle.com/docs/mcp/uploads/index.mdx