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
- Apps and websites: OAuth 2.1 authorization code with PKCE (
S256only) at/oauth/authorize, tokens at/api/oauth/token. Redirect addresses match exactly; native apps may use a loopback address on any port. - Command-line tools: the device flow (RFC 8628) at
/api/oauth/device_authorization; the person types the code atshiftmydata.com/oauth/device. - Servers: client credentials, proving the client with a signed JWT (
private_key_jwt, ES256 or EdDSA) -- no shared secret. Integrations that cannot sign may use a client secret. - Scripts: a personal API token from the Security page, sent as
Authorization: Bearer.
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
| Scope | Lets the app |
|---|---|
clouds:read | See which clouds you have connected |
files:read | List, search and download your files |
files:write | Upload, copy, move, rename and delete your files |
offline_access | Stay signed in when you are not using it |
profile | See your name, email address and plan |
schedules:read | See your schedules |
schedules:write | Create, change, run and delete schedules |
transfers:read | See your transfers and their progress |
transfers:write | Start, pause and cancel transfers |
webhooks | Send your transfer and schedule events to an address you choose |
workspaces:read | Read your encrypted workspaces and their discussion |
workspaces:write | Post 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
- Paging: lists answer
{"items": [...], "next_cursor": "..."}; pass the cursor back as?cursor=. Cursors are opaque. - Retries: send
Idempotency-Keywith a POST that creates something; a retry with the same key gets the first answer (Idempotent-Replayed: true). - Limits: every answer carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset; over the limit is429withRetry-After. - Errors:
{"detail": "..."}in words; a missing scope is403withWWW-Authenticate: Bearer error="insufficient_scope".
Ready-made clients
- Command line:
pipx install shiftmydata, thenshiftmydata login-- list, copy, sync, upload, download, save from the web, run schedules;--jsonfor scripts. - JavaScript and TypeScript:
npm install shiftmydata-- a typed client with no dependencies, for scripts and servers holding an API token: transfers, files, schedules, share links, andverifyWebhookto check each delivery. - n8n: the community node
n8n-nodes-shiftmydata, with a trigger that verifies each delivery's signature. - Zapier: a trigger for transfer events and actions to start transfers, save links and run schedules.
- Browser extension: save a link, image, video or page into a folder from Chrome, Edge or Firefox.
- Webhooks: signed to the Standard Webhooks format (
webhook-id,webhook-timestamp,webhook-signature), retried for about three days, with a delivery log and replay.
Endpoints
- Account
- People
- Transfers
- Clouds
- Files
- Developers
- Schedules
- Notifications
- Security
- Shares
- Support
- Telegram
- Webhooks
- Workspaces
Account
GET /api/v1/account
Profile
Answer 200
| Field | Type | Meaning |
|---|---|---|
account_url | string | |
email | string | |
email_verified | boolean | |
google_linked | boolean | |
has_password | boolean | |
mail_configured | boolean | |
name | string | |
passkeys_enabled | boolean | |
role | "owner" | "admin" | "member" | "viewer" | |
security_url | string | |
sub_account | boolean |
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)
| Field | Type | Meaning |
|---|---|---|
confirm_email optional | string (optional) | |
password optional | string (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)
| Field | Type | Meaning |
|---|---|---|
current_password | string | |
new_password | string |
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
| Field | Type | Meaning |
|---|---|---|
status optional | "accepted" |
GET /api/v1/me
Me
Answer 200
| Field | Type | Meaning |
|---|---|---|
created_at | string (date-time) | |
email | string | |
id | string (uuid) | |
scope | string | |
sub_account | boolean |
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)
| Field | Type | Meaning |
|---|---|---|
code | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
bytes_granted | integer | |
total_granted | integer |
GET /api/v1/me/drive
Drive
Answer 200
| Field | Type | Meaning |
|---|---|---|
app_passwords_url | string | |
drive_address | string | |
drive_enabled | boolean | |
sftp_address | string | |
sftp_enabled | boolean | |
username | string |
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
| Field | Type | Meaning |
|---|---|---|
billed_to | string | |
gstin | string | |
receipts | list of ReceiptOut | |
seller_address | string | |
seller_name | string | |
tax_invoice | boolean |
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
| Field | Type | Meaning |
|---|---|---|
bytes_earned | integer | |
code | string | |
enabled | boolean | |
hold_days | integer | |
invited | integer | |
link | string | |
pending | integer | |
rewarded | integer |
GET /api/v1/me/summary
Summary
Answer 200
| Field | Type | Meaning |
|---|---|---|
allowance_consumed_bytes optional | integer | |
allowance_expires_at | string (date-time) (optional) | |
allowance_granted_bytes | integer | |
allowance_in_use_bytes optional | integer | |
allowance_remaining_bytes | integer | |
clouds optional | integer (optional) | |
plan | string (optional) | |
transfers_running optional | integer (optional) | |
unlimited | boolean | |
used_bytes_this_month optional | integer |
People
GET /api/v1/audit
Events
Everything done in the organisation, newest first. Pass the last ``id`` as ``before``.
Parameters
| Name | Type | Meaning |
|---|---|---|
before query, optional | integer (optional) |
Answer 200
list of AuditEventOut
GET /api/v1/audit/settings
Settings
Answer 200
| Field | Type | Meaning |
|---|---|---|
retention_days | integer (optional) | |
webhook | string (optional) | |
webhook_delivered_at | string (date-time) (optional) | |
webhook_error | string (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)
| Field | Type | Meaning |
|---|---|---|
retention_days optional | integer (optional) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
retention_days | integer (optional) | |
webhook | string (optional) | |
webhook_delivered_at | string (date-time) (optional) | |
webhook_error | string (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)
| Field | Type | Meaning |
|---|---|---|
url | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
secret | string | |
settings | AuditSettingsOut |
DELETE /api/v1/audit/webhook
Remove Webhook
Answer 200
| Field | Type | Meaning |
|---|---|---|
retention_days | integer (optional) | |
webhook | string (optional) | |
webhook_delivered_at | string (date-time) (optional) | |
webhook_error | string (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)
| Field | Type | Meaning |
|---|---|---|
email | string (email) | |
label optional | string | |
password | string | |
role optional | "member" | "viewer" | "admin" |
Answer 202
| Field | Type | Meaning |
|---|---|---|
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
| Name | Type | Meaning |
|---|---|---|
person_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
is_active optional | boolean (optional) | |
label optional | string (optional) | |
password optional | string (optional) | |
role optional | "member" | "viewer" | "admin" (optional) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
created_at | string (date-time) | |
email | string (email) | |
grants | integer | |
held_jobs optional | integer | |
id | string (uuid) | |
is_active | boolean | |
label | string | |
last_login_at | string (date-time) (optional) | |
role optional | "member" | "viewer" | "admin" | |
tokens optional | integer |
DELETE /api/v1/people/{person_id}
Remove Person
Parameters
| Name | Type | Meaning |
|---|---|---|
person_id path | string (uuid) |
Answer 204
No body.
GET /api/v1/people/{person_id}/folders
Folders
The folders lent to this person.
Parameters
| Name | Type | Meaning |
|---|---|---|
person_id path | string (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
| Name | Type | Meaning |
|---|---|---|
person_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
can_write optional | boolean | |
path optional | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
account_name | string | |
can_write | boolean | |
created_at | string (date-time) | |
id | string (uuid) | |
path | string | |
replaced optional | list of string |
PATCH /api/v1/people/{person_id}/folders/{grant_id}
Change Folder
Parameters
| Name | Type | Meaning |
|---|---|---|
person_id path | string (uuid) | |
grant_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
can_write | boolean |
Answer 200
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
account_name | string | |
can_write | boolean | |
created_at | string (date-time) | |
id | string (uuid) | |
path | string |
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
| Name | Type | Meaning |
|---|---|---|
person_id path | string (uuid) | |
grant_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
jobs_cancelled | integer | |
shares_revoked | integer |
GET /api/v1/people/{person_id}/held-jobs
Held Jobs
Their transfers held when they were suspended.
Parameters
| Name | Type | Meaning |
|---|---|---|
person_id path | string (uuid) |
Answer 200
list of HeldJobOut
GET /api/v1/people/{person_id}/tokens
Person Tokens
Parameters
| Name | Type | Meaning |
|---|---|---|
person_id path | string (uuid) |
Answer 200
list of DelegateTokenOut
DELETE /api/v1/people/{person_id}/tokens/{token_id}
Revoke Person Token
Parameters
| Name | Type | Meaning |
|---|---|---|
person_id path | string (uuid) | |
token_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_collection optional | string | |
dst_path optional | string | |
src_account_id | string (uuid) | |
src_collections optional | list of string | |
src_path optional | string | |
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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_path optional | string | |
events optional | boolean | |
exclude optional | list of string | |
include optional | list of string | |
keep_last optional | integer | |
routines optional | boolean | |
src_account_id | string (uuid) | |
triggers optional | boolean |
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)
| Field | Type | Meaning |
|---|---|---|
confirm | string | |
drop optional | boolean | |
dst_account_id | string (uuid) | |
passphrase optional | string (optional) | |
src_account_id | string (uuid) | |
src_path | string |
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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
objects | list of DbObjectOut | |
reason | string (optional) | |
supported | boolean | |
truncated | boolean |
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)
| Field | Type | Meaning |
|---|---|---|
attachments optional | boolean | |
attachments_only optional | boolean | |
dst_account_id | string (uuid) | |
dst_path optional | string | |
filter optional | MailFilter (optional) | |
folders optional | list of string | |
format optional | "archive" | "mbox" | |
keep_original optional | boolean | |
since optional | string (date) (optional) | |
src_account_id | string (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)
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_path optional | string | |
restore_into optional | string (uuid) (optional) | |
restore_path optional | string | |
src_account_id | string (uuid) | |
src_path | string |
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)
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_path optional | string | |
src_account_id | string (uuid) | |
src_path optional | string |
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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
folders | list of FolderOut | |
suggested | list 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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
people | list of PersonOut | |
truncated | boolean |
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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
people | list of app__api__routes__accounts__organisation__PersonIn |
Answer 201
| Field | Type | Meaning |
|---|---|---|
created | list of Cloud | |
skipped | list 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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
ids | list of string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
created | list of Cloud | |
skipped | list 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)
| Field | Type | Meaning |
|---|---|---|
destination_cloud_id | string (uuid) | |
destination_path optional | string | |
kind optional | "file" | "video" | "page" | "image" | |
name optional | string (optional) | |
url | string |
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)
| Field | Type | Meaning |
|---|---|---|
destination_cloud_id | string (uuid) | |
destination_path optional | string | |
magnet optional | string (optional) | |
torrent optional | string (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)
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_path optional | string | |
exclude optional | list of string | |
exclude_types optional | list of string | |
include optional | list of string | |
include_types optional | list of string | |
max_size optional | integer (optional) | |
min_size optional | integer (optional) | |
modified_after optional | string (date-time) (optional) | |
modified_before optional | string (date-time) (optional) | |
older_than_days optional | integer (optional) | |
src_account_id | string (uuid) | |
src_path optional | string |
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)
| Field | Type | Meaning |
|---|---|---|
large_mb optional | integer | |
older_than_days optional | integer | |
places | list 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)
| Field | Type | Meaning |
|---|---|---|
min_kb optional | integer | |
places | list 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)
| Field | Type | Meaning |
|---|---|---|
certificate optional | boolean | |
certificate_download optional | boolean | |
concurrency optional | integer | |
exclude optional | list of string | |
fix_names optional | boolean | |
include optional | list of string | |
max_size optional | integer (optional) | |
members | list of TeamMember | |
min_size optional | integer (optional) | |
mode optional | TransferMode | |
name optional | string | |
report optional | boolean | |
verify_checksum optional | boolean |
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)
| Field | Type | Meaning |
|---|---|---|
certificate optional | boolean | |
certificate_download optional | boolean | |
concurrency optional | integer | |
exclude optional | list of string | |
fix_names optional | boolean | |
include optional | list of string | |
max_size optional | integer (optional) | |
members | list of TeamMember | |
min_size optional | integer (optional) | |
mode optional | TransferMode | |
name optional | string | |
report optional | boolean | |
verify_checksum optional | boolean |
Answer 200
| Field | Type | Meaning |
|---|---|---|
concurrency | integer | |
members | list of MemberPlan | |
mode | TransferMode | |
name | string | |
warnings | list 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
| Name | Type | Meaning |
|---|---|---|
cursor query, optional | string (optional) | |
limit query, optional | integer |
Answer 200
| Field | Type | Meaning |
|---|---|---|
items | list of Transfer | |
next_cursor optional | string (optional) |
POST /api/v1/transfers
Start Transfer
Start a transfer. Send ``Idempotency-Key`` so a retry cannot start a second one.
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
certificate optional | boolean | |
certificate_download optional | boolean | |
conflict optional | ConflictRule (optional) | |
destination_cloud_id | string (uuid) | |
destination_path optional | string | |
exclude optional | list of string | |
exclude_types optional | list of string | |
fix_names optional | boolean | |
google_docs optional | "office" | "pdf" | "opendocument" | "skip" | |
include optional | list of string | |
include_types optional | list of string | |
keep_sharing optional | boolean | |
max_delete optional | integer (optional) | |
max_size optional | integer (optional) | |
min_size optional | integer (optional) | |
mode optional | "copy" | "mirror" | "move" | "cumulative" | "update" | "incremental_backup" | "full_backup" | "two_way" | "real_time" | |
modified_after optional | string (date-time) (optional) | |
modified_before optional | string (date-time) (optional) | |
report optional | boolean | |
source_cloud_id | string (uuid) | |
source_path optional | string | |
verify_checksum optional | boolean |
Answer 202
object
POST /api/v1/transfers/plan
Plan Transfer
What a transfer would do, before it is started. Starts nothing.
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
certificate optional | boolean | |
certificate_download optional | boolean | |
conflict optional | ConflictRule (optional) | |
destination_cloud_id | string (uuid) | |
destination_path optional | string | |
exclude optional | list of string | |
exclude_types optional | list of string | |
fix_names optional | boolean | |
google_docs optional | "office" | "pdf" | "opendocument" | "skip" | |
include optional | list of string | |
include_types optional | list of string | |
keep_sharing optional | boolean | |
max_delete optional | integer (optional) | |
max_size optional | integer (optional) | |
min_size optional | integer (optional) | |
mode optional | "copy" | "mirror" | "move" | "cumulative" | "update" | "incremental_backup" | "full_backup" | "two_way" | "real_time" | |
modified_after optional | string (date-time) (optional) | |
modified_before optional | string (date-time) (optional) | |
report optional | boolean | |
source_cloud_id | string (uuid) | |
source_path optional | string | |
verify_checksum optional | boolean |
Answer 200
| Field | Type | Meaning |
|---|---|---|
brake optional | string (optional) | |
can_choose_google_docs optional | boolean | |
can_keep_sharing optional | boolean | |
notes | list of string | |
server_side | boolean | |
verification | string | |
warnings | list of string |
GET /api/v1/transfers/{job_id}
Get Transfer
Parameters
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
bytes_done | integer | |
bytes_total | integer | |
certificate optional | boolean | |
created_at | string (date-time) | |
cutover optional | boolean | |
destination_cloud_id | string (uuid) (optional) | |
destination_path | string | |
error | string (optional) | |
files_done | integer | |
files_total | integer | |
finished_at | string (date-time) (optional) | |
id | string (uuid) | |
kind | string | |
mode | string | |
name optional | string (optional) | |
report optional | boolean | |
source_cloud_id | string (uuid) (optional) | |
source_path | string | |
started_at | string (date-time) (optional) | |
status | string |
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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
object
GET /api/v1/transfers/{job_id}/assessment.csv
Assessment Csv
Every finding, as a spreadsheet.
Parameters
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
object
GET /api/v1/transfers/{job_id}/assessment.pdf
Assessment Pdf
The assessment as a report to hand to somebody.
Parameters
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
object
POST /api/v1/transfers/{job_id}/cancel
Cancel Transfer
Parameters
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
bytes_done | integer | |
bytes_total | integer | |
certificate optional | boolean | |
created_at | string (date-time) | |
cutover optional | boolean | |
destination_cloud_id | string (uuid) (optional) | |
destination_path | string | |
error | string (optional) | |
files_done | integer | |
files_total | integer | |
finished_at | string (date-time) (optional) | |
id | string (uuid) | |
kind | string | |
mode | string | |
name optional | string (optional) | |
report optional | boolean | |
source_cloud_id | string (uuid) (optional) | |
source_path | string | |
started_at | string (date-time) (optional) | |
status | string |
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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
finished | boolean | |
members | list 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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
cutover optional | boolean |
Answer 202
| Field | Type | Meaning |
|---|---|---|
bytes_done | integer | |
bytes_total | integer | |
certificate optional | boolean | |
created_at | string (date-time) | |
cutover optional | boolean | |
destination_cloud_id | string (uuid) (optional) | |
destination_path | string | |
error | string (optional) | |
files_done | integer | |
files_total | integer | |
finished_at | string (date-time) (optional) | |
id | string (uuid) | |
kind | string | |
mode | string | |
name optional | string (optional) | |
report optional | boolean | |
source_cloud_id | string (uuid) (optional) | |
source_path | string | |
started_at | string (date-time) (optional) | |
status | string |
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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) | |
limit query, optional | integer |
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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
bytes_done | integer | |
cancelled | integer | |
failed | integer | |
files_done | integer | |
id | string (uuid) | |
members | list of app__api__v1__teams__Member | |
name | string | |
running | integer | |
status | string | |
succeeded | integer | |
total | integer | |
waiting | integer |
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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
object
POST /api/v1/transfers/{job_id}/pause
Pause Transfer
Parameters
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
bytes_done | integer | |
bytes_total | integer | |
certificate optional | boolean | |
created_at | string (date-time) | |
cutover optional | boolean | |
destination_cloud_id | string (uuid) (optional) | |
destination_path | string | |
error | string (optional) | |
files_done | integer | |
files_total | integer | |
finished_at | string (date-time) (optional) | |
id | string (uuid) | |
kind | string | |
mode | string | |
name optional | string (optional) | |
report optional | boolean | |
source_cloud_id | string (uuid) (optional) | |
source_path | string | |
started_at | string (date-time) (optional) | |
status | string |
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
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
object
POST /api/v1/transfers/{job_id}/resume
Resume Transfer
Parameters
| Name | Type | Meaning |
|---|---|---|
job_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
bytes_done | integer | |
bytes_total | integer | |
certificate optional | boolean | |
created_at | string (date-time) | |
cutover optional | boolean | |
destination_cloud_id | string (uuid) (optional) | |
destination_path | string | |
error | string (optional) | |
files_done | integer | |
files_total | integer | |
finished_at | string (date-time) (optional) | |
id | string (uuid) | |
kind | string | |
mode | string | |
name optional | string (optional) | |
report optional | boolean | |
source_cloud_id | string (uuid) (optional) | |
source_path | string | |
started_at | string (date-time) (optional) | |
status | string |
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)
| Field | Type | Meaning |
|---|---|---|
display_name optional | string | |
fields optional | object | |
members optional | list of app__api__routes__accounts___shared__MemberIn | |
provider | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
created_at | string (date-time) | |
files | boolean | |
folders optional | list of Folder | |
holds optional | list of string | |
id | string (uuid) | |
kind optional | string | |
name | string | |
needs_folder optional | boolean | |
picked_only optional | boolean | |
provider | string | |
provider_label | string | |
status | string |
POST /api/v1/clouds/connect
Start Connect
Start connecting a cloud by its sign-in. Credential clouds use ``POST /clouds``.
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
code_challenge | string | |
provider | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
authorize_url | string | |
return_url | string |
POST /api/v1/clouds/connect/complete
Complete Connect
Finish it with the id the browser brought back and the app's verifier.
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
code_verifier | string | |
completion | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
created_at | string (date-time) | |
files | boolean | |
folders optional | list of Folder | |
holds optional | list of string | |
id | string (uuid) | |
kind optional | string | |
name | string | |
needs_folder optional | boolean | |
picked_only optional | boolean | |
provider | string | |
provider_label | string | |
status | string |
GET /api/v1/providers
Providers
Every service this server can connect, and which are not set up yet.
Answer 200
| Field | Type | Meaning |
|---|---|---|
connectable optional | integer | |
features optional | list of string | |
providers | list of ProviderOut | |
unavailable | list 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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) | |
cursor query, optional | string (optional) | |
limit query, optional | integer | |
path query, optional | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
can_write | boolean | |
items | list of File | |
next_cursor optional | string (optional) |
GET /api/v1/clouds/{account_id}/files/content
Download
The file at ``?path=``, streamed. Supports ``Range`` for resuming.
Parameters
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) | |
path query, optional | string |
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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) | |
path query, optional | string |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
destination_cloud_id | string (uuid) | |
destination_path optional | string | |
mode optional | "copy" | "move" | |
names | list 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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
items | list 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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
paths | list of string |
Answer 200
list of DeleteResult
POST /api/v1/clouds/{account_id}/files/rename
Rename
Rename the item at ``?path=`` in place.
Parameters
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) | |
path query, optional | string |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
name | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
done | boolean | |
path | string (optional) | |
transfer_id optional | string (uuid) (optional) |
GET /api/v1/clouds/{account_id}/files/search
Search Folder
Files and folders under ``path`` whose name contains ``q``, ignoring case (mobile parity P1.11). One cloud per request, as the website asks: an app searching every cloud sends one each, so a slow cloud does not hold back the others. The website's own search answers it.
Parameters
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) | |
q query | string | |
path query, optional | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
depth | integer | |
items | list of File | |
path | string | |
query | string | |
truncated | boolean | |
whole | boolean |
POST /api/v1/clouds/{account_id}/folders
Create Folder
A folder named ``name`` inside ``?path=``.
Parameters
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) | |
path query, optional | string |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
name | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
done | boolean | |
path | string (optional) | |
transfer_id optional | string (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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
done | boolean |
POST /api/v1/clouds/{account_id}/uploads
Start Upload
Start uploading a file named ``name`` of ``size`` bytes into ``?path=``.
Parameters
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) | |
name query | string | |
size query | integer | |
overwrite query, optional | boolean | |
path query, optional | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
id | string | |
piece_bytes | integer | |
received | integer | |
size | integer |
PUT /api/v1/clouds/{account_id}/uploads/{session_id}
Send Piece
One piece of the file, as the body, starting at ``offset``.
Parameters
| Name | Type | Meaning |
|---|---|---|
session_id path | string | |
account_id path | string (uuid) | |
offset query | integer | |
path query, optional | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
id | string | |
piece_bytes | integer | |
received | integer | |
size | integer |
DELETE /api/v1/clouds/{account_id}/uploads/{session_id}
Cancel Upload
Parameters
| Name | Type | Meaning |
|---|---|---|
session_id path | string | |
account_id path | string (uuid) | |
path query, optional | string |
Answer 204
No body.
POST /api/v1/clouds/{account_id}/uploads/{session_id}/complete
Complete Upload
Parameters
| Name | Type | Meaning |
|---|---|---|
session_id path | string | |
account_id path | string (uuid) | |
path query, optional | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
path | string | |
size | integer |
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)
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
allowed_extensions optional | list of string | |
expires_in_days optional | integer | |
label optional | string | |
max_bytes_per_file optional | integer (optional) | |
max_files optional | integer | |
passphrase optional | string (optional) | |
path optional | string |
Answer 201
object
DELETE /api/v1/upload-requests/{request_id}
Turn Off
Stop a link taking files. What arrived through it stays explained.
Parameters
| Name | Type | Meaning |
|---|---|---|
request_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
auth_method | "none" | "private_key_jwt" | "client_secret_basic" | "client_secret_post" | |
grant_types | list of string | |
homepage optional | string (optional) | |
jwks optional | object (optional) | |
jwks_uri optional | string (optional) | |
kind | "public" | "confidential" | |
name | string | |
redirect_uris optional | list of string | |
scope | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
auth_method | string | |
client_id | string | |
client_secret optional | string (optional) | |
confidential | boolean | |
created_at | string (date-time) | |
disabled | boolean | |
dpop_bound | boolean | |
grant_types | list of string | |
has_keys | boolean | |
homepage | string (optional) | |
id | string (uuid) | |
jwks_uri | string (optional) | |
name | string | |
redirect_uris | list of string | |
reviewed | boolean | |
scope | string |
PATCH /api/v1/developers/apps/{app_id}
Change App
Parameters
| Name | Type | Meaning |
|---|---|---|
app_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
homepage optional | string (optional) | |
name optional | string (optional) | |
redirect_uris optional | list of string (optional) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
auth_method | string | |
client_id | string | |
confidential | boolean | |
created_at | string (date-time) | |
disabled | boolean | |
dpop_bound | boolean | |
grant_types | list of string | |
has_keys | boolean | |
homepage | string (optional) | |
id | string (uuid) | |
jwks_uri | string (optional) | |
name | string | |
redirect_uris | list of string | |
reviewed | boolean | |
scope | string |
DELETE /api/v1/developers/apps/{app_id}
Switch Off App
Switch the app off: every sign-in made through it ends.
Parameters
| Name | Type | Meaning |
|---|---|---|
app_id path | string (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
| Name | Type | Meaning |
|---|---|---|
app_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
auth_method | string | |
client_id | string | |
client_secret optional | string (optional) | |
confidential | boolean | |
created_at | string (date-time) | |
disabled | boolean | |
dpop_bound | boolean | |
grant_types | list of string | |
has_keys | boolean | |
homepage | string (optional) | |
id | string (uuid) | |
jwks_uri | string (optional) | |
name | string | |
redirect_uris | list of string | |
reviewed | boolean | |
scope | string |
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
| Name | Type | Meaning |
|---|---|---|
grant_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_path optional | string | |
every_minutes optional | 15 | 30 | 60 | |
mode optional | "mirror" | "two_way" | "copy" | |
shared_drives optional | boolean | |
tenant_account_id | string (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
| Name | Type | Meaning |
|---|---|---|
mirror_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
enabled | boolean |
Answer 200
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_name | string | |
dst_path | string | |
enabled | boolean | |
every_minutes | integer | |
id | string (uuid) | |
last_error | string (optional) | |
last_reconciled_at | string (date-time) (optional) | |
last_run_at | string (date-time) (optional) | |
last_status | JobStatus (optional) | |
live | LiveOut | |
mode | string | |
people | integer | |
shared_drives | boolean | |
spaces | integer | |
tenant_account_id | string (uuid) | |
tenant_name | string |
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
| Name | Type | Meaning |
|---|---|---|
mirror_id path | string (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
| Name | Type | Meaning |
|---|---|---|
mirror_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_name | string | |
dst_path | string | |
enabled | boolean | |
every_minutes | integer | |
id | string (uuid) | |
last_error | string (optional) | |
last_reconciled_at | string (date-time) (optional) | |
last_run_at | string (date-time) (optional) | |
last_status | JobStatus (optional) | |
live | LiveOut | |
mode | string | |
people | integer | |
shared_drives | boolean | |
spaces | integer | |
tenant_account_id | string (uuid) | |
tenant_name | string |
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)
| Field | Type | Meaning |
|---|---|---|
chat_archive optional | ArchiveSpec (optional) | |
cron | string | |
database_backup optional | DumpSpec (optional) | |
email optional | EmailSpec (optional) | |
enabled optional | boolean | |
name | string | |
team_delta optional | string (uuid) (optional) | |
timezone optional | string | |
transfer optional | TransferIn (optional) |
Answer 201
object
GET /api/v1/schedules/{schedule_id}
Get Schedule
Parameters
| Name | Type | Meaning |
|---|---|---|
schedule_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
cron | string | |
enabled | boolean | |
id | string (uuid) | |
kind | string | |
last_error | string (optional) | |
last_run_at | string (date-time) (optional) | |
last_status | string (optional) | |
name | string | |
next_run_at | string (date-time) | |
timezone | string | |
transfer | ScheduleTransfer | |
trigger | string | |
upcoming | list 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
| Name | Type | Meaning |
|---|---|---|
schedule_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
cron optional | string (optional) | |
enabled optional | boolean (optional) | |
name optional | string (optional) | |
timezone optional | string (optional) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
cron | string | |
enabled | boolean | |
id | string (uuid) | |
kind | string | |
last_error | string (optional) | |
last_run_at | string (date-time) (optional) | |
last_status | string (optional) | |
name | string | |
next_run_at | string (date-time) | |
timezone | string | |
transfer | ScheduleTransfer | |
trigger | string | |
upcoming | list of string (date-time) |
DELETE /api/v1/schedules/{schedule_id}
Delete Schedule
Parameters
| Name | Type | Meaning |
|---|---|---|
schedule_id path | string (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
| Name | Type | Meaning |
|---|---|---|
schedule_id path | string (uuid) |
Answer 202
| Field | Type | Meaning |
|---|---|---|
bytes_done | integer | |
bytes_total | integer | |
certificate optional | boolean | |
created_at | string (date-time) | |
cutover optional | boolean | |
destination_cloud_id | string (uuid) (optional) | |
destination_path | string | |
error | string (optional) | |
files_done | integer | |
files_total | integer | |
finished_at | string (date-time) (optional) | |
id | string (uuid) | |
kind | string | |
mode | string | |
name optional | string (optional) | |
report optional | boolean | |
source_cloud_id | string (uuid) (optional) | |
source_path | string | |
started_at | string (date-time) (optional) | |
status | string |
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
| Name | Type | Meaning |
|---|---|---|
schedule_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
signed optional | boolean |
Answer 201
| Field | Type | Meaning |
|---|---|---|
exists | boolean | |
last_fired_at optional | string (date-time) (optional) | |
prefix optional | string (optional) | |
signed optional | boolean | |
signing_secret optional | string (optional) | |
url | string |
DELETE /api/v1/schedules/{schedule_id}/trigger
Delete Trigger
Parameters
| Name | Type | Meaning |
|---|---|---|
schedule_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
events | list of string | |
kind optional | "webhook" | "slack" | "discord" | "email" | "push" | |
name | string | |
subscription optional | PushSubscriptionIn (optional) | |
url optional | string (optional) |
Answer 201
| Field | Type | Meaning |
|---|---|---|
created_at | string (date-time) | |
enabled | boolean | |
events | list of string | |
failure_count | integer | |
id | string (uuid) | |
kind | string | |
last_delivery_at | string (date-time) (optional) | |
last_error | string (optional) | |
name | string | |
secret | string (optional) | |
target | string |
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
| Field | Type | Meaning |
|---|---|---|
kinds | list 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)
| Field | Type | Meaning |
|---|---|---|
events | list of string | |
name | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
code | string | |
expires_in | integer | |
url | string |
GET /api/v1/notifications/telegram/link/{code}
Telegram Link Status
Parameters
| Name | Type | Meaning |
|---|---|---|
code path | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
status | "waiting" | "linked" | "expired" |
PATCH /api/v1/notifications/{channel_id}
Change Channel
Rename, change the events, or switch it on or off.
Parameters
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
enabled optional | boolean (optional) | |
events optional | list of string (optional) | |
name optional | string (optional) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
created_at | string (date-time) | |
enabled | boolean | |
events | list of string | |
failure_count | integer | |
id | string (uuid) | |
kind | string | |
last_delivery_at | string (date-time) (optional) | |
last_error | string (optional) | |
name | string | |
target | string |
DELETE /api/v1/notifications/{channel_id}
Remove Channel
Parameters
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (uuid) |
Answer 204
No body.
GET /api/v1/notifications/{channel_id}/deliveries
Deliveries
Parameters
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (uuid) |
Answer 200
list of DeliveryOut
POST /api/v1/notifications/{channel_id}/deliveries/{delivery_id}/replay
Replay
Parameters
| Name | Type | Meaning |
|---|---|---|
delivery_id path | string (uuid) | |
channel_id path | string (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
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
previous_valid_until | string (date-time) | |
secret | string |
POST /api/v1/notifications/{channel_id}/test
Test Channel
Send a test event now, through the real delivery path.
Parameters
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (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
| Name | Type | Meaning |
|---|---|---|
before query, optional | integer (optional) | |
limit query, optional | integer |
Answer 200
| Field | Type | Meaning |
|---|---|---|
items | list of ActivityItem | |
next_before | integer (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)
| Field | Type | Meaning |
|---|---|---|
account_id optional | string (uuid) (optional) | |
code optional | string (optional) | |
folder optional | string | |
name | string | |
password optional | string (optional) | |
read_only optional | boolean |
Answer 201
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) (optional) | |
created_at | string (date-time) | |
folder | string | |
id | string (uuid) | |
last_used_at | string (date-time) (optional) | |
name | string | |
password | string | |
prefix | string | |
read_only | boolean |
DELETE /api/v1/security/app-passwords/{password_id}
Revoke App Password
Parameters
| Name | Type | Meaning |
|---|---|---|
password_id path | string (uuid) |
Answer 204
No body.
GET /api/v1/security/passkeys
Passkeys
Answer 200
| Field | Type | Meaning |
|---|---|---|
enabled | boolean | |
fresh | boolean | |
passkeys | list of PasskeyOut |
PATCH /api/v1/security/passkeys/{passkey_id}
Rename Passkey
Parameters
| Name | Type | Meaning |
|---|---|---|
passkey_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
name | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
created_at | string (date-time) | |
id | string (uuid) | |
last_used_at | string (date-time) (optional) | |
name | string | |
synced | boolean |
POST /api/v1/security/passkeys/{passkey_id}/remove
Remove Passkey
Parameters
| Name | Type | Meaning |
|---|---|---|
passkey_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
code optional | string (optional) | |
password optional | string (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)
| Field | Type | Meaning |
|---|---|---|
code optional | string (optional) | |
expires_in_days optional | 30 | 90 | 365 | |
name | string | |
password optional | string (optional) | |
scope optional | TokenScope |
Answer 201
| Field | Type | Meaning |
|---|---|---|
created_at | string (date-time) | |
expired | boolean | |
expires_at | string (date-time) (optional) | |
id | string (uuid) | |
last_used_at | string (date-time) (optional) | |
name | string | |
prefix | string | |
scope | string | |
token | string |
DELETE /api/v1/security/tokens/{token_id}
Revoke Token
Parameters
| Name | Type | Meaning |
|---|---|---|
token_id path | string (uuid) |
Answer 204
No body.
GET /api/v1/security/two-factor
Two Factor
Answer 200
| Field | Type | Meaning |
|---|---|---|
enabled | boolean | |
enabled_at | string (date-time) (optional) | |
factors optional | list of "totp" | "passkey" | |
recovery_codes_left | integer |
POST /api/v1/security/two-factor/disable
Two Factor Disable
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
code optional | string (optional) | |
password optional | string (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)
| Field | Type | Meaning |
|---|---|---|
code | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
recovery_codes | list 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)
| Field | Type | Meaning |
|---|---|---|
code | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
recovery_codes | list 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
| Field | Type | Meaning |
|---|---|---|
otpauth_uri | string | |
qr_svg | string | |
secret | string |
Shares
Support
GET /api/v1/support/attachments/{attachment_id}
Attachment
A file from one of the person's tickets.
Parameters
| Name | Type | Meaning |
|---|---|---|
attachment_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
body | string | |
category optional | string | |
context optional | object |
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
| Field | Type | Meaning |
|---|---|---|
attachment_types | list of string | |
categories | object | |
chat_enabled | boolean | |
chat_online | boolean | |
email | string | |
enabled | boolean | |
max_attachment_bytes | integer | |
max_attachments_per_message | integer | |
priorities | list 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
| Name | Type | Meaning |
|---|---|---|
message_id path | string (uuid) | |
name query | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
content_type | string | |
filename | string | |
id | string (uuid) | |
inline | boolean | |
size | integer |
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)
| Field | Type | Meaning |
|---|---|---|
body | string | |
category | string | |
context optional | object | |
priority optional | string | |
subject | string |
Answer 201
object
GET /api/v1/support/tickets/{ticket_id}
Ticket
The whole thread; reading it marks it read.
Parameters
| Name | Type | Meaning |
|---|---|---|
ticket_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
category | string | |
channel | string | |
created_at | string (date-time) | |
id | string (uuid) | |
last_activity_at | string (date-time) | |
messages | list of MessageOut | |
number | integer | |
priority | string | |
rating | integer (optional) | |
rating_comment | string (optional) | |
status | string | |
subject | string | |
typing optional | boolean | |
unread | boolean |
POST /api/v1/support/tickets/{ticket_id}/close
Close
Parameters
| Name | Type | Meaning |
|---|---|---|
ticket_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
category | string | |
channel | string | |
created_at | string (date-time) | |
id | string (uuid) | |
last_activity_at | string (date-time) | |
messages | list of MessageOut | |
number | integer | |
priority | string | |
rating | integer (optional) | |
rating_comment | string (optional) | |
status | string | |
subject | string | |
typing optional | boolean | |
unread | boolean |
POST /api/v1/support/tickets/{ticket_id}/messages
Reply
A reply. Files follow it at ``/messages/{id}/attachments``, one per request.
Parameters
| Name | Type | Meaning |
|---|---|---|
ticket_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
body | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
attachments | list of AttachmentOut | |
author | string | |
body | string | |
created_at | string (date-time) | |
id | string (uuid) | |
kind | string | |
mine | boolean |
POST /api/v1/support/tickets/{ticket_id}/rating
Rate
How the help was, 1 to 5, once the ticket is solved or closed.
Parameters
| Name | Type | Meaning |
|---|---|---|
ticket_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
comment optional | string (optional) | |
rating | integer |
Answer 200
| Field | Type | Meaning |
|---|---|---|
category | string | |
channel | string | |
created_at | string (date-time) | |
id | string (uuid) | |
last_activity_at | string (date-time) | |
messages | list of MessageOut | |
number | integer | |
priority | string | |
rating | integer (optional) | |
rating_comment | string (optional) | |
status | string | |
subject | string | |
typing optional | boolean | |
unread | boolean |
POST /api/v1/support/tickets/{ticket_id}/reopen
Reopen
Parameters
| Name | Type | Meaning |
|---|---|---|
ticket_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
category | string | |
channel | string | |
created_at | string (date-time) | |
id | string (uuid) | |
last_activity_at | string (date-time) | |
messages | list of MessageOut | |
number | integer | |
priority | string | |
rating | integer (optional) | |
rating_comment | string (optional) | |
status | string | |
subject | string | |
typing optional | boolean | |
unread | boolean |
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
| Name | Type | Meaning |
|---|---|---|
ticket_id path | string (uuid) | |
after query, optional | string (date-time) (optional) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
category | string | |
channel | string | |
created_at | string (date-time) | |
id | string (uuid) | |
last_activity_at | string (date-time) | |
messages | list of MessageOut | |
number | integer | |
priority | string | |
rating | integer (optional) | |
rating_comment | string (optional) | |
status | string | |
subject | string | |
typing optional | boolean | |
unread | boolean |
POST /api/v1/support/tickets/{ticket_id}/typing
Typing
Parameters
| Name | Type | Meaning |
|---|---|---|
ticket_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
dst_account_id | string (uuid) | |
dst_path optional | string | |
max_file_mb optional | integer | |
media optional | "all" | "photos" | "none" | |
src_account_id | string (uuid) | |
src_path optional | string |
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)
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
destination | string | |
follow optional | boolean | |
hide_sender optional | boolean | |
interval_seconds optional | integer | |
kinds optional | list of "text" | "photo" | "video" | "audio" | "document" | "other" | |
last_count optional | integer | |
max_size optional | integer (optional) | |
min_size optional | integer (optional) | |
skip_existing optional | boolean | |
source | string | |
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)
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
destinations | list of string | |
follow optional | boolean | |
hide_sender optional | boolean | |
interval_seconds optional | integer | |
kinds optional | list of "text" | "photo" | "video" | "audio" | "document" | "other" | |
last_count optional | integer | |
max_size optional | integer (optional) | |
min_size optional | integer (optional) | |
pairs optional | list of list of (optional) | |
resume optional | boolean | |
skip_existing optional | boolean | |
sources | list 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
| Name | Type | Meaning |
|---|---|---|
group_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
interval_seconds optional | integer (optional) | |
status optional | "active" | "paused" (optional) |
Answer 200
list of CloneOut
DELETE /api/v1/telegram/clones/groups/{group_id}
Delete Group
Parameters
| Name | Type | Meaning |
|---|---|---|
group_id path | string (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
| Name | Type | Meaning |
|---|---|---|
account_id query | string (uuid) | |
source query | string | |
destination query | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
clone | PairCloneOut (optional) | |
saved | SavedOut (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)
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
destinations | list of string | |
sources | list of string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
pairs | list 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
| Name | Type | Meaning |
|---|---|---|
clone_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
follow optional | boolean (optional) | |
hide_sender optional | boolean (optional) | |
interval_seconds optional | integer (optional) | |
kinds optional | list of "text" | "photo" | "video" | "audio" | "document" | "other" (optional) | |
max_size optional | integer (optional) | |
min_size optional | integer (optional) | |
skip_existing optional | boolean (optional) | |
status optional | "active" | "paused" (optional) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
account_id | string | |
account_name | string | |
charged_bytes optional | integer | |
created_at | string (date-time) | |
cursor | integer | |
destination | EndOut | |
end_id | integer | |
failed | integer | |
files_charged optional | integer | |
follow | boolean | |
forwarded | integer | |
group_id optional | string (optional) | |
group_interval_seconds optional | integer (optional) | |
hide_sender | boolean | |
id | string | |
interval_seconds | integer | |
kinds | list of string | |
last_error | string (optional) | |
last_forwarded_at | string (date-time) (optional) | |
max_size | integer (optional) | |
min_size | integer (optional) | |
next_at | string (date-time) | |
phase | string | |
skip_existing optional | boolean | |
skipped | integer | |
source | EndOut | |
start_cursor | integer | |
status | string | |
wait_until | string (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
| Name | Type | Meaning |
|---|---|---|
clone_id path | string (uuid) |
Answer 204
No body.
GET /api/v1/telegram/clones/{clone_id}/events
Clone Events
What the clone has done lately, newest first.
Parameters
| Name | Type | Meaning |
|---|---|---|
clone_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
chat | string | |
match optional | "file" | "file_or_name" |
Answer 201
object
GET /api/v1/telegram/duplicates/{scan_id}
Get Scan
Parameters
| Name | Type | Meaning |
|---|---|---|
scan_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
account_id | string | |
account_name | string | |
chat | ChatOut | |
created_at | string (date-time) | |
deleted | integer | |
duplicates | integer | |
error | string (optional) | |
groups | integer | |
id | string | |
match | string | |
newest_id | integer | |
scanned | integer | |
status | string | |
to_delete | integer | |
updated_at | string (date-time) |
DELETE /api/v1/telegram/duplicates/{scan_id}
Forget Scan
Parameters
| Name | Type | Meaning |
|---|---|---|
scan_id path | string (uuid) |
Answer 204
No body.
POST /api/v1/telegram/duplicates/{scan_id}/cancel
Cancel Scan
Parameters
| Name | Type | Meaning |
|---|---|---|
scan_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
account_id | string | |
account_name | string | |
chat | ChatOut | |
created_at | string (date-time) | |
deleted | integer | |
duplicates | integer | |
error | string (optional) | |
groups | integer | |
id | string | |
match | string | |
newest_id | integer | |
scanned | integer | |
status | string | |
to_delete | integer | |
updated_at | string (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
| Name | Type | Meaning |
|---|---|---|
scan_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
skip_groups optional | list of integer |
Answer 200
| Field | Type | Meaning |
|---|---|---|
account_id | string | |
account_name | string | |
chat | ChatOut | |
created_at | string (date-time) | |
deleted | integer | |
duplicates | integer | |
error | string (optional) | |
groups | integer | |
id | string | |
match | string | |
newest_id | integer | |
scanned | integer | |
status | string | |
to_delete | integer | |
updated_at | string (date-time) |
GET /api/v1/telegram/duplicates/{scan_id}/groups
Scan Groups
A page of what the scan found, most copies first.
Parameters
| Name | Type | Meaning |
|---|---|---|
scan_id path | string (uuid) | |
offset query, optional | integer | |
limit query, optional | integer |
Answer 200
| Field | Type | Meaning |
|---|---|---|
groups | list of GroupOut | |
total | integer |
GET /api/v1/telegram/pricing
Pricing
What a cloned file counts against the allowance.
Answer 200
| Field | Type | Meaning |
|---|---|---|
bytes_per_file | integer | |
files_left | integer (optional) | |
files_per_gb | integer | |
remaining_bytes | integer (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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
password_saved | boolean | |
workers | list 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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) | |
path query, optional | string | |
before query, optional | integer | |
limit query, optional | integer |
Answer 200
| Field | Type | Meaning |
|---|---|---|
chats optional | list of ChatOut | |
files optional | list of FileOut | |
max_file_size optional | integer | |
next_before optional | integer | |
path | string | |
premium optional | boolean |
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
| Name | Type | Meaning |
|---|---|---|
account_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
password | string |
Answer 204
No body.
DELETE /api/v1/telegram/{account_id}/password
Forget Password
Parameters
| Name | Type | Meaning |
|---|---|---|
account_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
events | list of string | |
name | string | |
url | string |
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
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (uuid) |
Answer 204
No body.
GET /api/v1/webhooks/{channel_id}/deliveries
List Deliveries
Parameters
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (uuid) |
Answer 200
list of DeliveryOut
POST /api/v1/webhooks/{channel_id}/deliveries/{delivery_id}/replay
Replay Delivery
Parameters
| Name | Type | Meaning |
|---|---|---|
delivery_id path | string (uuid) | |
channel_id path | string (uuid) |
Answer 202
object
POST /api/v1/webhooks/{channel_id}/secret
Rotate Secret
Parameters
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
previous_valid_until | string (date-time) | |
secret | string |
POST /api/v1/webhooks/{channel_id}/test
Test Webhook
Send a ``notification.test`` event now, through the real delivery path.
Parameters
| Name | Type | Meaning |
|---|---|---|
channel_id path | string (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)
| Field | Type | Meaning |
|---|---|---|
account_id | string (uuid) | |
name | string | |
names optional | "standard" | "off" | |
path optional | string | |
people optional | list 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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) | |
path query, optional | string (optional) | |
before query, optional | string (date-time) (optional) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
members | list of WorkspaceMemberOut | |
messages | list of WorkspaceMessageOut | |
workspace | WorkspaceSummary |
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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
mentions optional | list of string (uuid) | |
parent_id optional | string (uuid) (optional) | |
path optional | string (optional) | |
text | string |
Answer 201
| Field | Type | Meaning |
|---|---|---|
author | string | |
author_id | string (uuid) (optional) | |
created_at | string (date-time) | |
deleted | boolean | |
edited_at | string (date-time) (optional) | |
id | string (uuid) | |
mentions | list of string (uuid) | |
parent_id | string (uuid) (optional) | |
path | string (optional) | |
reactions | object | |
text | string |
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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) |
Answer 200
| Field | Type | Meaning |
|---|---|---|
name | string |
POST /api/v1/workspaces/{workspace_id}/discussion/read
Mark Read
Everything said so far is read.
Parameters
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) |
Answer 204
No body.
PATCH /api/v1/workspaces/{workspace_id}/discussion/{message_id}
Edit Message
Change one's own words.
Parameters
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) | |
message_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
text | string |
Answer 200
| Field | Type | Meaning |
|---|---|---|
author | string | |
author_id | string (uuid) (optional) | |
created_at | string (date-time) | |
deleted | boolean | |
edited_at | string (date-time) (optional) | |
id | string (uuid) | |
mentions | list of string (uuid) | |
parent_id | string (uuid) (optional) | |
path | string (optional) | |
reactions | object | |
text | string |
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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) | |
message_id path | string (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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) | |
message_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
emoji | string |
Answer 200
object
POST /api/v1/workspaces/{workspace_id}/members
Add Member
Share the workspace with one of the owner's people.
Parameters
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
can_write optional | boolean | |
user_id | string (uuid) |
Answer 201
| Field | Type | Meaning |
|---|---|---|
can_write | boolean | |
email | string | |
user_id | string (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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) | |
user_id path | string (uuid) |
Body (JSON)
| Field | Type | Meaning |
|---|---|---|
can_write | boolean |
Answer 200
| Field | Type | Meaning |
|---|---|---|
can_write | boolean | |
email | string | |
user_id | string (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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) | |
user_id path | string (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
| Name | Type | Meaning |
|---|---|---|
workspace_id path | string (uuid) |
Answer 200
object