# ShareWith API

Read and write files on a ShareWith server over HTTP.

- Base URL: `https://sharewith.xyz`
- OpenAPI: `https://sharewith.xyz/api/openapi.json`
- Every request needs the header `X-API-Key: <your key>`
- Responses are `{"success":true,"data":…}` or `{"success":false,"error":"…"}`
- Paths are relative to the key's root. `..` is rejected; a folder-scoped key cannot read outside its folder.

## Quick start

```bash
curl -H "X-API-Key: $KEY" "https://sharewith.xyz/api/v1/files?path="
curl -H "X-API-Key: $KEY" -F "file=@report.pdf" "https://sharewith.xyz/api/v1/files/upload?path=docs"
curl -H "X-API-Key: $KEY" -o report.pdf "https://sharewith.xyz/api/v1/files/download?path=docs/report.pdf"
```

## Endpoints

### GET /api/v1/locations

List every reachable location. Returns the caller's own files plus each shared folder and mounted connector, with the virtual path prefix to use for it. Start here rather than guessing mount ids.

### GET /api/v1/files

List a folder. Returns the folders and files directly inside `path`. Folders come first. Listing the root also returns shared folders and connector mounts, each flagged with `mount`. A path may start at the caller's own root, or with "__adm_<id>/" for a folder an administrator shared with them, or "__conn_<id>/" for a mounted FTP/SFTP/Google Drive connector. Call /api/v1/locations to discover the ids.

| Parameter | In | Required | Description |
|---|---|---|---|
| `path` | query | no | Folder to list. Omit for the root. A path may start at the caller's own root, or with "__adm_<id>/" for a folder an administrator shared with them, or "__conn_<id>/" for a mounted FTP/SFTP/Google Drive connector. Call /api/v1/locations to discover the ids. |

### GET /api/v1/files/download

Download a file. Streams the file. Supports `Range` requests, so large downloads can be resumed.

| Parameter | In | Required | Description |
|---|---|---|---|
| `path` | query | yes | File to download. |

### POST /api/v1/files/upload

Upload a file. Send the file as multipart/form-data in a field named `file`. An existing file with the same name is overwritten.

| Parameter | In | Required | Description |
|---|---|---|---|
| `path` | query | no | Destination folder. Omit for the root. |

Body: `multipart/form-data` with a `file` field.

### POST /api/v1/files/folder

Create a folder. Creates a folder, including any missing parents.

| Parameter | In | Required | Description |
|---|---|---|---|
| `path` | query | no | Parent folder. |
| `name` | query | yes | Name of the new folder. |

### POST /api/v1/files/file

Create an empty file. Creates a zero-byte file. Does nothing if the name is taken.

| Parameter | In | Required | Description |
|---|---|---|---|
| `path` | query | no | Parent folder. |
| `name` | query | yes | Name of the new file. |

### PUT /api/v1/files/move

Move a file or folder. Moves an item into another folder. Source and destination may be on different backends (own files, shared folder, FTP/Drive mount); the content is streamed across.

| Parameter | In | Required | Description |
|---|---|---|---|
| `from` | query | yes | Item to move. |
| `to` | query | yes | Destination folder. Omit for the root. |

### PUT /api/v1/files/copy

Copy a file or folder. Copies an item into another folder, leaving the source in place. Folders are copied recursively. This is how to pull data out of a read-only shared folder.

| Parameter | In | Required | Description |
|---|---|---|---|
| `from` | query | yes | Item to copy. |
| `to` | query | yes | Destination folder. Omit for the root. |

### PUT /api/v1/files/rename

Rename a file or folder. Renames an item in place. `newName` must not contain a path separator.

| Parameter | In | Required | Description |
|---|---|---|---|
| `path` | query | yes | Item to rename. |
| `newName` | query | yes | New name. |

### DELETE /api/v1/files

Delete a file or folder. Deletes a file, or a folder and everything inside it. This cannot be undone.

| Parameter | In | Required | Description |
|---|---|---|---|
| `path` | query | yes | Item to delete. |

### GET /api/v1/files/info

Read one item's details. Returns name, size, timestamps and whether the item is a folder.

| Parameter | In | Required | Description |
|---|---|---|---|
| `path` | query | yes | Item to inspect. |

### GET /api/v1/account

Read the calling account. Returns the username, role and storage usage behind the API key.

### GET /api/v1/keys

List your API keys. Returns the keys belonging to the calling account, without the secret values.

### POST /api/v1/keys

Create an API key. Creates a key. The secret is returned once and cannot be retrieved again.

| Parameter | In | Required | Description |
|---|---|---|---|
| `name` | query | yes | Label to recognise the key by. |
| `folder` | query | no | Restrict the key to this folder. |

### DELETE /api/v1/keys/{id}

Revoke an API key. Immediately stops the key from working.

| Parameter | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | Id of the key to revoke. |

## Errors

| Status | Meaning |
|---|---|
| 400 | The request was missing something, or the name was invalid |
| 401 | The `X-API-Key` header was missing or the key is not valid |
| 403 | The key is scoped to a folder and the path is outside it |
| 404 | No such file or folder |

Built with love from [ShareWith](https://sharewith.xyz).