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 or 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.

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:

   dd if="<path>" bs=1048576 skip=$(( (<N>-1) * <partSize> / 1048576 )) count=$(( <partSize> / 1048576 )) 2>/dev/null | curl -fS -X PUT -H "Transfer-Encoding:" -H "Content-Length: <contentLength>" -T - "<url>"

   Replace <N>, <partSize>, <contentLength> and <url> 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.

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 <your-tarkle-key>, as shown in Coding assistants. Keys are created and managed in API keys.

Related pages

• MCP tools lists the tools and what each one asks for.
• Authorization and security explains how sign-in and keys are checked.
• Troubleshooting covers upload errors and what to do about them.
• Uploads describes the upload calls of the REST API.