ShiftMyData

ShiftMyData API

Move, copy and sync files between clouds, and run it on a schedule. Sign in with OAuth 2.1 (authorization code with PKCE, the device flow for command-line tools, or client credentials for servers) or a personal API token. Public clients must bind their tokens with DPoP. Every list is paged with an opaque cursor; every creating POST takes an Idempotency-Key; every answer carries RateLimit headers.

Base address https://shiftmydata.com. Machine-readable: openapi.json (OpenAPI 3.1). Authorisation server metadata: /api/oauth/metadata.

Signing in

Public clients (mobile apps, the CLI, browser extensions) must bind their tokens with DPoP (RFC 9449): send Authorization: DPoP <token> and a fresh DPoP proof signed by a key that never leaves the device. Access tokens live ten minutes; refresh tokens rotate on every use, and a reused one ends the sign-in. Register an app under Account, Developers.

Scopes

ScopeLets the app
clouds:readSee which clouds you have connected
files:readList, search and download your files
files:writeUpload, copy, move, rename and delete your files
offline_accessStay signed in when you are not using it
profileSee your name, email address and plan
schedules:readSee your schedules
schedules:writeCreate, change, run and delete schedules
transfers:readSee your transfers and their progress
transfers:writeStart, pause and cancel transfers
webhooksSend your transfer and schedule events to an address you choose
workspaces:readRead your encrypted workspaces and their discussion
workspaces:writePost in your encrypted workspaces

A person can narrow any grant further when they allow it: to one cloud and folder, to address ranges, and to an end date.

Rules every call follows

Ready-made clients

Endpoints

Account

GET /api/v1/account

Profile

Answer 200

FieldTypeMeaning
account_urlstring
emailstring
email_verifiedboolean
google_linkedboolean
has_passwordboolean
mail_configuredboolean
namestring
passkeys_enabledboolean
role"owner" | "admin" | "member" | "viewer"
security_urlstring
sub_accountboolean

POST /api/v1/account/delete

Delete Account

Delete the account and everything ShiftMyData holds for it, straight away. Files in the person's clouds are not touched. The password confirms it, or for an account without one, the address typed exactly. The app's own sign-in ends with the account.

Body (JSON)

FieldTypeMeaning
confirm_email optionalstring (optional)
password optionalstring (optional)

Answer 204

No body.

POST /api/v1/account/password

Change Password

Change the password, given the current one. Every browser is signed out, and every API token and drive app password stops working, as on the website. This app stays signed in.

Body (JSON)

FieldTypeMeaning
current_passwordstring
new_passwordstring

Answer 204

No body.

POST /api/v1/account/verification

Resend Verification

Send the confirmation link again. Nothing happens for an address already confirmed.

Answer 202

FieldTypeMeaning
status optional"accepted"

GET /api/v1/me

Me

Answer 200

FieldTypeMeaning
created_atstring (date-time)
emailstring
idstring (uuid)
scopestring
sub_accountboolean

POST /api/v1/me/coupons

Redeem Coupon

Redeem a coupon code; the allowance goes to the account's owner. A wrong code counts like a wrong password, as on the website.

Body (JSON)

FieldTypeMeaning
codestring

Answer 200

FieldTypeMeaning
bytes_grantedinteger
total_grantedinteger

GET /api/v1/me/drive

Drive

Answer 200

FieldTypeMeaning
app_passwords_urlstring
drive_addressstring
drive_enabledboolean
sftp_addressstring
sftp_enabledboolean
usernamestring

GET /api/v1/me/receipts

Receipts

Every pack the account owner paid for, as receipts, with the seller's details to print on them (mobile parity P1.13). The owner's alone: a sub-account is refused, as on the website. Packs are bought through sales on WhatsApp until checkout opens.

Answer 200

FieldTypeMeaning
billed_tostring
gstinstring
receiptslist of ReceiptOut
seller_addressstring
seller_namestring
tax_invoiceboolean

GET /api/v1/me/referrals

Referrals

The owner's invite link and what it has earned. A sub-account is refused, as on the website.

Answer 200

FieldTypeMeaning
bytes_earnedinteger
codestring
enabledboolean
hold_daysinteger
invitedinteger
linkstring
pendinginteger
rewardedinteger

GET /api/v1/me/summary

Summary

Answer 200

FieldTypeMeaning
allowance_consumed_bytes optionalinteger
allowance_expires_atstring (date-time) (optional)
allowance_granted_bytesinteger
allowance_in_use_bytes optionalinteger
allowance_remaining_bytesinteger
clouds optionalinteger (optional)
planstring (optional)
transfers_running optionalinteger (optional)
unlimitedboolean
used_bytes_this_month optionalinteger

People

GET /api/v1/audit

Events

Everything done in the organisation, newest first. Pass the last ``id`` as ``before``.

Parameters

NameTypeMeaning
before query, optionalinteger (optional)

Answer 200

list of AuditEventOut

GET /api/v1/audit/settings

Settings

Answer 200

FieldTypeMeaning
retention_daysinteger (optional)
webhookstring (optional)
webhook_delivered_atstring (date-time) (optional)
webhook_errorstring (optional)

PUT /api/v1/audit/settings

Change Settings

How long events are kept: 30 days to ten years, or null to keep them.

Body (JSON)

FieldTypeMeaning
retention_days optionalinteger (optional)

Answer 200

FieldTypeMeaning
retention_daysinteger (optional)
webhookstring (optional)
webhook_delivered_atstring (date-time) (optional)
webhook_errorstring (optional)

PUT /api/v1/audit/webhook

Set Webhook

Send each new event to a SIEM. The signing secret is in this answer only.

Body (JSON)

FieldTypeMeaning
urlstring

Answer 200

FieldTypeMeaning
secretstring
settingsAuditSettingsOut

DELETE /api/v1/audit/webhook

Remove Webhook

Answer 200

FieldTypeMeaning
retention_daysinteger (optional)
webhookstring (optional)
webhook_delivered_atstring (date-time) (optional)
webhook_errorstring (optional)

GET /api/v1/people

People

Answer 200

list of SubAccountOut

POST /api/v1/people

Add Person

Add somebody who signs in for themselves and reaches nothing until a folder is lent. Accepted either way: whether the address already has an account is not said.

Body (JSON)

FieldTypeMeaning
emailstring (email)
label optionalstring
passwordstring
role optional"member" | "viewer" | "admin"

Answer 202

FieldTypeMeaning
status optional"accepted"

GET /api/v1/people/lendable

Lendable

The owner's clouds a folder can be lent from.

Answer 200

list of LendableAccount

PATCH /api/v1/people/{person_id}

Change Person

Rename, change the role, suspend or reinstate, or set a new password.

Parameters

NameTypeMeaning
person_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
is_active optionalboolean (optional)
label optionalstring (optional)
password optionalstring (optional)
role optional"member" | "viewer" | "admin" (optional)

Answer 200

FieldTypeMeaning
created_atstring (date-time)
emailstring (email)
grantsinteger
held_jobs optionalinteger
idstring (uuid)
is_activeboolean
labelstring
last_login_atstring (date-time) (optional)
role optional"member" | "viewer" | "admin"
tokens optionalinteger

DELETE /api/v1/people/{person_id}

Remove Person

Parameters

NameTypeMeaning
person_id pathstring (uuid)

Answer 204

No body.

GET /api/v1/people/{person_id}/folders

Folders

The folders lent to this person.

Parameters

NameTypeMeaning
person_id pathstring (uuid)

Answer 200

list of GrantOut

POST /api/v1/people/{person_id}/folders

Lend Folder

Lend one folder of one cloud, to read or to read and change.

Parameters

NameTypeMeaning
person_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
account_idstring (uuid)
can_write optionalboolean
path optionalstring

Answer 201

FieldTypeMeaning
account_idstring (uuid)
account_namestring
can_writeboolean
created_atstring (date-time)
idstring (uuid)
pathstring
replaced optionallist of string

PATCH /api/v1/people/{person_id}/folders/{grant_id}

Change Folder

Parameters

NameTypeMeaning
person_id pathstring (uuid)
grant_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
can_writeboolean

Answer 200

FieldTypeMeaning
account_idstring (uuid)
account_namestring
can_writeboolean
created_atstring (date-time)
idstring (uuid)
pathstring

DELETE /api/v1/people/{person_id}/folders/{grant_id}

Take Folder Back

Stop lending a folder. Their transfers from it are cancelled, their links to it end.

Parameters

NameTypeMeaning
person_id pathstring (uuid)
grant_id pathstring (uuid)

Answer 200

FieldTypeMeaning
jobs_cancelledinteger
shares_revokedinteger

