# ShareWith

> Self-hosted file manager with a REST API. It stores files on the server's own
> disks and can mount remote storage (FTP, FTPS, SFTP and Google Drive) so that
> everything is browsable, searchable and transferable through one interface.

Authentication: every /api/v1 request needs an `X-API-Key` header. Keys are created
by a signed-in user from the API panel and can be scoped to a single folder.

All responses are JSON shaped as `{"success": true, "data": ...}` or
`{"success": false, "error": "..."}`.

Paths: a `path` may start at the caller's own root, or with `__adm_<id>/` for a
server folder an administrator shared with them, or `__conn_<id>/` for a mounted
FTP/SFTP/Google Drive connector. GET /api/v1/locations lists all of them with the
prefix to use. Shared folders may be read-only, in which case writes return 403.

## Machine-readable docs

- [OpenAPI 3.1 document](https://sharewith.xyz/api/openapi.json): complete request/response schema
- [Markdown reference](https://sharewith.xyz/api/docs.md): the same reference as prose
- [Human docs](https://sharewith.xyz/api/docs): browsable version with copyable examples

## Capabilities

- List, read, upload, download, rename, move and delete files and folders
- Create folders and empty files
- Inspect a single item with `/api/v1/files/info`
- Read the calling account with `/api/v1/account`
- Manage API keys with `/api/v1/keys`

## Limits

- Uploads up to 10 GB per file
- Downloads support HTTP range requests, so transfers can be resumed
- A folder-scoped key can never read outside its folder