> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Orientation for file operations: listing, upload, download, update, move, copy, delete, restore, and versions.

Files are the objects you store. This page orients you across the file operations and points to the detailed guides.

## Operations

| Operation | Method and path | Required scopes |
| - | - | - |
| List files in a bucket | `GET /files/findAll/{bucketId}` | `buckets:read` + `files:read` |
| List deleted files in a bucket | `GET /files/deleted-files/{bucketId}` | `buckets:read` + `files:read` |
| Upload to bucket root | `POST /files/upload/{bucketId}` | `buckets:write` + `files:write` |
| Upload to a folder | `POST /files/upload/{bucketId}/{folderId}` | `buckets:write` + `files:write` |
| Stream download | `GET /files/{fileId}/stream` | `buckets:read` + `files:read` |
| Update metadata or retention | `PUT /files/update/{fileId}` | `buckets:write` + `files:write` |
| Move | `POST /files/move/{fileId}` | `buckets:write` + `files:write` |
| Copy | `POST /files/copy/{fileId}` | `buckets:write` + `files:write` |
| Delete | `DELETE /files/delete/{fileId}` | `buckets:write` + `files:delete` |
| Restore from trash | `POST /files/{fileId}/restore` | `buckets:write` + `files:write` |
| List versions | `GET /files/{fileId}/versions` | `buckets:read` + `files:read` |
| Restore a version | `POST /files/{fileId}/versions/{versionId}/restore` | `buckets:write` + `files:write` |
| Delete a version | `DELETE /files/{fileId}/versions/{versionId}` | `buckets:write` + `files:delete` |
| Download a version | `GET /files/{fileId}/versions/{versionId}/download` | `buckets:read` + `files:read` |

Every listing is scoped to a `bucketId`. There is no documented cross-bucket or company-wide file listing.

## What to know first

1. **Uploads return `200`, not `201`.**
2. **Multi-file uploads return only the first file's result.** List the folder afterward.
3. **File delete returns `data: ""`.** That is a success.
4. **Version list, restore, and delete operations return HTTP `200` with a nested status.**
5. **`name` excludes the extension; `extFile` holds it.**
6. **Soft delete keeps bytes and remains billable until purge.**

## File details is not available to API keys

`GET /files/details/{fileId}` is a session-only route. A key cannot call it, and it is not part of this reference. Use the list operations instead.

## Guides

> **[Upload files](https://docs.everabyte.com/storage/upload-files.md)**
>
> Multipart behavior, limits, and prerequisites.

> **[Download files](https://docs.everabyte.com/storage/download-files.md)**
>
> Streaming and range requests.

> **[Manage file lifecycle](https://docs.everabyte.com/storage/manage-file-lifecycle.md)**
>
> Update, move, copy, delete, and restore.

> **[Versions and restore](https://docs.everabyte.com/storage/versions-and-restore.md)**
>
> Version listing and nested status semantics.

## Common patterns

### Enumerate everything in a bucket

```text theme={null}
GET /folders/findAll/{bucketId}          -> folder tree
GET /folders/{folderId}/content          -> paginated contents per folder
```

Use folder content rather than a global file list when you need structure.

### Find a file by name

Use `searchTerm` on the file list, then verify `name` and `extFile` exactly. Names are not unique.

### Replace a file's contents

Prefer uploading a new version through the upload route with the same name in the same folder scope, or update the file explicitly. Do not delete and re-upload unless you intend to lose the version lineage.

## Related

> **[Conventions](https://docs.everabyte.com/api-reference/conventions.md)**
>
> Envelopes and identifiers.

> **[Pagination](https://docs.everabyte.com/api-reference/pagination.md)**
>
> List shape.

> **[Errors](https://docs.everabyte.com/api-reference/errors.md)**
>
> Failure handling.

> **[Limits and quotas](https://docs.everabyte.com/concepts/limits-and-quotas.md)**
>
> Size and rate limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.