GET /api/v1/people/{person_id}/held-jobs

Held Jobs

Their transfers held when they were suspended.

Parameters

NameTypeMeaning
person_id pathstring (uuid)

Answer 200

list of HeldJobOut

GET /api/v1/people/{person_id}/tokens

Person Tokens

Parameters

NameTypeMeaning
person_id pathstring (uuid)

Answer 200

list of DelegateTokenOut

DELETE /api/v1/people/{person_id}/tokens/{token_id}

Revoke Person Token

Parameters

NameTypeMeaning
person_id pathstring (uuid)
token_id pathstring (uuid)

Answer 204

No body.

Transfers

POST /api/v1/calendars/transfers

Start

Back up, copy or restore calendars or contacts (``what``). From a cloud of this kind, ``src_collections`` picks which (empty: every one); from storage, ``src_path`` is one file or a folder of them. Into one, ``dst_collection`` picks where (empty: matched by name). A transfer to follow.

Body (JSON)

FieldTypeMeaning
dst_account_idstring (uuid)
dst_collection optionalstring
dst_path optionalstring
src_account_idstring (uuid)
src_collections optionallist of string
src_path optionalstring
what"calendars" | "contacts"

Answer 202

object

GET /api/v1/calendars/{account_id}/collections

Collections

The calendars or address books in one cloud, asked of the service now: id, name, and whether it can be written to.

Parameters

NameTypeMeaning
account_id pathstring (uuid)
kind query, optional"calendars" | "contacts"

Answer 200

list of CollectionOut

GET /api/v1/databases

List Databases

Every connected database: engine, its name (empty for a whole MongoDB server or a Redis), whether backups are encrypted, whether it can be restored from here, the last backup and restore, and the backup schedules that read it. Never a password or a passphrase.

Answer 200

list of DatabaseOut

POST /api/v1/databases/backups

Backup

Back a database up into a cloud folder now. ``include`` or ``exclude`` picks tables or collections (``key`` from ``/objects``); ``keep_last`` is how many of its own backups the folder keeps. A transfer to follow.

Body (JSON)

FieldTypeMeaning
dst_account_idstring (uuid)
dst_path optionalstring
events optionalboolean
exclude optionallist of string
include optionallist of string
keep_last optionalinteger
routines optionalboolean
src_account_idstring (uuid)
triggers optionalboolean

Answer 202

object

POST /api/v1/databases/restores

Restore

Load a backup file from a cloud into a database. It changes the database, so ``confirm`` must be the database's name, typed by the person; never retried on its own. ``passphrase`` is for a backup encrypted with another passphrase than the account's.

Body (JSON)

FieldTypeMeaning
confirmstring
drop optionalboolean
dst_account_idstring (uuid)
passphrase optionalstring (optional)
src_account_idstring (uuid)
src_pathstring

Answer 202

object

GET /api/v1/databases/{account_id}/objects

List Objects

What the database holds -- tables, views, collections and the rest -- for choosing what a backup takes. Asked of the database now, so under the write limit.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Answer 200

FieldTypeMeaning
objectslist of DbObjectOut
reasonstring (optional)
supportedboolean
truncatedboolean

POST /api/v1/mail/migrations

Migrate

Move a mailbox into a cloud folder (``format``: ``archive``, a PDF per message with the original and its attachments, or ``mbox``, a backup any mail program imports) or into another mailbox. ``filter`` picks messages; ``attachments_only`` saves only the files they carry. Each run takes only what the last one did not. A transfer to follow.

Body (JSON)

FieldTypeMeaning
attachments optionalboolean
attachments_only optionalboolean
dst_account_idstring (uuid)
dst_path optionalstring
filter optionalMailFilter (optional)
folders optionallist of string
format optional"archive" | "mbox"
keep_original optionalboolean
since optionalstring (date) (optional)
src_account_idstring (uuid)

Answer 202

object

POST /api/v1/mail/pst

Import Pst

Turn an Outlook .pst in a cloud into .mbox files beside it, and, with ``restore_into``, put them into a mailbox too. 403 when this server does not import PST files. A transfer to follow.

Body (JSON)

FieldTypeMeaning
dst_account_idstring (uuid)
dst_path optionalstring
restore_into optionalstring (uuid) (optional)
restore_path optionalstring
src_account_idstring (uuid)
src_pathstring

Answer 202

object

POST /api/v1/mail/restores

Restore

Put the mail in .mbox files (one file, or a folder of them at any depth) back into a mailbox; Sent goes to Sent, Trash to Trash. A transfer to follow.

Body (JSON)

FieldTypeMeaning
dst_account_idstring (uuid)
dst_path optionalstring
src_account_idstring (uuid)
src_path optionalstring

Answer 202

object

GET /api/v1/mail/{account_id}/folders

Mail Folders

The mailbox's folders, asked of the server now, with how deep each sits, whether it holds messages, and the ones a migration takes if nothing is changed.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Answer 200

FieldTypeMeaning
folderslist of FolderOut
suggestedlist of string

GET /api/v1/organisations/{account_id}/directory

Read Directory

Who belongs to this organisation, asked of it now: address, name, active, and whether they are already connected here. The first real test of the organisation's credential, so a failure names the grant that is missing.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Answer 200

FieldTypeMeaning
peoplelist of PersonOut
truncatedboolean

POST /api/v1/organisations/{account_id}/members

Add Members

Connect up to 200 of the organisation's people as accounts, to put in a roster. Somebody who cannot be addressed (never opened their drive) is skipped and named.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
peoplelist of app__api__routes__accounts__organisation__PersonIn

Answer 201

FieldTypeMeaning
createdlist of Cloud
skippedlist of Skipped

GET /api/v1/organisations/{account_id}/spaces

Read Spaces

The organisation's Shared Drives, SharePoint sites or team folders, asked of it now.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Answer 200

list of SharedSpaceOut

POST /api/v1/organisations/{account_id}/spaces

Add Spaces

Connect some of the organisation's shared spaces as accounts, by the ids the listing gave them.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
idslist of string

Answer 201

FieldTypeMeaning
createdlist of Cloud
skippedlist of Skipped

POST /api/v1/saves

Save From Web

Fetch a link, a page's video, or a rendering of the page into a folder, as a transfer to follow at ``/transfers/{id}``. The server fetches it, never the client: the same address checks as the web app's own (no private addresses, redirects re-checked).

Body (JSON)

FieldTypeMeaning
destination_cloud_idstring (uuid)
destination_path optionalstring
kind optional"file" | "video" | "page" | "image"
name optionalstring (optional)
urlstring

Answer 202

object

POST /api/v1/saves/torrent

Save Torrent

Download a torrent or magnet link into a folder, as a transfer to follow at ``/transfers/{id}``. The website's own handler: a ``.torrent`` is read before this answers, so its size and file names are checked now; a magnet's size once the swarm says. 503 when this server does not take torrents (``features`` in ``/providers`` says so).

Body (JSON)

FieldTypeMeaning
destination_cloud_idstring (uuid)
destination_path optionalstring
magnet optionalstring (optional)
torrent optionalstring (optional)

Answer 202

object

POST /api/v1/scans/assessment

Scan Assessment

Check a folder against a destination before moving it (mobile parity P3.5). Free, and nothing moves: what would fail (a path too long, a name refused, a file over a limit, two names differing only in case), what would change, and an estimate of the time and the allowance. A transfer to follow; once finished, ``/transfers/{id}/assessment``. Takes the transfer filters too. 403 when this server does not assess (``assessment`` in ``/providers`` ``features``).

Body (JSON)

FieldTypeMeaning
dst_account_idstring (uuid)
dst_path optionalstring
exclude optionallist of string
exclude_types optionallist of string
include optionallist of string
include_types optionallist of string
max_size optionalinteger (optional)
min_size optionalinteger (optional)
modified_after optionalstring (date-time) (optional)
modified_before optionalstring (date-time) (optional)
older_than_days optionalinteger (optional)
src_account_idstring (uuid)
src_path optionalstring

Answer 202

object

POST /api/v1/scans/cleanup

Scan Cleanup

Look for large old files, empty folders and trash to empty. A transfer to follow; once finished, ``/transfers/{id}/cleanup`` has the suggestions.

Body (JSON)

FieldTypeMeaning
large_mb optionalinteger
older_than_days optionalinteger
placeslist of Place

Answer 202

object

POST /api/v1/scans/duplicates

Scan Duplicates

Look for copies of the same file across up to ten places (clouds or folders). A transfer to follow; once it has finished, ``/transfers/{id}/duplicates`` has the groups. Reads whole clouds, so it shares an hourly limit with the clean-up scan.

Body (JSON)

FieldTypeMeaning
min_kb optionalinteger
placeslist of Place

