> For the complete documentation index, see [llms.txt](https://docs.quicksync.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.quicksync.me/qs-framework/upload-api.md).

# Upload API

This page provides comprehensive documentation for the Upload API, which offers a simplified interface for uploading and managing content on IPFS (InterPlanetary File System) storage. Inspired by the widely adopted S3 API, this interface aims to provide a familiar experience for developers while leveraging the benefits of decentralized storage. By abstracting the underlying complexity of IPFS, the API allows for seamless integration into existing workflows with minimal learning curve.

{% hint style="warning" %}
This API is currently under active development and may be subject to changes. We recommend reviewing the documentation regularly and subscribing to updates to stay informed about any modifications, deprecations, or new features that may affect your integration.
{% endhint %}

{% hint style="info" %}
The maximum upload size and related limitations are governed by the rules defined for each session
{% endhint %}

## Retrieve all files in the user's storage bucket

> Returns a list of files currently stored in the authenticated user's bucket. Useful for listing uploaded content.

```json
{"openapi":"3.0.1","info":{"title":"Session API","version":"1.1.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"UploadInfoDto":{"type":"object","properties":{"creatorId":{"type":"string","nullable":true},"completed":{"type":"boolean"},"fileKey":{"type":"string","nullable":true},"fileName":{"type":"string","nullable":true},"totalParts":{"type":"integer","format":"int32"},"originalSizeInBytes":{"type":"integer","format":"int64"}},"additionalProperties":false}}},"paths":{"/buckets":{"get":{"tags":["Buckets"],"summary":"Retrieve all files in the user's storage bucket","description":"Returns a list of files currently stored in the authenticated user's bucket. Useful for listing uploaded content.","responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UploadInfoDto"}}},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UploadInfoDto"}}},"text/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UploadInfoDto"}}}}}}}}}}
```

## Start a new file upload

> Initiates a multipart upload request to the user's storage bucket. Returns necessary upload details including an uploadId. For using with QS Share, encryptedName should be encrypted using AES256 with the session ID as key

```json
{"openapi":"3.0.1","info":{"title":"Session API","version":"1.1.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"InitiateUploadRequest":{"type":"object","properties":{"totalParts":{"type":"integer","format":"int32"},"encryptedName":{"type":"string","nullable":true},"originalSizeInBytes":{"type":"integer","format":"int64"}},"additionalProperties":false},"InitiateUploadResponse":{"type":"object","properties":{"uploadId":{"type":"string","nullable":true},"fileKey":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/buckets":{"post":{"tags":["Buckets"],"summary":"Start a new file upload","description":"Initiates a multipart upload request to the user's storage bucket. Returns necessary upload details including an uploadId. For using with QS Share, encryptedName should be encrypted using AES256 with the session ID as key","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateUploadRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/InitiateUploadRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/InitiateUploadRequest"}}}},"responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/InitiateUploadResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/InitiateUploadResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/InitiateUploadResponse"}}}}}}}}}
```

## Upload a file part for multipart upload

> Uploads a specific part of a file during a multipart upload. Requires uploadId, partNumber, and key to identify the upload session and part.

```json
{"openapi":"3.0.1","info":{"title":"Session API","version":"1.1.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[],"Wallet Ownership Bearer":[],"API Key":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"UploadPartResponse":{"type":"object","properties":{"tag":{"type":"string","nullable":true},"partNumber":{"type":"integer","format":"int32"}},"additionalProperties":false}}},"paths":{"/buckets":{"put":{"tags":["Buckets"],"parameters":[{"name":"partNumber","in":"header","style":"simple","schema":{"type":"integer","format":"int32"}},{"name":"key","in":"header","style":"simple","schema":{"type":"string"}},{"name":"uploadId","in":"header","style":"simple","schema":{"type":"string"}}],"summary":"Upload a file part for multipart upload","description":"Uploads a specific part of a file during a multipart upload. Requires uploadId, partNumber, and key to identify the upload session and part.","responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/UploadPartResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/UploadPartResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/UploadPartResponse"}}}}}}}}}
```

## Finalize a multipart file upload.

> Completes a multipart file upload by combining previously uploaded parts. Requires the uploadId and associated metadata to finalize the upload.

```json
{"openapi":"3.0.1","info":{"title":"Session API","version":"1.1.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"CompleteUploadRequest":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"nullable":true},"key":{"type":"string","nullable":true}},"additionalProperties":false},"InitiateUploadInfoDto":{"type":"object","properties":{"uploadId":{"type":"string","nullable":true},"fileKey":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/buckets/complete":{"post":{"tags":["Buckets"],"summary":"Finalize a multipart file upload.","description":"Completes a multipart file upload by combining previously uploaded parts. Requires the uploadId and associated metadata to finalize the upload.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteUploadRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/CompleteUploadRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CompleteUploadRequest"}}}},"responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/InitiateUploadInfoDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/InitiateUploadInfoDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/InitiateUploadInfoDto"}}}}}}}}}
```

## Remove a file from the bucket

> Permanently deletes a file from the user's storage bucket using its unique fileId.

```json
{"openapi":"3.0.1","info":{"title":"Session API","version":"1.1.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}}},"paths":{"/buckets/{fileId}":{"delete":{"tags":["Buckets"],"summary":"Remove a file from the bucket","description":"Permanently deletes a file from the user's storage bucket using its unique fileId.","parameters":[{"name":"fileId","in":"path","required":true,"style":"simple","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}}}}
```

## Get metadata for a specific file.

> Retrieves detailed metadata about a single file using its fileId, such as file size, name, upload status, and more.

```json
{"openapi":"3.0.1","info":{"title":"Session API","version":"1.1.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"UploadInfoDto":{"type":"object","properties":{"creatorId":{"type":"string","nullable":true},"completed":{"type":"boolean"},"fileKey":{"type":"string","nullable":true},"fileName":{"type":"string","nullable":true},"totalParts":{"type":"integer","format":"int32"},"originalSizeInBytes":{"type":"integer","format":"int64"}},"additionalProperties":false}}},"paths":{"/buckets/file/{fileId}":{"get":{"tags":["Buckets"],"parameters":[{"name":"fileId","in":"path","required":true,"style":"simple","schema":{"type":"string"}}],"summary":"Get metadata for a specific file.","description":"Retrieves detailed metadata about a single file using its fileId, such as file size, name, upload status, and more.","responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/UploadInfoDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/UploadInfoDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/UploadInfoDto"}}}}}}}}}
```

## Get a downloadable link for a file.

> Generates a temporary pre-signed download URL for the specified file.

```json
{"openapi":"3.0.1","info":{"title":"Session API","version":"1.1.0"},"servers":[{"url":"https://api.quicksync.me/v1"}],"security":[{"Session Bearer":[]}],"components":{"securitySchemes":{"Session Bearer":{"type":"http","scheme":"bearer","in":"header","description":"Bearer schema token issued by session credentials"}},"schemas":{"DownloadResponse":{"type":"object","properties":{"url":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/buckets/download/{fileId}":{"get":{"tags":["Buckets"],"summary":"Get a downloadable link for a file.","description":"Generates a temporary pre-signed download URL for the specified file.","parameters":[{"name":"fileId","in":"path","required":true,"style":"simple","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/DownloadResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/DownloadResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/DownloadResponse"}}}}}}}}}
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.quicksync.me/qs-framework/upload-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.