> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/api-integration/file-library-resumable-upload.md).

# File Library Resumable Upload API

Write files to the file library with chunked upload sessions, resume transfers from the server offset, verify integrity with SHA-256, and handle completion and cancellation.

When an integration needs to upload a large file, or continue a transfer after a network interruption, it can use the file library's upload sessions. This flow accepts files from **1 byte to 500 MiB (524,288,000 bytes)**. Regular direct uploads and direct version uploads keep their 10 MiB limit, so the 500 MiB limit on this page does not apply to them.

For example, a document integration service needs to store a large training manual in the file library. The service first computes the SHA-256 of the entire file, then creates a session and sends the file chunk by chunk. If the connection drops, it reads the progress back from the server, resumes from the returned offset, and finally asks the server to verify and complete the file.

## Prerequisites and Path <a href="#prerequisites-and-path" id="prerequisites-and-path"></a>

Authenticate with `Authorization: Api-Key <your API key>`. For how to obtain a key, see [Quickstart](https://docs.maiagent.ai/tech/en/api-integration/quickstart.md).

The organization must have the file library enabled, and the caller must be a verified member with file library permission and write access to the target space. The target must be a folder; you cannot upload directly to the space root. Folders synced from external sources, and their subfolders, are read-only targets and cannot be uploaded to either.

This page uses the following path as its base, referred to below as `{base}`:

```
/api/v1/file-library/folders/{folderId}/upload-sessions/
```

## Create or Retrieve a Session <a href="#create-session" id="create-session"></a>

Send a `POST` to `{base}` with JSON:

| Field             | Required | Description                                                                                                         |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `clientId`        | Yes      | A UUID generated by the client; reuse it when resuming the same upload                                              |
| `filename`        | Yes      | The file name. It must not contain a directory path, and its extension must be a format allowed by the file library |
| `sha256`          | Yes      | The SHA-256 of the entire file, as 64 lowercase hexadecimal characters                                              |
| `size`            | Yes      | The size of the entire file in bytes. Empty files are not accepted                                                  |
| `contentType`     | No       | MIME type. Defaults to an empty string                                                                              |
| `collisionPolicy` | No       | `ask` (default), `keep_both`, or `replace`                                                                          |
| `replaceFileId`   | No       | The file to replace when using `replace`                                                                            |

Allowed extensions are `pdf`, `doc`, `docx`, `ppt`, `pptx`, `xls`, `xlsx`, `csv`, `txt`, `md`, `json`, `html`, `png`, `jpg`, `jpeg`, `gif`, `webp`, `mp3`, `wav`, `m4a`, `mp4`, and `dxf`, case-insensitive. Files with no extension or an unsupported format are rejected.

The same user, folder, and `clientId` retrieve the existing session; the request is rejected if `filename`, `sha256`, `size`, or `contentType` differs from the original values. Both creation and retrieval return `201`.

The response contains `id`, `folderId`, `filename`, `sha256`, `size`, `offset`, `chunkSize`, `completed`, and `completedFileId`. `offset` is the byte offset of the next chunk to send; `chunkSize` is 2 MiB (2,097,152 bytes).

## Send and Resume <a href="#send-and-resume" id="send-and-resume"></a>

1. Send a `PATCH` to `{base}{sessionId}/` using `multipart/form-data`, with a non-negative integer `offset` and the binary file field `chunk`.
2. Each chunk must be larger than 0 and no larger than `chunkSize`; only the last chunk may be shorter than `chunkSize`. Send chunks in order: the offset must equal the server's current `offset`, and the total must not exceed the declared `size`.
3. Each successful call returns a `200` session. Use the returned `offset` to decide the next chunk. If you are unsure whether the previous chunk arrived, send a `GET` to `{base}{sessionId}/` to read the progress back.

A previously received chunk can be resent, but its offset must fall on a recorded chunk boundary, and its offset, size, and content SHA-256 must all match the original chunk; only then is the existing progress returned. Do not upload in parallel or out of order.

The server computes the hash of each chunk, so the PATCH does not need to include a chunk hash. A session is valid for 24 hours from creation; if it does not exist, belongs to someone else, or has expired, the server returns `404`.

## Complete and Cancel <a href="#complete-and-cancel" id="complete-and-cancel"></a>

After all bytes have been sent, send a `POST` to `{base}{sessionId}/complete/`. If no duplicate file name needs to be handled, you can send an empty JSON object `{}`. The server re-checks the offset, size, and SHA-256 of each chunk, then compares the SHA-256 of the entire file; the file is completed only if verification passes, and a successful call returns `201` with the file object.

Completion still re-checks name collisions, capacity, and versions, so sending every chunk does not mean the file is already complete:

* `ask` returns `409 duplicate_name` on a name collision, with `existingFileId` and `currentVersionNumber`.
* `keep_both` appends a numeric suffix to the file name.
* `replace` requires `replaceFileId`; at completion, also send `expectedVersionNumber` to avoid overwriting a version someone else has just updated. The completion request must again include `collisionPolicy: "replace"` and `replaceFileId`, and `expectedVersionNumber` must be the `currentVersionNumber` from the most recent read or `409` response: a positive integer if a version exists, or an explicit JSON `null` if there is no version yet. Do not omit it or guess the version number.

{% hint style="warning" %}
The collision policy used when creating a session is not stored in the session. If you choose `keep_both` or `replace`, the completion request must send that policy and the required fields again; if none is specified, `ask` is used again.
{% endhint %}

Calling complete again on an already completed session returns the originally completed file and does not create a second copy; if the original file has been deleted or is currently not visible, it returns `404`.

To cancel an incomplete session, send a `DELETE` to `{base}{sessionId}/`; success returns `204`. A completed session cannot be canceled. To handle a completed file, use the file management flow.

{% hint style="info" %}
This flow writes to the file library; it is not a conversation attachment upload. To hand a file to an Agent in a conversation, see [Conversation Attachment Upload and Download](https://docs.maiagent.ai/tech/en/api-integration/endpoint-behaviors/conversation-attachments.md).
{% endhint %}


---

# 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.maiagent.ai/tech/en/api-integration/file-library-resumable-upload.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.