Answer 202

object

POST /api/v1/team-transfers

Start

Start a migration: one batch, many members, one report. The whole roster is checked first. A transfer to follow (``kind`` ``team_transfer``); its people are ``/transfers/{id}/members``.

Body (JSON)

FieldTypeMeaning
certificate optionalboolean
certificate_download optionalboolean
concurrency optionalinteger
exclude optionallist of string
fix_names optionalboolean
include optionallist of string
max_size optionalinteger (optional)
memberslist of TeamMember
min_size optionalinteger (optional)
mode optionalTransferMode
name optionalstring
report optionalboolean
verify_checksum optionalboolean

Answer 202

object

POST /api/v1/team-transfers/plan

Plan

The whole migration before it exists: refused, naming the member, when any row cannot run; otherwise each member's plan and the warnings rolled up.

Body (JSON)

FieldTypeMeaning
certificate optionalboolean
certificate_download optionalboolean
concurrency optionalinteger
exclude optionallist of string
fix_names optionalboolean
include optionallist of string
max_size optionalinteger (optional)
memberslist of TeamMember
min_size optionalinteger (optional)
mode optionalTransferMode
name optionalstring
report optionalboolean
verify_checksum optionalboolean

Answer 200

FieldTypeMeaning
concurrencyinteger
memberslist of MemberPlan
modeTransferMode
namestring
warningslist of string

GET /api/v1/transfers

List Transfers

Newest first. Members of a team transfer are read through the batch, not listed here.

Keyset paging on (created, id), so a transfer started while a client pages through never shifts the pages it has not read yet.

Parameters

NameTypeMeaning
cursor query, optionalstring (optional)
limit query, optionalinteger

Answer 200

FieldTypeMeaning
itemslist of Transfer
next_cursor optionalstring (optional)

POST /api/v1/transfers

Start Transfer

Start a transfer. Send ``Idempotency-Key`` so a retry cannot start a second one.

Body (JSON)

FieldTypeMeaning
certificate optionalboolean
certificate_download optionalboolean
conflict optionalConflictRule (optional)
destination_cloud_idstring (uuid)
destination_path optionalstring
exclude optionallist of string
exclude_types optionallist of string
fix_names optionalboolean
google_docs optional"office" | "pdf" | "opendocument" | "skip"
include optionallist of string
include_types optionallist of string
keep_sharing optionalboolean
max_delete optionalinteger (optional)
max_size optionalinteger (optional)
min_size optionalinteger (optional)
mode optional"copy" | "mirror" | "move" | "cumulative" | "update" | "incremental_backup" | "full_backup" | "two_way" | "real_time"
modified_after optionalstring (date-time) (optional)
modified_before optionalstring (date-time) (optional)
report optionalboolean
source_cloud_idstring (uuid)
source_path optionalstring
verify_checksum optionalboolean

Answer 202

object

POST /api/v1/transfers/plan

Plan Transfer

What a transfer would do, before it is started. Starts nothing.

Body (JSON)

FieldTypeMeaning
certificate optionalboolean
certificate_download optionalboolean
conflict optionalConflictRule (optional)
destination_cloud_idstring (uuid)
destination_path optionalstring
exclude optionallist of string
exclude_types optionallist of string
fix_names optionalboolean
google_docs optional"office" | "pdf" | "opendocument" | "skip"
include optionallist of string
include_types optionallist of string
keep_sharing optionalboolean
max_delete optionalinteger (optional)
max_size optionalinteger (optional)
min_size optionalinteger (optional)
mode optional"copy" | "mirror" | "move" | "cumulative" | "update" | "incremental_backup" | "full_backup" | "two_way" | "real_time"
modified_after optionalstring (date-time) (optional)
modified_before optionalstring (date-time) (optional)
report optionalboolean
source_cloud_idstring (uuid)
source_path optionalstring
verify_checksum optionalboolean

Answer 200

FieldTypeMeaning
brake optionalstring (optional)
can_choose_google_docs optionalboolean
can_keep_sharing optionalboolean
noteslist of string
server_sideboolean
verificationstring
warningslist of string

GET /api/v1/transfers/{job_id}

Get Transfer

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

FieldTypeMeaning
bytes_doneinteger
bytes_totalinteger
certificate optionalboolean
created_atstring (date-time)
cutover optionalboolean
destination_cloud_idstring (uuid) (optional)
destination_pathstring
errorstring (optional)
files_doneinteger
files_totalinteger
finished_atstring (date-time) (optional)
idstring (uuid)
kindstring
modestring
name optionalstring (optional)
report optionalboolean
source_cloud_idstring (uuid) (optional)
source_pathstring
started_atstring (date-time) (optional)
statusstring

GET /api/v1/transfers/{job_id}/assessment

Assessment Result

A finished assessment: its summary, counts and first findings, the website's own answer, kept two weeks.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

GET /api/v1/transfers/{job_id}/assessment.csv

Assessment Csv

Every finding, as a spreadsheet.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

GET /api/v1/transfers/{job_id}/assessment.pdf

Assessment Pdf

The assessment as a report to hand to somebody.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

POST /api/v1/transfers/{job_id}/cancel

Cancel Transfer

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

FieldTypeMeaning
bytes_doneinteger
bytes_totalinteger
certificate optionalboolean
created_atstring (date-time)
cutover optionalboolean
destination_cloud_idstring (uuid) (optional)
destination_pathstring
errorstring (optional)
files_doneinteger
files_totalinteger
finished_atstring (date-time) (optional)
idstring (uuid)
kindstring
modestring
name optionalstring (optional)
report optionalboolean
source_cloud_idstring (uuid) (optional)
source_pathstring
started_atstring (date-time) (optional)
statusstring

GET /api/v1/transfers/{job_id}/certificate.csv

Transfer Certificate Manifest

The certificate's manifest: the files it vouches for, kept here thirty days.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

GET /api/v1/transfers/{job_id}/certificate.pdf

Transfer Certificate

The signed migration certificate, as a PDF. 404 with the reason when there is none.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

GET /api/v1/transfers/{job_id}/cleanup

Scan Cleanup Result

A finished clean-up scan's suggestions. The website's own answer, kept two days.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

GET /api/v1/transfers/{job_id}/cutover

Cutover

Per person, after a pass with a per-file report: in sync, or what is left.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

FieldTypeMeaning
finishedboolean
memberslist of MemberSync

POST /api/v1/transfers/{job_id}/delta

Delta

Run the roster again, bringing across what changed since. With ``cutover``, the last pass: afterwards ``/transfers/{id}/cutover`` says, per person, in sync or what is left. 409 while a pass is still running.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
cutover optionalboolean

Answer 202

FieldTypeMeaning
bytes_doneinteger
bytes_totalinteger
certificate optionalboolean
created_atstring (date-time)
cutover optionalboolean
destination_cloud_idstring (uuid) (optional)
destination_pathstring
errorstring (optional)
files_doneinteger
files_totalinteger
finished_atstring (date-time) (optional)
idstring (uuid)
kindstring
modestring
name optionalstring (optional)
report optionalboolean
source_cloud_idstring (uuid) (optional)
source_pathstring
started_atstring (date-time) (optional)
statusstring

GET /api/v1/transfers/{job_id}/duplicates

Scan Duplicates Result

A finished duplicate scan's groups, the most space wasted first. The website's own answer, kept two days.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

GET /api/v1/transfers/{job_id}/events

Transfer Events

Live progress as server-sent events, the same stream the web app watches.

Each event is a JSON snapshot of the transfer's counters; the stream ends when it does. Native clients send their token in the ``Authorization`` header like any other request.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

GET /api/v1/transfers/{job_id}/history

Transfer History

What happened during the transfer, oldest first: the website's log of a run (mobile parity P1.9). Where ``error`` says it failed, this says what led there.

Parameters

NameTypeMeaning
job_id pathstring (uuid)
limit query, optionalinteger

Answer 200

list of HistoryLine

GET /api/v1/transfers/{job_id}/members

Members

Who moved and who did not, in roster order. 404 for any other kind of transfer.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

FieldTypeMeaning
bytes_doneinteger
cancelledinteger
failedinteger
files_doneinteger
idstring (uuid)
memberslist of app__api__v1__teams__Member
namestring
runninginteger
statusstring
succeededinteger
totalinteger
waitinginteger

GET /api/v1/transfers/{job_id}/members.csv

Members Csv

The member report as a spreadsheet, in roster order: what a migration is signed off with.

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

POST /api/v1/transfers/{job_id}/pause

Pause Transfer

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

FieldTypeMeaning
bytes_doneinteger
bytes_totalinteger
certificate optionalboolean
created_atstring (date-time)
cutover optionalboolean
destination_cloud_idstring (uuid) (optional)
destination_pathstring
errorstring (optional)
files_doneinteger
files_totalinteger
finished_atstring (date-time) (optional)
idstring (uuid)
kindstring
modestring
name optionalstring (optional)
report optionalboolean
source_cloud_idstring (uuid) (optional)
source_pathstring
started_atstring (date-time) (optional)
statusstring

GET /api/v1/transfers/{job_id}/report.csv

Transfer Report

The per-file report: every source file and where it ended up. 404 with the reason when there is none (not asked for, not finished, or older than thirty days).

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

object

POST /api/v1/transfers/{job_id}/resume

Resume Transfer

Parameters

NameTypeMeaning
job_id pathstring (uuid)

Answer 200

FieldTypeMeaning
bytes_doneinteger
bytes_totalinteger
certificate optionalboolean
created_atstring (date-time)
cutover optionalboolean
destination_cloud_idstring (uuid) (optional)
destination_pathstring
errorstring (optional)
files_doneinteger
files_totalinteger
finished_atstring (date-time) (optional)
idstring (uuid)
kindstring
modestring
name optionalstring (optional)
report optionalboolean
source_cloud_idstring (uuid) (optional)
source_pathstring
started_atstring (date-time) (optional)
statusstring

Clouds

GET /api/v1/clouds

List Clouds

Every cloud the caller can see, oldest first. Short enough never to need a page.

Answer 200

list of Cloud

POST /api/v1/clouds

Connect With Fields

Connect a cloud by its details (a key pair, a server and password), proved first.

Sign-in clouds use ``POST /clouds/connect``. Typed in ShiftMyData's own app only, by the account owner: the details go to the server, which tries them before keeping them.

Body (JSON)

FieldTypeMeaning
display_name optionalstring
fields optionalobject
members optionallist of app__api__routes__accounts___shared__MemberIn
providerstring

Answer 201

FieldTypeMeaning
created_atstring (date-time)
filesboolean
folders optionallist of Folder
holds optionallist of string
idstring (uuid)
kind optionalstring
namestring
needs_folder optionalboolean
picked_only optionalboolean
providerstring
provider_labelstring
statusstring

POST /api/v1/clouds/connect

Start Connect

Start connecting a cloud by its sign-in. Credential clouds use ``POST /clouds``.

Body (JSON)

FieldTypeMeaning
code_challengestring
providerstring

Answer 200

FieldTypeMeaning
authorize_urlstring
return_urlstring

POST /api/v1/clouds/connect/complete

Complete Connect

Finish it with the id the browser brought back and the app's verifier.

Body (JSON)

FieldTypeMeaning
code_verifierstring
completionstring

Answer 200

FieldTypeMeaning
created_atstring (date-time)
filesboolean
folders optionallist of Folder
holds optionallist of string
idstring (uuid)
kind optionalstring
namestring
needs_folder optionalboolean
picked_only optionalboolean
providerstring
provider_labelstring
statusstring

GET /api/v1/providers

Providers

Every service this server can connect, and which are not set up yet.

Answer 200

FieldTypeMeaning
connectable optionalinteger
features optionallist of string
providerslist of ProviderOut
unavailablelist of string

Files

GET /api/v1/clouds/{account_id}/files

List Folder

Folders first, then files, each by name.

The provider is asked for the whole folder on every page -- most cannot list from the middle -- so a client reading a large folder should use a large ``limit``.

Parameters

NameTypeMeaning
account_id pathstring (uuid)
cursor query, optionalstring (optional)
limit query, optionalinteger
path query, optionalstring

Answer 200

FieldTypeMeaning
can_writeboolean
itemslist of File
next_cursor optionalstring (optional)

GET /api/v1/clouds/{account_id}/files/content

Download

The file at ``?path=``, streamed. Supports ``Range`` for resuming.

Parameters

NameTypeMeaning
account_id pathstring (uuid)
path query, optionalstring

Answer 200

object

POST /api/v1/clouds/{account_id}/files/copy

Copy

Copy or move items. Small ones happen at once; large ones become a transfer.

Parameters

NameTypeMeaning
account_id pathstring (uuid)
path query, optionalstring

Body (JSON)

FieldTypeMeaning
destination_cloud_idstring (uuid)
destination_path optionalstring
mode optional"copy" | "move"
nameslist of string

Answer 200

object

POST /api/v1/clouds/{account_id}/files/delete

Delete

Delete items; a folder goes with everything in it. Each item answers for itself.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
itemslist of DeleteItem

Answer 200

list of DeleteResult

POST /api/v1/clouds/{account_id}/files/remove-empty

Remove Empty

Remove folders that are empty (mobile parity P2.6). Only what is still empty goes: a folder that has had a file put in it since the scan is left, and says so.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
pathslist of string

Answer 200

list of DeleteResult

POST /api/v1/clouds/{account_id}/files/rename

Rename

Rename the item at ``?path=`` in place.

Parameters

NameTypeMeaning
account_id pathstring (uuid)
path query, optionalstring

Body (JSON)

FieldTypeMeaning
namestring

Answer 200

FieldTypeMeaning
doneboolean
pathstring (optional)
transfer_id optionalstring (uuid) (optional)

POST /api/v1/clouds/{account_id}/folders

Create Folder

A folder named ``name`` inside ``?path=``.

Parameters

NameTypeMeaning
account_id pathstring (uuid)
path query, optionalstring

Body (JSON)

FieldTypeMeaning
namestring

Answer 201

FieldTypeMeaning
doneboolean
pathstring (optional)
transfer_id optionalstring (uuid) (optional)

POST /api/v1/clouds/{account_id}/trash/empty

Empty Trash

Empty this cloud's trash for good (mobile parity P2.6). The account owner only, and only where the provider's trash can be emptied from here; the website's own handler.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Answer 200

FieldTypeMeaning
doneboolean

POST /api/v1/clouds/{account_id}/uploads

Start Upload

Start uploading a file named ``name`` of ``size`` bytes into ``?path=``.

Parameters

NameTypeMeaning
account_id pathstring (uuid)
name querystring
size queryinteger
overwrite query, optionalboolean
path query, optionalstring

Answer 201

FieldTypeMeaning
idstring
piece_bytesinteger
receivedinteger
sizeinteger

PUT /api/v1/clouds/{account_id}/uploads/{session_id}

Send Piece

One piece of the file, as the body, starting at ``offset``.

Parameters

NameTypeMeaning
session_id pathstring
account_id pathstring (uuid)
offset queryinteger
path query, optionalstring

Answer 200

FieldTypeMeaning
idstring
piece_bytesinteger
receivedinteger
sizeinteger

DELETE /api/v1/clouds/{account_id}/uploads/{session_id}

Cancel Upload

Parameters

NameTypeMeaning
session_id pathstring
account_id pathstring (uuid)
path query, optionalstring

Answer 204

No body.

POST /api/v1/clouds/{account_id}/uploads/{session_id}/complete

Complete Upload

Parameters

NameTypeMeaning
session_id pathstring
account_id pathstring (uuid)
path query, optionalstring

Answer 200

FieldTypeMeaning
pathstring
sizeinteger

GET /api/v1/upload-requests

List Links

Every link made, newest first, the dead ones included.

Answer 200

list of UploadRequestOut

POST /api/v1/upload-requests

Make Link

A link strangers can upload into this folder through. ``url`` is shown once, here: only a fingerprint of it is kept. Send ``Idempotency-Key`` so a retry makes one.

Body (JSON)

FieldTypeMeaning
account_idstring (uuid)
allowed_extensions optionallist of string
expires_in_days optionalinteger
label optionalstring
max_bytes_per_file optionalinteger (optional)
max_files optionalinteger
passphrase optionalstring (optional)
path optionalstring

Answer 201

object

DELETE /api/v1/upload-requests/{request_id}

Turn Off

Stop a link taking files. What arrived through it stays explained.

Parameters

NameTypeMeaning
request_id pathstring (uuid)

Answer 204

No body.

Developers

GET /api/v1/developers/apps

Apps

Answer 200

list of RegisteredApp

POST /api/v1/developers/apps

Make App

Register an app. A client-secret app's secret is in this answer and never again.

Body (JSON)

FieldTypeMeaning
auth_method"none" | "private_key_jwt" | "client_secret_basic" | "client_secret_post"
grant_typeslist of string
homepage optionalstring (optional)
jwks optionalobject (optional)
jwks_uri optionalstring (optional)
kind"public" | "confidential"
namestring
redirect_uris optionallist of string
scopestring

Answer 201

FieldTypeMeaning
auth_methodstring
client_idstring
client_secret optionalstring (optional)
confidentialboolean
created_atstring (date-time)
disabledboolean
dpop_boundboolean
grant_typeslist of string
has_keysboolean
homepagestring (optional)
idstring (uuid)
jwks_uristring (optional)
namestring
redirect_urislist of string
reviewedboolean
scopestring

PATCH /api/v1/developers/apps/{app_id}

Change App

Parameters

NameTypeMeaning
app_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
homepage optionalstring (optional)
name optionalstring (optional)
redirect_uris optionallist of string (optional)

Answer 200

FieldTypeMeaning
auth_methodstring
client_idstring
confidentialboolean
created_atstring (date-time)
disabledboolean
dpop_boundboolean
grant_typeslist of string
has_keysboolean
homepagestring (optional)
idstring (uuid)
jwks_uristring (optional)
namestring
redirect_urislist of string
reviewedboolean
scopestring

DELETE /api/v1/developers/apps/{app_id}

Switch Off App

Switch the app off: every sign-in made through it ends.

Parameters

NameTypeMeaning
app_id pathstring (uuid)

Answer 204

No body.

POST /api/v1/developers/apps/{app_id}/secret

New Secret

A new client secret, shown once; the old one keeps working for a day.

Parameters

NameTypeMeaning
app_id pathstring (uuid)

Answer 200

FieldTypeMeaning
auth_methodstring
client_idstring
client_secret optionalstring (optional)
confidentialboolean
created_atstring (date-time)
disabledboolean
dpop_boundboolean
grant_typeslist of string
has_keysboolean
homepagestring (optional)
idstring (uuid)
jwks_uristring (optional)
namestring
redirect_urislist of string
reviewedboolean
scopestring

GET /api/v1/developers/connected

Connected

Every app that can use this account: what it may do, from where, and when last.

Answer 200

list of ConnectedApp

DELETE /api/v1/developers/connected/{grant_id}

Disconnect

Stop an app reaching the account, from its next request.

Parameters

NameTypeMeaning
grant_id pathstring (uuid)

Answer 204

No body.

Schedules

GET /api/v1/mirrors

List Mirrors

Every mirror: the organisation, where its copies go and how (``mirror``, ``two_way``, ``copy``), how often, people and Shared Drives in it, on or paused, the last pass and its problem, and the live watch (drives watched, the last change copied, the oldest waiting).

Answer 200

list of MirrorOut

POST /api/v1/mirrors

Create Mirror

Read the organisation's directory, connect its people, and start mirroring into ``dst_account_id`` / ``dst_path``. The first pass is due at once. The organisation is a cloud of ``kind`` ``organisation`` in ``GET /clouds``.

Body (JSON)

FieldTypeMeaning
dst_account_idstring (uuid)
dst_path optionalstring
every_minutes optional15 | 30 | 60
mode optional"mirror" | "two_way" | "copy"
shared_drives optionalboolean
tenant_account_idstring (uuid)

Answer 201

object

PATCH /api/v1/mirrors/{mirror_id}

Pause Or Resume

``enabled`` false pauses it; true resumes it with a pass due at once.

Parameters

NameTypeMeaning
mirror_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
enabledboolean

Answer 200

FieldTypeMeaning
dst_account_idstring (uuid)
dst_namestring
dst_pathstring
enabledboolean
every_minutesinteger
idstring (uuid)
last_errorstring (optional)
last_reconciled_atstring (date-time) (optional)
last_run_atstring (date-time) (optional)
last_statusJobStatus (optional)
liveLiveOut
modestring
peopleinteger
shared_drivesboolean
spacesinteger
tenant_account_idstring (uuid)
tenant_namestring

DELETE /api/v1/mirrors/{mirror_id}

Delete Mirror

Stop mirroring. The copies already made stay where they are, and so do the people's accounts, which other transfers may use.

Parameters

NameTypeMeaning
mirror_id pathstring (uuid)

Answer 204

No body.

POST /api/v1/mirrors/{mirror_id}/directory

Read Directory Now

Read the directory now rather than tomorrow: somebody just joined.

Parameters

NameTypeMeaning
mirror_id pathstring (uuid)

Answer 200

FieldTypeMeaning
dst_account_idstring (uuid)
dst_namestring
dst_pathstring
enabledboolean
every_minutesinteger
idstring (uuid)
last_errorstring (optional)
last_reconciled_atstring (date-time) (optional)
last_run_atstring (date-time) (optional)
last_statusJobStatus (optional)
liveLiveOut
modestring
peopleinteger
shared_drivesboolean
spacesinteger
tenant_account_idstring (uuid)
tenant_namestring

GET /api/v1/schedules

List Schedules

Every schedule the caller can see. Capped per person, so never paged.

Answer 200

list of Schedule

POST /api/v1/schedules

Create Schedule

A transfer on a timetable. Send ``Idempotency-Key`` so a retry makes one, not two.

Body (JSON)

FieldTypeMeaning
chat_archive optionalArchiveSpec (optional)
cronstring
database_backup optionalDumpSpec (optional)
email optionalEmailSpec (optional)
enabled optionalboolean
namestring
team_delta optionalstring (uuid) (optional)
timezone optionalstring
transfer optionalTransferIn (optional)

Answer 201

object

GET /api/v1/schedules/{schedule_id}

Get Schedule

Parameters

NameTypeMeaning
schedule_id pathstring (uuid)

Answer 200

FieldTypeMeaning
cronstring
enabledboolean
idstring (uuid)
kindstring
last_errorstring (optional)
last_run_atstring (date-time) (optional)
last_statusstring (optional)
namestring
next_run_atstring (date-time)
timezonestring
transferScheduleTransfer
triggerstring
upcominglist of string (date-time)

PATCH /api/v1/schedules/{schedule_id}

Edit Schedule

Rename it, retime it, or switch it on or off. What it runs is changed in the web app.

Parameters

NameTypeMeaning
schedule_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
cron optionalstring (optional)
enabled optionalboolean (optional)
name optionalstring (optional)
timezone optionalstring (optional)

Answer 200

FieldTypeMeaning
cronstring
enabledboolean
idstring (uuid)
kindstring
last_errorstring (optional)
last_run_atstring (date-time) (optional)
last_statusstring (optional)
namestring
next_run_atstring (date-time)
timezonestring
transferScheduleTransfer
triggerstring
upcominglist of string (date-time)

DELETE /api/v1/schedules/{schedule_id}

Delete Schedule

Parameters

NameTypeMeaning
schedule_id pathstring (uuid)

Answer 204

No body.

POST /api/v1/schedules/{schedule_id}/run

Run Schedule

Run it now, as its timetable would. Answers with the transfer it started.

Parameters

NameTypeMeaning
schedule_id pathstring (uuid)

Answer 202

FieldTypeMeaning
bytes_doneinteger
bytes_totalinteger
certificate optionalboolean
created_atstring (date-time)
cutover optionalboolean
destination_cloud_idstring (uuid) (optional)
destination_pathstring
errorstring (optional)
files_doneinteger
files_totalinteger
finished_atstring (date-time) (optional)
idstring (uuid)
kindstring
modestring
name optionalstring (optional)
report optionalboolean
source_cloud_idstring (uuid) (optional)
source_pathstring
started_atstring (date-time) (optional)
statusstring

POST /api/v1/schedules/{schedule_id}/trigger

Create Trigger

A URL that runs this schedule when POSTed to; replaces any earlier one. Shown once.

Parameters

NameTypeMeaning
schedule_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
signed optionalboolean

Answer 201

FieldTypeMeaning
existsboolean
last_fired_at optionalstring (date-time) (optional)
prefix optionalstring (optional)
signed optionalboolean
signing_secret optionalstring (optional)
urlstring

DELETE /api/v1/schedules/{schedule_id}/trigger

Delete Trigger

Parameters

NameTypeMeaning
schedule_id pathstring (uuid)

Answer 204

No body.

Notifications

GET /api/v1/notifications

Channels

Answer 200

list of ChannelOut

POST /api/v1/notifications

Add Channel

Email (to the account's own address), a webhook, Slack or Discord. A webhook's signing secret is in this answer and never again.

Body (JSON)

FieldTypeMeaning
eventslist of string
kind optional"webhook" | "slack" | "discord" | "email" | "push"
namestring
subscription optionalPushSubscriptionIn (optional)
url optionalstring (optional)

Answer 201

FieldTypeMeaning
created_atstring (date-time)
enabledboolean
eventslist of string
failure_countinteger
idstring (uuid)
kindstring
last_delivery_atstring (date-time) (optional)
last_errorstring (optional)
namestring
secretstring (optional)
targetstring

GET /api/v1/notifications/events

Events

What a channel can subscribe to.

Answer 200

object

GET /api/v1/notifications/kinds

Kinds

The kinds this server can deliver and an app can set up.

Answer 200

FieldTypeMeaning
kindslist of string

POST /api/v1/notifications/telegram/link

Telegram Link

A link that opens the bot in Telegram; pressing Start there makes the channel.

Body (JSON)

FieldTypeMeaning
eventslist of string
namestring

Answer 201

FieldTypeMeaning
codestring
expires_ininteger
urlstring

PATCH /api/v1/notifications/{channel_id}

Change Channel

Rename, change the events, or switch it on or off.

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
enabled optionalboolean (optional)
events optionallist of string (optional)
name optionalstring (optional)

Answer 200

FieldTypeMeaning
created_atstring (date-time)
enabledboolean
eventslist of string
failure_countinteger
idstring (uuid)
kindstring
last_delivery_atstring (date-time) (optional)
last_errorstring (optional)
namestring
targetstring

DELETE /api/v1/notifications/{channel_id}

Remove Channel

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Answer 204

No body.

GET /api/v1/notifications/{channel_id}/deliveries

Deliveries

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Answer 200

list of DeliveryOut

POST /api/v1/notifications/{channel_id}/deliveries/{delivery_id}/replay

Replay

Parameters

NameTypeMeaning
delivery_id pathstring (uuid)
channel_id pathstring (uuid)

Answer 202

object

POST /api/v1/notifications/{channel_id}/secret

New Secret

A webhook's new signing secret, shown once; the old one keeps working for a while.

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Answer 200

FieldTypeMeaning
previous_valid_untilstring (date-time)
secretstring

POST /api/v1/notifications/{channel_id}/test

Test Channel

Send a test event now, through the real delivery path.

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Answer 202

object

Security

GET /api/v1/security/activity

Activity

Sign-ins and changes to the account, newest first. Pass ``next_before`` as ``before``.

Parameters

NameTypeMeaning
before query, optionalinteger (optional)
limit query, optionalinteger

Answer 200

FieldTypeMeaning
itemslist of ActivityItem
next_beforeinteger (optional)

GET /api/v1/security/app-passwords

App Passwords

Answer 200

list of AppPasswordOut

POST /api/v1/security/app-passwords

Create App Password

A password for the network drive or SFTP, given the password or a code. Shown once.

Body (JSON)

FieldTypeMeaning
account_id optionalstring (uuid) (optional)
code optionalstring (optional)
folder optionalstring
namestring
password optionalstring (optional)
read_only optionalboolean

Answer 201

FieldTypeMeaning
account_idstring (uuid) (optional)
created_atstring (date-time)
folderstring
idstring (uuid)
last_used_atstring (date-time) (optional)
namestring
passwordstring
prefixstring
read_onlyboolean

DELETE /api/v1/security/app-passwords/{password_id}

Revoke App Password

Parameters

NameTypeMeaning
password_id pathstring (uuid)

Answer 204

No body.

GET /api/v1/security/passkeys

Passkeys

Answer 200

FieldTypeMeaning
enabledboolean
freshboolean
passkeyslist of PasskeyOut

PATCH /api/v1/security/passkeys/{passkey_id}

Rename Passkey

Parameters

NameTypeMeaning
passkey_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
namestring

Answer 200

FieldTypeMeaning
created_atstring (date-time)
idstring (uuid)
last_used_atstring (date-time) (optional)
namestring
syncedboolean

POST /api/v1/security/passkeys/{passkey_id}/remove

Remove Passkey

Parameters

NameTypeMeaning
passkey_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
code optionalstring (optional)
password optionalstring (optional)

Answer 204

No body.

GET /api/v1/security/tokens

Tokens

Answer 200

list of TokenOut

POST /api/v1/security/tokens

Create Token

A new personal token, given the password or a code. The token itself is in this answer and never again; no ``Idempotency-Key`` replay keeps a copy of it.

Body (JSON)

FieldTypeMeaning
code optionalstring (optional)
expires_in_days optional30 | 90 | 365
namestring
password optionalstring (optional)
scope optionalTokenScope

Answer 201

FieldTypeMeaning
created_atstring (date-time)
expiredboolean
expires_atstring (date-time) (optional)
idstring (uuid)
last_used_atstring (date-time) (optional)
namestring
prefixstring
scopestring
tokenstring

DELETE /api/v1/security/tokens/{token_id}

Revoke Token

Parameters

NameTypeMeaning
token_id pathstring (uuid)

Answer 204

No body.

GET /api/v1/security/two-factor

Two Factor

Answer 200

FieldTypeMeaning
enabledboolean
enabled_atstring (date-time) (optional)
factors optionallist of "totp" | "passkey"
recovery_codes_leftinteger

POST /api/v1/security/two-factor/disable

Two Factor Disable

Body (JSON)

FieldTypeMeaning
code optionalstring (optional)
password optionalstring (optional)

Answer 204

No body.

POST /api/v1/security/two-factor/enable

Two Factor Enable

Confirm with a code from the authenticator. Answers the recovery codes, shown once, and signs every browser out.

Body (JSON)

FieldTypeMeaning
codestring

Answer 200

FieldTypeMeaning
recovery_codeslist of string

POST /api/v1/security/two-factor/recovery-codes

Two Factor Recovery Codes

Replace every recovery code, given a code (a recovery code will do). Shown once.

Body (JSON)

FieldTypeMeaning
codestring

Answer 200

FieldTypeMeaning
recovery_codeslist of string

POST /api/v1/security/two-factor/setup

Two Factor Setup

A secret to put in the authenticator, shown once. ``otpauth_uri`` opens an authenticator app on the same phone. Nothing changes at sign-in until a code confirms it.

Answer 200

FieldTypeMeaning
otpauth_uristring
qr_svgstring
secretstring

Shares

GET /api/v1/shares

List Shares

Answer 200

list of Share

POST /api/v1/shares

Create Share

A link anybody holding it can download from, until it expires or is revoked.

Body (JSON)

FieldTypeMeaning
cloud_idstring (uuid)
expires_in_hours optionalinteger
max_downloads optionalinteger (optional)
password optionalstring (optional)
pathstring

Answer 201

object

DELETE /api/v1/shares/{share_id}

Revoke Share

Parameters

NameTypeMeaning
share_id pathstring (uuid)

Answer 204

No body.

Support

GET /api/v1/support/attachments/{attachment_id}

Attachment

A file from one of the person's tickets.

Parameters

NameTypeMeaning
attachment_id pathstring (uuid)

Answer 200

object

POST /api/v1/support/chat

Chat

Start a live chat: a ticket on the chat channel. Asked when nobody is available too; replies then come by email. Send ``Idempotency-Key``.

Body (JSON)

FieldTypeMeaning
bodystring
category optionalstring
context optionalobject

Answer 201

object

GET /api/v1/support/info

Info

What Help offers: tickets, chat and whether anybody is there, the email address, the categories and what a file may be.

Answer 200

FieldTypeMeaning
attachment_typeslist of string
categoriesobject
chat_enabledboolean
chat_onlineboolean
emailstring
enabledboolean
max_attachment_bytesinteger
max_attachments_per_messageinteger
prioritieslist of string

POST /api/v1/support/messages/{message_id}/attachments

Attach

One file for a message the person has just sent: the body is the file, ``?name=`` its name. The types and size ``/info`` lists.

Parameters

NameTypeMeaning
message_id pathstring (uuid)
name querystring

Answer 201

FieldTypeMeaning
content_typestring
filenamestring
idstring (uuid)
inlineboolean
sizeinteger

GET /api/v1/support/tickets

Tickets

The person's tickets, the most recently active first.

Answer 200

list of TicketSummary

POST /api/v1/support/tickets

Open Ticket

Open a ticket with its first message. Send ``Idempotency-Key`` so a retry opens one.

Body (JSON)

FieldTypeMeaning
bodystring
categorystring
context optionalobject
priority optionalstring
subjectstring

Answer 201

object

GET /api/v1/support/tickets/{ticket_id}

Ticket

The whole thread; reading it marks it read.

Parameters

NameTypeMeaning
ticket_id pathstring (uuid)

Answer 200

FieldTypeMeaning
categorystring
channelstring
created_atstring (date-time)
idstring (uuid)
last_activity_atstring (date-time)
messageslist of MessageOut
numberinteger
prioritystring
ratinginteger (optional)
rating_commentstring (optional)
statusstring
subjectstring
typing optionalboolean
unreadboolean

POST /api/v1/support/tickets/{ticket_id}/close

Close

Parameters

NameTypeMeaning
ticket_id pathstring (uuid)

Answer 200

FieldTypeMeaning
categorystring
channelstring
created_atstring (date-time)
idstring (uuid)
last_activity_atstring (date-time)
messageslist of MessageOut
numberinteger
prioritystring
ratinginteger (optional)
rating_commentstring (optional)
statusstring
subjectstring
typing optionalboolean
unreadboolean

POST /api/v1/support/tickets/{ticket_id}/messages

Reply

A reply. Files follow it at ``/messages/{id}/attachments``, one per request.

Parameters

NameTypeMeaning
ticket_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
bodystring

Answer 201

FieldTypeMeaning
attachmentslist of AttachmentOut
authorstring
bodystring
created_atstring (date-time)
idstring (uuid)
kindstring
mineboolean

POST /api/v1/support/tickets/{ticket_id}/rating

Rate

How the help was, 1 to 5, once the ticket is solved or closed.

Parameters

NameTypeMeaning
ticket_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
comment optionalstring (optional)
ratinginteger

Answer 200

FieldTypeMeaning
categorystring
channelstring
created_atstring (date-time)
idstring (uuid)
last_activity_atstring (date-time)
messageslist of MessageOut
numberinteger
prioritystring
ratinginteger (optional)
rating_commentstring (optional)
statusstring
subjectstring
typing optionalboolean
unreadboolean

POST /api/v1/support/tickets/{ticket_id}/reopen

Reopen

Parameters

NameTypeMeaning
ticket_id pathstring (uuid)

Answer 200

FieldTypeMeaning
categorystring
channelstring
created_atstring (date-time)
idstring (uuid)
last_activity_atstring (date-time)
messageslist of MessageOut
numberinteger
prioritystring
ratinginteger (optional)
rating_commentstring (optional)
statusstring
subjectstring
typing optionalboolean
unreadboolean

GET /api/v1/support/tickets/{ticket_id}/since

Since

What is new since ``after``, with the status and whether the desk is typing: the poll of an open ticket or chat.

Parameters

NameTypeMeaning
ticket_id pathstring (uuid)
after query, optionalstring (date-time) (optional)

Answer 200

FieldTypeMeaning
categorystring
channelstring
created_atstring (date-time)
idstring (uuid)
last_activity_atstring (date-time)
messageslist of MessageOut
numberinteger
prioritystring
ratinginteger (optional)
rating_commentstring (optional)
statusstring
subjectstring
typing optionalboolean
unreadboolean

POST /api/v1/support/tickets/{ticket_id}/typing

Typing

Parameters

NameTypeMeaning
ticket_id pathstring (uuid)

Answer 200

object

Telegram

POST /api/v1/telegram/archives

Archive

Save a chat as a readable archive in a cloud folder; each run carries on from where the last stopped (on a schedule: ``POST /schedules`` with ``chat_archive``). A transfer to follow.

Body (JSON)

FieldTypeMeaning
dst_account_idstring (uuid)
dst_path optionalstring
max_file_mb optionalinteger
media optional"all" | "photos" | "none"
src_account_idstring (uuid)
src_path optionalstring

Answer 202

object

GET /api/v1/telegram/clones

List Clones

Every clone: source and destination chat, status, pace, filters, what it has copied, and its group if it was made in a batch.

Answer 200

list of CloneOut

POST /api/v1/telegram/clones

Create Clone

Copy one chat's files into another, paced, from ``start`` (all, the last, only new, or where a deleted clone stopped), then keep following it if ``follow``.

Body (JSON)

FieldTypeMeaning
account_idstring (uuid)
destinationstring
follow optionalboolean
hide_sender optionalboolean
interval_seconds optionalinteger
kinds optionallist of "text" | "photo" | "video" | "audio" | "document" | "other"
last_count optionalinteger
max_size optionalinteger (optional)
min_size optionalinteger (optional)
skip_existing optionalboolean
sourcestring
start optional"all" | "last" | "new" | "resume"

Answer 201

object

POST /api/v1/telegram/clones/batch

Create Clones

Many clones at once, as one group sharing a pace.

Body (JSON)

FieldTypeMeaning
account_idstring (uuid)
destinationslist of string
follow optionalboolean
hide_sender optionalboolean
interval_seconds optionalinteger
kinds optionallist of "text" | "photo" | "video" | "audio" | "document" | "other"
last_count optionalinteger
max_size optionalinteger (optional)
min_size optionalinteger (optional)
pairs optionallist of list of (optional)
resume optionalboolean
skip_existing optionalboolean
sourceslist of string
start optional"all" | "last" | "new"

Answer 201

object

PATCH /api/v1/telegram/clones/groups/{group_id}

Update Group

Pause or resume a whole group, or change its shared pace.

Parameters

NameTypeMeaning
group_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
interval_seconds optionalinteger (optional)
status optional"active" | "paused" (optional)

Answer 200

list of CloneOut

DELETE /api/v1/telegram/clones/groups/{group_id}

Delete Group

Parameters

NameTypeMeaning
group_id pathstring (uuid)

Answer 204

No body.

GET /api/v1/telegram/clones/position

Clone Position

Where an earlier clone of these two chats stopped, for ``start`` ``resume``.

Parameters

NameTypeMeaning
account_id querystring (uuid)
source querystring
destination querystring

Answer 200

FieldTypeMeaning
clonePairCloneOut (optional)
savedSavedOut (optional)

POST /api/v1/telegram/clones/preview

Preview Clones

The pairs a batch of sources and destinations would make, and any already running.

Body (JSON)

FieldTypeMeaning
account_idstring (uuid)
destinationslist of string
sourceslist of string

Answer 200

FieldTypeMeaning
pairslist of PairOut

PATCH /api/v1/telegram/clones/{clone_id}

Update Clone

Pause or resume it, change its pace, what it copies, or whether it follows on.

Parameters

NameTypeMeaning
clone_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
follow optionalboolean (optional)
hide_sender optionalboolean (optional)
interval_seconds optionalinteger (optional)
kinds optionallist of "text" | "photo" | "video" | "audio" | "document" | "other" (optional)
max_size optionalinteger (optional)
min_size optionalinteger (optional)
skip_existing optionalboolean (optional)
status optional"active" | "paused" (optional)

Answer 200

FieldTypeMeaning
account_idstring
account_namestring
charged_bytes optionalinteger
created_atstring (date-time)
cursorinteger
destinationEndOut
end_idinteger
failedinteger
files_charged optionalinteger
followboolean
forwardedinteger
group_id optionalstring (optional)
group_interval_seconds optionalinteger (optional)
hide_senderboolean
idstring
interval_secondsinteger
kindslist of string
last_errorstring (optional)
last_forwarded_atstring (date-time) (optional)
max_sizeinteger (optional)
min_sizeinteger (optional)
next_atstring (date-time)
phasestring
skip_existing optionalboolean
skippedinteger
sourceEndOut
start_cursorinteger
statusstring
wait_untilstring (date-time) (optional)

DELETE /api/v1/telegram/clones/{clone_id}

Delete Clone

Stop and forget it; what it copied stays, and its position is kept for a resume.

Parameters

NameTypeMeaning
clone_id pathstring (uuid)

Answer 204

No body.

GET /api/v1/telegram/clones/{clone_id}/events

Clone Events

What the clone has done lately, newest first.

Parameters

NameTypeMeaning
clone_id pathstring (uuid)

Answer 200

list of EventOut

GET /api/v1/telegram/duplicates

List Scans

Every duplicate scan of a chat: its progress, what it found, what was deleted.

Answer 200

list of DuplicateScanOut

POST /api/v1/telegram/duplicates

Start Scan

Read a chat for the same file posted more than once (by the file, or also by name).

Body (JSON)

FieldTypeMeaning
account_idstring (uuid)
chatstring
match optional"file" | "file_or_name"

Answer 201

object

GET /api/v1/telegram/duplicates/{scan_id}

Get Scan

Parameters

NameTypeMeaning
scan_id pathstring (uuid)

Answer 200

FieldTypeMeaning
account_idstring
account_namestring
chatChatOut
created_atstring (date-time)
deletedinteger
duplicatesinteger
errorstring (optional)
groupsinteger
idstring
matchstring
newest_idinteger
scannedinteger
statusstring
to_deleteinteger
updated_atstring (date-time)

DELETE /api/v1/telegram/duplicates/{scan_id}

Forget Scan

Parameters

NameTypeMeaning
scan_id pathstring (uuid)

Answer 204

No body.

POST /api/v1/telegram/duplicates/{scan_id}/cancel

Cancel Scan

Parameters

NameTypeMeaning
scan_id pathstring (uuid)

Answer 200

FieldTypeMeaning
account_idstring
account_namestring
chatChatOut
created_atstring (date-time)
deletedinteger
duplicatesinteger
errorstring (optional)
groupsinteger
idstring
matchstring
newest_idinteger
scannedinteger
statusstring
to_deleteinteger
updated_atstring (date-time)

POST /api/v1/telegram/duplicates/{scan_id}/delete

Delete Duplicates

Delete every copy but the first in each group, except the groups in ``skip_groups``. The messages are deleted in Telegram.

Parameters

NameTypeMeaning
scan_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
skip_groups optionallist of integer

Answer 200

FieldTypeMeaning
account_idstring
account_namestring
chatChatOut
created_atstring (date-time)
deletedinteger
duplicatesinteger
errorstring (optional)
groupsinteger
idstring
matchstring
newest_idinteger
scannedinteger
statusstring
to_deleteinteger
updated_atstring (date-time)

GET /api/v1/telegram/duplicates/{scan_id}/groups

Scan Groups

A page of what the scan found, most copies first.

Parameters

NameTypeMeaning
scan_id pathstring (uuid)
offset query, optionalinteger
limit query, optionalinteger

Answer 200

FieldTypeMeaning
groupslist of GroupOut
totalinteger

GET /api/v1/telegram/pricing

Pricing

What a cloned file counts against the allowance.

Answer 200

FieldTypeMeaning
bytes_per_fileinteger
files_leftinteger (optional)
files_per_gbinteger
remaining_bytesinteger (optional)

GET /api/v1/telegram/{account_id}/access

Access

Whether the workers can sign in as this account on their own, and whether a two-step password is saved for them -- never the password.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Answer 200

FieldTypeMeaning
password_savedboolean
workerslist of WorkerSessionOut

GET /api/v1/telegram/{account_id}/chats

Chats

Every chat at the root (``path`` empty); the files in one below it, newest first, a page at a time (``before`` the oldest message id seen).

Parameters

NameTypeMeaning
account_id pathstring (uuid)
path query, optionalstring
before query, optionalinteger
limit query, optionalinteger

Answer 200

FieldTypeMeaning
chats optionallist of ChatOut
files optionallist of FileOut
max_file_size optionalinteger
next_before optionalinteger
pathstring
premium optionalboolean

PUT /api/v1/telegram/{account_id}/password

Save Password

Save the account's two-step password, so the workers can sign in as it. Checked against Telegram first.

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
passwordstring

Answer 204

No body.

DELETE /api/v1/telegram/{account_id}/password

Forget Password

Parameters

NameTypeMeaning
account_id pathstring (uuid)

Answer 204

No body.

Webhooks

GET /api/v1/webhooks

List Webhooks

Answer 200

list of Webhook

POST /api/v1/webhooks

Create Webhook

Body (JSON)

FieldTypeMeaning
eventslist of string
namestring
urlstring

Answer 201

object

GET /api/v1/webhooks/events

List Events

The events a webhook may subscribe to.

Answer 200

list of string

DELETE /api/v1/webhooks/{channel_id}

Delete Webhook

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Answer 204

No body.

GET /api/v1/webhooks/{channel_id}/deliveries

List Deliveries

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Answer 200

list of DeliveryOut

POST /api/v1/webhooks/{channel_id}/deliveries/{delivery_id}/replay

Replay Delivery

Parameters

NameTypeMeaning
delivery_id pathstring (uuid)
channel_id pathstring (uuid)

Answer 202

object

POST /api/v1/webhooks/{channel_id}/secret

Rotate Secret

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Answer 200

FieldTypeMeaning
previous_valid_untilstring (date-time)
secretstring

POST /api/v1/webhooks/{channel_id}/test

Test Webhook

Send a ``notification.test`` event now, through the real delivery path.

Parameters

NameTypeMeaning
channel_id pathstring (uuid)

Answer 202

object

Workspaces

GET /api/v1/workspaces

List Workspaces

The owner's encrypted workspaces, where each is stored and who it is shared with. Their files are read as a cloud, under /clouds; the people in them reach them the same way.

Answer 200

list of Workspace

POST /api/v1/workspaces

Make Workspace

Encrypt a folder of one of the owner's clouds with a key made here, and share it. Send ``Idempotency-Key`` so a retry makes one.

Body (JSON)

FieldTypeMeaning
account_idstring (uuid)
namestring
names optional"standard" | "off"
path optionalstring
people optionallist of app__api__routes__workspaces__PersonIn

Answer 201

object

GET /api/v1/workspaces/discussions

My Discussions

Every workspace this person may talk in -- their own and those shared with them -- with how many messages they have not read.

Answer 200

list of WorkspaceSummary

GET /api/v1/workspaces/people

List People

The owner's people (sub-accounts), to choose who a workspace is shared with.

Answer 200

list of Person

GET /api/v1/workspaces/{workspace_id}/activity

Activity

Files added or changed in the last fortnight, newest first (100 at most).

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)

Answer 200

list of ActivityOut

GET /api/v1/workspaces/{workspace_id}/discussion

Read Stream

The newest messages, oldest first, with the members; ``path`` gives one file's comments, ``before`` (a message's ``created_at``) pages back.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)
path query, optionalstring (optional)
before query, optionalstring (date-time) (optional)

Answer 200

FieldTypeMeaning
memberslist of WorkspaceMemberOut
messageslist of WorkspaceMessageOut
workspaceWorkspaceSummary

POST /api/v1/workspaces/{workspace_id}/discussion

Post Message

Say something: to everybody, in reply to a message (``parent_id``), or about a file of the workspace (``path``). ``mentions`` are members' ids; they are told by email.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
mentions optionallist of string (uuid)
parent_id optionalstring (uuid) (optional)
path optionalstring (optional)
textstring

Answer 201

FieldTypeMeaning
authorstring
author_idstring (uuid) (optional)
created_atstring (date-time)
deletedboolean
edited_atstring (date-time) (optional)
idstring (uuid)
mentionslist of string (uuid)
parent_idstring (uuid) (optional)
pathstring (optional)
reactionsobject
textstring

GET /api/v1/workspaces/{workspace_id}/discussion/events

Events

Server-sent events as the discussion changes: ``change`` with a type and a message id (never the words), ``gone`` when this person is removed, ``timeout`` after 30 minutes.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)

Answer 200

object

POST /api/v1/workspaces/{workspace_id}/discussion/export

Export

Save the whole discussion as one HTML page into the workspace, encrypted there like every other file. Members who can write only.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)

Answer 200

FieldTypeMeaning
namestring

POST /api/v1/workspaces/{workspace_id}/discussion/read

Mark Read

Everything said so far is read.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)

Answer 204

No body.

PATCH /api/v1/workspaces/{workspace_id}/discussion/{message_id}

Edit Message

Change one's own words.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)
message_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
textstring

Answer 200

FieldTypeMeaning
authorstring
author_idstring (uuid) (optional)
created_atstring (date-time)
deletedboolean
edited_atstring (date-time) (optional)
idstring (uuid)
mentionslist of string (uuid)
parent_idstring (uuid) (optional)
pathstring (optional)
reactionsobject
textstring

DELETE /api/v1/workspaces/{workspace_id}/discussion/{message_id}

Delete Message

Take one's own message down; the owner may take anybody's (audited).

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)
message_id pathstring (uuid)

Answer 204

No body.

POST /api/v1/workspaces/{workspace_id}/discussion/{message_id}/reactions

React

Add this person's reaction, or take it back when it is there. Answers every reaction on the message, each with who gave it.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)
message_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
emojistring

Answer 200

object

POST /api/v1/workspaces/{workspace_id}/members

Add Member

Share the workspace with one of the owner's people.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
can_write optionalboolean
user_idstring (uuid)

Answer 201

FieldTypeMeaning
can_writeboolean
emailstring
user_idstring (uuid)

PATCH /api/v1/workspaces/{workspace_id}/members/{user_id}

Change Member

Let a member write, or make them a reader. Taking write away stops the work that relied on it, as on the website.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)
user_id pathstring (uuid)

Body (JSON)

FieldTypeMeaning
can_writeboolean

Answer 200

FieldTypeMeaning
can_writeboolean
emailstring
user_idstring (uuid)

DELETE /api/v1/workspaces/{workspace_id}/members/{user_id}

Remove Member

Take the workspace back from somebody: their discussion stream ends, work they had running in it stops and links they made into it are turned off.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)
user_id pathstring (uuid)

Answer 204

No body.

GET /api/v1/workspaces/{workspace_id}/recovery

Recovery File

The rclone config that opens the workspace without ShiftMyData. It is the key: keep it secret. Audited.

Parameters

NameTypeMeaning
workspace_id pathstring (uuid)

Answer 200

object