Help

API reference (v1.0.0)

Every public Boita API endpoint with parameters, request and response schemas, scopes, and examples in curl, TypeScript and Python, from the OpenAPI document.

Base URL https://api.boita.io/v1 · every request carries Authorization: Bearer boita_sk_…. Keys are created on Developers → API keys in the app and are bound to one workspace. Errors are always { "error": { "code", "message", "details" } }; the rate limit is 600 requests a minute per key.

Scopes#

A key carries one or more scopes; each operation below lists which one it needs (any one is enough).

Scope	Allows
`files:read`	List and search files, folders, versions and trash; read transfers and watch folders
`files:write`	Create folders, rename, delete and restore; start transfers; manage watch folders
`shares:write`	Create, extend and revoke share links and read their details
`portals:write`	Create, update and revoke upload portals and review their uploads
`receipts:read`	Read delivery receipts, verification reports, comments and share details
`webhooks:manage`	Manage webhook endpoints and REST-hook subscriptions (Zapier, Make, n8n), read deliveries, retry and test them; poll the event stream
`usage:read`	Read storage, bandwidth, dashboard figures and the audit log

SDKs#

The examples use the official clients, generated from this same contract: @boita/sdk for TypeScript (Node 18+ or any runtime with fetch) and boita for Python 3.9+ (standard library only). Both retry 429 and 5xx with backoff, honour Retry-After, never replay a POST except on 429/503, and throw a BoitaError carrying the API envelope. Set BOITA_API_KEY and BOITA_WORKSPACE (the id in the app URL, /app/<workspaceId>/…).

npm install @boita/sdk

Transfers The API never carries file bytes. POST …/transfers returns a transfer spec for the transfer engine on the machine that holds the files (the desktop app, the Linux agent or a gateway) to run; poll transfers.get until status is completed, then share.

Operations#

Files
Browse, search and organise the workspace
19 operations
Transfers
Transfer specs and progress
4 operations
Shares
Share links and recipient comments
9 operations
Receipts
Delivery receipts, verification reports and delivery notes
4 operations
Portals
Upload portals and the uploads they receive
6 operations
Webhooks
Endpoints, deliveries and the signed event stream
12 operations
Events
Polling alternative to webhooks
1 operation
Usage
Storage and bandwidth figures
2 operations
Cloud
Deliveries to connected Google Drive, Dropbox, OneDrive and Box folders
3 operations

Files#

Browse, search and organise the workspace

GET List a folder
PATCH Rename a file or folder
DELETE Move files to the trash (or delete permanently)
GET Search files by name
GET Every file under a folder with size and modification time (for sync clients)
POST Create a folder
GET List the trash
POST Restore a trashed item
DELETE Purge one trashed item now
GET List kept versions of a file
POST Restore a kept version
GET Thumbnail of a file
GET Rendered proxies of a file
POST Render proxies now
GET A rendered proxy (supports Range)
POST Queue a server-side move or copy
GET Move/copy jobs of the workspace
POST Cancel a queued or running move/copy job
POST Rename many items with a pattern (preview with dryRun)

GETList a folder#

/workspaces/{workspaceId}/files

SDK: files.list · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`path`	query	string	max length 4096 · default ""
`skip`	query	integer	minimum 0 · default 0
`count`	query	integer	minimum 1, maximum 1000 · default 200

Response 200 · application/json

Field Type Notes

pathrequired string

accessrequired string

itemsrequired

array of FileEntry

Field	Type	Notes
`name`required	string
`path`required	string
`type`required	"file" \| "folder" \| "link"
`size`required	integer	nullable
`modifiedAt`required	string	nullable
`encrypted`required	boolean
`preview`	boolean

totalrequired integer

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files?path=&count=200" \
  -H "Authorization: Bearer $BOITA_API_KEY"

PATCHRename a file or folder#

/workspaces/{workspaceId}/files

SDK: files.rename · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`path`required	string	min length 1, max length 4096
`newName`required	string	min length 1, max length 255

Response 200 · application/json

Field	Type	Notes
`ok`required	boolean

curl -X PATCH "https://api.boita.io/v1/workspaces/$WORKSPACE/files" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"deliveries/ep01/EP01_final.mov","newName":"EP01_final.mov"}'

DELETEMove files to the trash (or delete permanently)#

/workspaces/{workspaceId}/files

SDK: files.delete · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`paths`required	array of string	min items 1, max items 500
`permanent`	boolean	· default false

Response 200 · application/json

Field	Type	Notes
`ok`required	boolean

curl -X DELETE "https://api.boita.io/v1/workspaces/$WORKSPACE/files" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paths":["deliveries/ep01/EP01_final.mov"],"permanent":false}'

GETSearch files by name#

/workspaces/{workspaceId}/files/search

SDK: files.search · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`q`required	query	string	min length 1, max length 200
`path`	query	string	max length 4096 · default ""
`limit`	query	integer	minimum 1, maximum 500 · default 100

Response 200 · application/json

Field Type Notes

itemsrequired

array of FileEntry

Field	Type	Notes
`name`required	string
`path`required	string
`type`required	"file" \| "folder" \| "link"
`size`required	integer	nullable
`modifiedAt`required	string	nullable
`encrypted`required	boolean
`preview`	boolean

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files/search?q=EP01&path=" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETEvery file under a folder with size and modification time (for sync clients)#

/workspaces/{workspaceId}/files/manifest

SDK: files.manifest · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`path`	query	string	max length 4096 · default ""

Response 200 · application/json

Field Type Notes

rootrequired string

filesrequired

array of object

Field	Type	Notes
`path`required	string
`size`required	integer
`modifiedAt`required	string	nullable

truncatedrequired boolean

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files/manifest?path=" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTCreate a folder#

/workspaces/{workspaceId}/files/folder

SDK: files.createFolder · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`path`required	string	min length 1, max length 4096

Response 201 · application/json

Field	Type	Notes
`ok`required	boolean

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/files/folder" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"deliveries/ep01/EP01_final.mov"}'

GETList the trash#

/workspaces/{workspaceId}/files/trash

SDK: files.listTrash · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Response 200 · application/json

Field	Type	Notes
`id`required	string
`path`required	string
`name`required	string
`sizeBytes`required	number	nullable
`deletedAt`required	string (date-time)	ISO 8601 timestamp · date-time
`purgeAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files/trash" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTRestore a trashed item#

/workspaces/{workspaceId}/files/trash/{itemId}/restore

SDK: files.restoreFromTrash · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`itemId`required	path	string

Response 200 · application/json

Field	Type	Notes
`ok`required	boolean

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/files/trash/<itemId>/restore" \
  -H "Authorization: Bearer $BOITA_API_KEY"

DELETEPurge one trashed item now#

/workspaces/{workspaceId}/files/trash/{itemId}

SDK: files.purgeFromTrash · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`itemId`required	path	string

Response 200 · application/json

Field	Type	Notes
`ok`required	boolean

curl -X DELETE "https://api.boita.io/v1/workspaces/$WORKSPACE/files/trash/<itemId>" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETList kept versions of a file#

/workspaces/{workspaceId}/files/versions

SDK: files.listVersions · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`path`required	query	string	min length 1, max length 4096

Response 200 · application/json

Field	Type	Notes
`id`required	string
`path`required	string
`sizeBytes`required	number	nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files/versions?path=deliveries%2Fep01%2FEP01_final.mov" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTRestore a kept version#

/workspaces/{workspaceId}/files/versions/{versionId}/restore

SDK: files.restoreVersion · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`versionId`required	path	string

Response 200 · application/json

Field	Type	Notes
`ok`required	boolean

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/files/versions/<versionId>/restore" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETThumbnail of a file#

/workspaces/{workspaceId}/files/preview

SDK: files.preview · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`path`required	query	string	min length 1, max length 4096

Response 200 · image/jpeg

string

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files/preview?path=deliveries%2Fep01%2FEP01_final.mov" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETRendered proxies of a file#

/workspaces/{workspaceId}/files/proxies

What the proxy pipeline has rendered for a file or a kept version (720p MP4, waveform, contact sheet, PDF pages), with its media kind and frame rate.

SDK: files.proxyStatus · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`path`	query	string	max length 4096 · default ""
`version`	query	string

Response 200 · application/json

Field Type Notes

mediarequired "video" | "audio" | "image" | "pdf" nullable

fpsrequired number nullable

durationMsrequired integer nullable

proxiesrequired

array of object

Field	Type	Notes
`kind`required	"proxy720" \| "waveform" \| "contact_sheet" \| "page"
`page`required	integer
`status`required	string
`width`required	integer	nullable
`height`required	integer	nullable
`durationMs`required	integer	nullable
`error`required	string	nullable

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files/proxies?path=" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTRender proxies now#

/workspaces/{workspaceId}/files/proxies

Queues the proxies a file (or a kept version) needs. Video and audio queue on upload; images and PDFs render on demand.

SDK: files.renderProxies · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`paths`	array of string	max items 50
`versions`	array of string	max items 50

Response 200 · application/json

Field	Type	Notes
`queued`required	integer

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/files/proxies" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paths":["deliveries/ep01/EP01_final.mov"],"versions":["…"]}'

GETA rendered proxy (supports Range)#

/workspaces/{workspaceId}/files/proxy

SDK: files.proxy · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`path`	query	string	max length 4096 · default ""
`kind`required	query	"proxy720" \| "waveform" \| "contact_sheet" \| "page"
`page`	query	integer	minimum 0, maximum 50 · default 0
`version`	query	string

Response 200 · application/octet-stream

string

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files/proxy?path=&kind=proxy720" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTQueue a server-side move or copy#

/workspaces/{workspaceId}/files/operations

The workers copy through the transfer engine, verify size and count, and delete the originals only then (move). Conflicts are refused unless `overwrite` is true; a selected frame of a numbered set takes the whole set unless `expandSequences` is false. Caps: 200 items and 500 GB per job (250 GB on plans without the feature).

SDK: files.createOperation · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`kind`required	"move" \| "copy"
`paths`required	array of string	min items 1, max items 200
`destination`	string	max length 4096 · default ""
`overwrite`	boolean	· default false
`expandSequences`	boolean	· default true

Response 201 · application/json

Field Type Notes

idrequired string

kindrequired "move" | "copy"

statusrequired "queued" | "running" | "completed" | "failed" | "cancelled"

destinationrequired string

overwriterequired boolean

itemsrequired

array of object

Field	Type	Notes
`path`required	string
`type`required	"file" \| "folder"
`bytes`required	number

filesTotalrequired integer

filesDonerequired integer

bytesTotalrequired number

bytesDonerequired number

errorrequired string nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

startedAtrequired string (date-time) ISO 8601 timestamp · date-time, nullable

finishedAtrequired string (date-time) ISO 8601 timestamp · date-time, nullable

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/files/operations" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"move","paths":["deliveries/ep01/EP01_final.mov"],"destination":""}'

GETMove/copy jobs of the workspace#

/workspaces/{workspaceId}/files/operations

SDK: files.listOperations · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`active`	query	"1" \| "true"
`limit`	query	integer	minimum 1, maximum 200 · default 50

Response 200 · application/json

Field Type Notes

idrequired string

kindrequired "move" | "copy"

statusrequired "queued" | "running" | "completed" | "failed" | "cancelled"

destinationrequired string

overwriterequired boolean

itemsrequired

array of object

Field	Type	Notes
`path`required	string
`type`required	"file" \| "folder"
`bytes`required	number

filesTotalrequired integer

filesDonerequired integer

bytesTotalrequired number

bytesDonerequired number

errorrequired string nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

startedAtrequired string (date-time) ISO 8601 timestamp · date-time, nullable

finishedAtrequired string (date-time) ISO 8601 timestamp · date-time, nullable

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/files/operations" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTCancel a queued or running move/copy job#

/workspaces/{workspaceId}/files/operations/{jobId}/cancel

SDK: files.cancelOperation · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`jobId`required	path	string

Response 200 · application/json

Field Type Notes

idrequired string

kindrequired "move" | "copy"

statusrequired "queued" | "running" | "completed" | "failed" | "cancelled"

destinationrequired string

overwriterequired boolean

itemsrequired

array of object

Field	Type	Notes
`path`required	string
`type`required	"file" \| "folder"
`bytes`required	number

filesTotalrequired integer

filesDonerequired integer

bytesTotalrequired number

bytesDonerequired number

errorrequired string nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

startedAtrequired string (date-time) ISO 8601 timestamp · date-time, nullable

finishedAtrequired string (date-time) ISO 8601 timestamp · date-time, nullable

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/files/operations/<jobId>/cancel" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTRename many items with a pattern (preview with dryRun)#

/workspaces/{workspaceId}/files/rename-batch

Find/replace, prefix/suffix and numbering with padding. `dryRun: true` returns the plan and conflicts without touching anything; the apply runs exactly that plan.

SDK: files.renameBatch · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field Type Notes

pathsrequired array of string min items 1, max items 200

patternrequired

object

Field Type Notes

find string max length 255

replace string max length 255

regex boolean

ignoreCase boolean

includeExtension boolean

prefix string max length 120

suffix string max length 120

numbering

object

Field	Type	Notes
`start`	integer	minimum 0, maximum 999999 · default 1
`step`	integer	minimum 1, maximum 1000 · default 1
`padding`	integer	minimum 1, maximum 8 · default 3
`position`	"prefix" \| "suffix" \| "replace"	· default "suffix"
`separator`	string	max length 8 · default "_"

dryRun boolean · default false

overwrite boolean · default false

expandSequences boolean · default true

Response 200 · application/json

Field Type Notes

dryRunrequired boolean

expandedrequired integer

changedrequired integer

stepsrequired

array of object

Field	Type	Notes
`from`required	string
`to`required	string
`name`required	string
`newName`required	string
`changed`required	boolean

conflictsrequired

array of object

Field	Type	Notes
`path`required	string
`name`required	string
`reason`required	"duplicate_target" \| "exists" \| "invalid"

appliedrequired

array of object

Field	Type	Notes
`from`required	string
`to`required	string

failedrequired

object

nullable

Field	Type	Notes
`from`required	string
`to`required	string
`error`required	string

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/files/rename-batch" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paths":["deliveries/ep01/EP01_final.mov"],"pattern":{"find":"…","replace":"…","regex":true},"dryRun":false}'

Transfers#

Transfer specs and progress

POST Request a transfer spec
GET List recent transfers
GET Get one transfer
PATCH Report client-side progress

POSTRequest a transfer spec#

/workspaces/{workspaceId}/transfers

Returns a spec the transfer engine (Boita desktop, the CLI agent or a gateway) runs; the API never moves bytes itself.

SDK: transfers.create · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field Type Notes

directionrequired "send" | "receive"

pathsrequired

array of object

min items 1, max items 10000

Field	Type	Notes
`source`required	string	min length 1, max length 4096
`destination`	string	min length 1, max length 4096

destinationRoot any

sourceRoot any

fileCount integer minimum 0

totalBytes integer minimum 0

streams integer minimum 1, maximum 128

growingFileWaitSeconds integer minimum 1, maximum 3600

contentProtectionPassword string min length 8, max length 256

priority "normal" | "deadline" | "background"

deliverTo array of string max items 20

rawAscp boolean

speedMode boolean

deviceId string

shareId string

portalId string

Response 201 · application/json

Field	Type	Notes
`transferId`required	string
`transferSpec`required	object	Hand this to the transfer engine unchanged; it is valid for a short window.
`expiresAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/transfers" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direction":"send","paths":[{"source":"deliveries/ep01/EP01_final.mov","destination":"deliveries/ep01/EP01_final.mov"}],"destinationRoot":null}'

GETList recent transfers#

/workspaces/{workspaceId}/transfers

SDK: transfers.list · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Response 200 · application/json

Field	Type	Notes
`id`required	string
`direction`required	"send" \| "receive"
`client`required	string
`engine`required	string
`status`required	"queued" \| "running" \| "paused" \| "completed" \| "failed" \| "cancelled"
`streams`required	integer
`priority`required	string
`usageId`required	string
`filesTotal`required	integer	nullable
`filesDone`required	integer
`bytesTotal`required	number	nullable
`bytesDone`required	number
`avgRateKbps`required	number	nullable
`startedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`finishedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`errorCode`required	string	nullable
`errorMessage`required	string	nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/transfers" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETGet one transfer#

/workspaces/{workspaceId}/transfers/{transferId}

SDK: transfers.get · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`transferId`required	path	string

Response 200 · application/json

Field	Type	Notes
`id`required	string
`direction`required	"send" \| "receive"
`client`required	string
`engine`required	string
`status`required	"queued" \| "running" \| "paused" \| "completed" \| "failed" \| "cancelled"
`streams`required	integer
`priority`required	string
`usageId`required	string
`filesTotal`required	integer	nullable
`filesDone`required	integer
`bytesTotal`required	number	nullable
`bytesDone`required	number
`avgRateKbps`required	number	nullable
`startedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`finishedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`errorCode`required	string	nullable
`errorMessage`required	string	nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/transfers/<transferId>" \
  -H "Authorization: Bearer $BOITA_API_KEY"

PATCHReport client-side progress#

/workspaces/{workspaceId}/transfers/{transferId}

SDK: transfers.reportProgress · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`transferId`required	path	string

Request body (application/json, required)

Field	Type	Notes
`status`required	"queued" \| "running" \| "paused" \| "completed" \| "failed" \| "cancelled"
`bytesDone`required	integer	minimum 0
`bytesTotal`	integer	minimum 0
`filesDone`required	integer	minimum 0
`filesTotal`	integer	minimum 0
`rateKbps`	number	minimum 0
`errorCode`	string
`errorMessage`	string	max length 500

Response 200 · application/json

Field	Type	Notes
`id`required	string
`direction`required	"send" \| "receive"
`client`required	string
`engine`required	string
`status`required	"queued" \| "running" \| "paused" \| "completed" \| "failed" \| "cancelled"
`streams`required	integer
`priority`required	string
`usageId`required	string
`filesTotal`required	integer	nullable
`filesDone`required	integer
`bytesTotal`required	number	nullable
`bytesDone`required	number
`avgRateKbps`required	number	nullable
`startedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`finishedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`errorCode`required	string	nullable
`errorMessage`required	string	nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X PATCH "https://api.boita.io/v1/workspaces/$WORKSPACE/transfers/<transferId>" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"queued","bytesDone":48000000000,"bytesTotal":48000000000,"filesDone":0}'

Shares#

Share links and recipient comments

POST Create a share link
GET List share links
GET Get a share link with its activity
PATCH Extend a share link
DELETE Revoke a share link
POST Extend, revoke or re-notify many links
POST Add recipients (email or WhatsApp number) to a live link
GET List recipient comments
POST Reply to recipients

POSTCreate a share link#

/workspaces/{workspaceId}/shares

SDK: shares.create · scope: shares:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`mode`	"drive" \| "send"	· default "drive"
`paths`required	array of string	min items 1, max items 500
`title`	string	max length 200
`message`	string	max length 4000
`expiresInDays`	integer	minimum 1, maximum 3650
`maxDownloads`	integer	minimum 1, maximum 100000
`password`	string	min length 8, max length 256
`notifyOnDownload`	boolean
`allowPreview`	boolean
`allowComments`	boolean
`requireEmail`	boolean
`recipients`	array of string (email)	max items 200
`phones`	array of string	max items 200
`availableFrom`	string (date-time)	date-time
`viewOnly`	boolean
`watermark`	boolean
`templateId`	string	max length 64
`recipientGroups`	array of string	max items 20
`reviewRoles`	object
`projectId`	string	max length 64, nullable
`locale`	"en"	nullable

Response 201 · application/json

Field Type Notes

idrequired string

slugrequired string

urlrequired string Relative on the app host, absolute on a custom domain

moderequired "drive" | "send"

titlerequired string nullable

messagerequired string nullable

hasPasswordrequired boolean

statusrequired string

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time

maxDownloadsrequired integer nullable

downloadCountrequired integer

viewCountrequired integer

requireEmailrequired boolean

allowCommentsrequired boolean

viewOnlyrequired boolean

watermarkrequired boolean

availableFromrequired string (date-time) ISO 8601 timestamp · date-time, nullable

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

recipientsrequired

array of ShareRecipient

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`url`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/shares" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"drive","paths":["deliveries/ep01/EP01_final.mov"],"title":"EP01 final"}'

GETList share links#

/workspaces/{workspaceId}/shares

SDK: shares.list · scopes: shares:writereceipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Response 200 · application/json

Field Type Notes

idrequired string

slugrequired string

urlrequired string Relative on the app host, absolute on a custom domain

moderequired "drive" | "send"

titlerequired string nullable

messagerequired string nullable

hasPasswordrequired boolean

statusrequired string

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time

maxDownloadsrequired integer nullable

downloadCountrequired integer

viewCountrequired integer

requireEmailrequired boolean

allowCommentsrequired boolean

viewOnlyrequired boolean

watermarkrequired boolean

availableFromrequired string (date-time) ISO 8601 timestamp · date-time, nullable

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

recipientsrequired

array of ShareRecipient

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`url`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/shares" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETGet a share link with its activity#

/workspaces/{workspaceId}/shares/{shareId}

SDK: shares.get · scopes: shares:writereceipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Response 200 · application/json

Field Type Notes

idrequired string

slugrequired string

urlrequired string Relative on the app host, absolute on a custom domain

moderequired "drive" | "send"

titlerequired string nullable

messagerequired string nullable

hasPasswordrequired boolean

statusrequired string

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time

maxDownloadsrequired integer nullable

downloadCountrequired integer

viewCountrequired integer

requireEmailrequired boolean

allowCommentsrequired boolean

viewOnlyrequired boolean

watermarkrequired boolean

availableFromrequired string (date-time) ISO 8601 timestamp · date-time, nullable

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

recipientsrequired

array of ShareRecipient

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`url`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

eventsrequired

array of object

Field	Type	Notes
`type`required	string
`at`required	string (date-time)	ISO 8601 timestamp · date-time
`ip`required	string	nullable
`userAgent`required	string	nullable
`recipient`required	string	nullable

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>" \
  -H "Authorization: Bearer $BOITA_API_KEY"

PATCHExtend a share link#

/workspaces/{workspaceId}/shares/{shareId}

SDK: shares.extend · scope: shares:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Request body (application/json, required)

Field	Type	Notes
`expiresInDays`	integer	minimum 1, maximum 3650
`projectId`	string	max length 64, nullable

Response 200 · application/json

Field Type Notes

idrequired string

slugrequired string

urlrequired string Relative on the app host, absolute on a custom domain

moderequired "drive" | "send"

titlerequired string nullable

messagerequired string nullable

hasPasswordrequired boolean

statusrequired string

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time

maxDownloadsrequired integer nullable

downloadCountrequired integer

viewCountrequired integer

requireEmailrequired boolean

allowCommentsrequired boolean

viewOnlyrequired boolean

watermarkrequired boolean

availableFromrequired string (date-time) ISO 8601 timestamp · date-time, nullable

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

recipientsrequired

array of ShareRecipient

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`url`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

curl -X PATCH "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expiresInDays":7,"projectId":"ckz7…"}'

DELETERevoke a share link#

/workspaces/{workspaceId}/shares/{shareId}

SDK: shares.revoke · scope: shares:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Response 204

No body.

curl -X DELETE "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTExtend, revoke or re-notify many links#

/workspaces/{workspaceId}/shares/bulk

SDK: shares.bulk · scope: shares:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`ids`required	array of string	min items 1, max items 200
`action`required	"extend" \| "revoke" \| "renotify"
`days`	integer	minimum 1, maximum 3650

Response 200 · application/json

Field Type Notes

donerequired integer

failed

array of object

Field	Type	Notes
`id`required	string
`error`required	string

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/bulk" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["ckz7…"],"action":"extend","days":7}'

POSTAdd recipients (email or WhatsApp number) to a live link#

/workspaces/{workspaceId}/shares/{shareId}/recipients

SDK: shares.addRecipients · scope: shares:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Request body (application/json, required)

Field	Type	Notes
`emails`	array of string (email)	max items 200
`phones`	array of string	max items 200

Response 200 · application/json

Field Type Notes

idrequired string

slugrequired string

urlrequired string Relative on the app host, absolute on a custom domain

moderequired "drive" | "send"

titlerequired string nullable

messagerequired string nullable

hasPasswordrequired boolean

statusrequired string

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time

maxDownloadsrequired integer nullable

downloadCountrequired integer

viewCountrequired integer

requireEmailrequired boolean

allowCommentsrequired boolean

viewOnlyrequired boolean

watermarkrequired boolean

availableFromrequired string (date-time) ISO 8601 timestamp · date-time, nullable

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

recipientsrequired

array of ShareRecipient

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`url`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

eventsrequired

array of object

Field	Type	Notes
`type`required	string
`at`required	string (date-time)	ISO 8601 timestamp · date-time
`ip`required	string	nullable
`userAgent`required	string	nullable
`recipient`required	string	nullable

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>/recipients" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["post@client.tv"],"phones":["…"]}'

GETList recipient comments#

/workspaces/{workspaceId}/shares/{shareId}/comments

SDK: shares.listComments · scope: receipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Response 200 · application/json

Field	Type	Notes
`id`required	string
`body`required	string
`author`required	string	nullable
`itemPath`required	string	nullable
`resolvedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>/comments" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTReply to recipients#

/workspaces/{workspaceId}/shares/{shareId}/comments

SDK: shares.reply · scope: shares:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Request body (application/json, required)

Field Type Notes

itemPath string max length 4096

bodyrequired string min length 1, max length 2000

parentId string max length 64

timecode string max length 20

timecodeMs integer minimum 0, maximum 2592000000

annotation

object

Field Type Notes

vrequired number

aspect number minimum 0.1, maximum 10

page integer minimum 1, maximum 50

strokesrequired

array of object

min items 1, max items 200

Field	Type	Notes
`tool`required	"pen" \| "arrow" \| "rect"
`color`required	string
`width`required	number	minimum 0.001, maximum 0.05
`points`required	array of array of items	min items 2, max items 2000

Response 201 · application/json

Field	Type	Notes
`id`required	string
`body`required	string
`author`required	string	nullable
`itemPath`required	string	nullable
`resolvedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>/comments" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemPath":"deliveries/ep01/EP01_final.mov","body":"Final grade, please confirm.","parentId":"ckz7…"}'

Receipts#

Delivery receipts, verification reports and delivery notes

GET Delivery receipt
GET Delivery receipt as PDF
GET Verification report as CSV
GET Printable delivery note

GETDelivery receipt#

/workspaces/{workspaceId}/shares/{shareId}/receipt

Who viewed, who downloaded, per-file checksums and whether every download verified.

SDK: receipts.get · scope: receipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Response 200 · application/json

Field Type Notes

receiptIdrequired string

sharerequired

object

Field	Type	Notes
`url`required	string
`title`required	string	nullable
`status`required	string
`hasPassword`required	boolean
`maxDownloads`required	integer	nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time
`expiresAt`required	string (date-time)	ISO 8601 timestamp · date-time
`viewCount`required	integer
`downloadCount`required	integer

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

totalBytesrequired number nullable

recipientsrequired

array of object

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloads`required	integer
`status`required	"sent" \| "viewed" \| "downloaded"

anonymousrequired

object

Field	Type	Notes
`views`required	integer
`downloads`required	integer

downloadsrequired

array of object

Field	Type	Notes
`transferId`required	string
`recipient`required	string	nullable
`client`required	string
`files`required	integer
`bytes`required	number
`rateMbps`required	number	nullable
`completedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`seconds`required	number	nullable

timelinerequired

array of object

Field	Type	Notes
`type`required	string
`at`required	string (date-time)	ISO 8601 timestamp · date-time
`recipient`required	string	nullable
`client`required	string	nullable

integrityrequired "verified" | "none"

filesrequired

array of object

Field	Type	Notes
`path`required	string
`sizeBytes`required	number	nullable
`checksumType`required	string	nullable
`checksum`required	string	nullable
`downloads`required	integer
`verifiedDownloads`required	integer
`verified`required	boolean

checksumTyperequired string

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>/receipt" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETDelivery receipt as PDF#

/workspaces/{workspaceId}/shares/{shareId}/receipt.pdf

SDK: receipts.pdf · scope: receipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Response 200 · application/pdf

string

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>/receipt.pdf" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETVerification report as CSV#

/workspaces/{workspaceId}/shares/{shareId}/receipt.csv

SDK: receipts.verificationCsv · scope: receipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Response 200 · text/csv

string

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>/receipt.csv" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETPrintable delivery note#

/workspaces/{workspaceId}/shares/{shareId}/delivery-note.pdf

SDK: receipts.deliveryNotePdf · scope: receipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`required	path	string

Response 200 · application/pdf

string

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/shares/<shareId>/delivery-note.pdf" \
  -H "Authorization: Bearer $BOITA_API_KEY"

Portals#

Upload portals and the uploads they receive

POST Create an upload portal
GET List upload portals
GET Get a portal with its uploads
PATCH Update or pause a portal
DELETE Revoke a portal
POST Approve or reject an upload

POSTCreate an upload portal#

/workspaces/{workspaceId}/portals

SDK: portals.create · scope: portals:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field Type Notes

fields

array of object

max items 20

Field	Type	Notes
`key`required	string	min length 1, max length 40
`label`required	string	min length 1, max length 80
`required`	boolean	· default false
`type`	"text" \| "select"	· default "text"
`options`	array of string	max items 50
`hint`	string	max length 200

rules

object

Field	Type	Notes
`allowedExtensions`	array of string	max items 50
`maxFiles`	integer	minimum 1, maximum 5000
`namePattern`	string	max length 200
`namePatternHint`	string	max length 200
`minBytes`	integer	minimum 0

spec

object

Field	Type	Notes
`name`	string	max length 80
`containers`	array of string	max items 20
`videoCodecs`	array of string	max items 20
`audioCodecs`	array of string	max items 20
`minWidth`	integer
`minHeight`	integer
`fps`	array of number	max items 10
`audioChannels`	array of integer	max items 5
`minDurationSeconds`	number	minimum 0
`maxDurationSeconds`	number

dueAt string (date-time) date-time

inviteEmails array of string (email) max items 100

invitePhones array of string max items 100

titlerequired string min length 1, max length 120

message string max length 2000

targetPath string max length 4096 · default ""

requireEmail boolean

password string min length 8, max length 256

maxBytesPerUpload integer

expiresInDays integer minimum 1, maximum 3650

notifyOnUpload boolean

projectId string max length 64, nullable

Response 201 · application/json

Field	Type	Notes
`id`required	string
`slug`required	string
`url`required	string
`title`required	string
`message`required	string	nullable
`targetPath`required	string
`requireEmail`required	boolean
`hasPassword`required	boolean
`maxBytesPerUpload`required	number	nullable
`expiresAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`notifyOnUpload`required	boolean
`status`required	"active" \| "paused" \| "revoked"
`uploadCount`required	integer
`bytesReceived`required	number
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/portals" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":[{"key":"…","label":"…","required":false}],"rules":{"allowedExtensions":["…"],"maxFiles":1,"namePattern":"…"},"spec":{"name":"EP01_final.mov","containers":["…"],"videoCodecs":["…"]},"title":"EP01 final"}'

GETList upload portals#

/workspaces/{workspaceId}/portals

SDK: portals.list · scopes: portals:writereceipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Response 200 · application/json

Field	Type	Notes
`id`required	string
`slug`required	string
`url`required	string
`title`required	string
`message`required	string	nullable
`targetPath`required	string
`requireEmail`required	boolean
`hasPassword`required	boolean
`maxBytesPerUpload`required	number	nullable
`expiresAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`notifyOnUpload`required	boolean
`status`required	"active" \| "paused" \| "revoked"
`uploadCount`required	integer
`bytesReceived`required	number
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/portals" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETGet a portal with its uploads#

/workspaces/{workspaceId}/portals/{portalId}

SDK: portals.get · scopes: portals:writereceipts:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`portalId`required	path	string

Response 200 · application/json

Field Type Notes

idrequired string

slugrequired string

urlrequired string

titlerequired string

messagerequired string nullable

targetPathrequired string

requireEmailrequired boolean

hasPasswordrequired boolean

maxBytesPerUploadrequired number nullable

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time, nullable

notifyOnUploadrequired boolean

statusrequired "active" | "paused" | "revoked"

uploadCountrequired integer

bytesReceivedrequired number

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

uploadsrequired

array of PortalUpload

Field	Type	Notes
`id`required	string
`senderEmail`required	string	nullable
`senderName`required	string	nullable
`message`required	string	nullable
`folderPath`required	string
`fileCount`required	integer	nullable
`bytesTotal`required	number	nullable
`bytesDone`required	number
`status`required	string
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time
`completedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/portals/<portalId>" \
  -H "Authorization: Bearer $BOITA_API_KEY"

PATCHUpdate or pause a portal#

/workspaces/{workspaceId}/portals/{portalId}

SDK: portals.update · scope: portals:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`portalId`required	path	string

Request body (application/json, required)

Field	Type	Notes
`projectId`	string	max length 64, nullable
`title`	string	min length 1, max length 120
`message`	string	max length 2000, nullable
`status`	"active" \| "paused"
`requireEmail`	boolean
`password`	string	min length 8, max length 256, nullable
`maxBytesPerUpload`	integer	nullable
`expiresInDays`	integer	minimum 1, maximum 3650, nullable
`notifyOnUpload`	boolean

Response 200 · application/json

Field	Type	Notes
`id`required	string
`slug`required	string
`url`required	string
`title`required	string
`message`required	string	nullable
`targetPath`required	string
`requireEmail`required	boolean
`hasPassword`required	boolean
`maxBytesPerUpload`required	number	nullable
`expiresAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`notifyOnUpload`required	boolean
`status`required	"active" \| "paused" \| "revoked"
`uploadCount`required	integer
`bytesReceived`required	number
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X PATCH "https://api.boita.io/v1/workspaces/$WORKSPACE/portals/<portalId>" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"ckz7…","title":"EP01 final","message":"Final grade, please confirm."}'

DELETERevoke a portal#

/workspaces/{workspaceId}/portals/{portalId}

SDK: portals.revoke · scope: portals:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`portalId`required	path	string

Response 204

No body.

curl -X DELETE "https://api.boita.io/v1/workspaces/$WORKSPACE/portals/<portalId>" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTApprove or reject an upload#

/workspaces/{workspaceId}/portals/{portalId}/uploads/{uploadId}/review

SDK: portals.reviewUpload · scope: portals:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`portalId`required	path	string
`uploadId`required	path	string

Request body (application/json, required)

Field	Type	Notes
`decision`required	"approved" \| "rejected" \| "pending"
`note`	string	max length 500

Response 200 · application/json

Field	Type	Notes
`id`required	string
`senderEmail`required	string	nullable
`senderName`required	string	nullable
`message`required	string	nullable
`folderPath`required	string
`fileCount`required	integer	nullable
`bytesTotal`required	number	nullable
`bytesDone`required	number
`status`required	string
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time
`completedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/portals/<portalId>/uploads/<uploadId>/review" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approved","note":"Final grade, please confirm."}'

Webhooks#

Endpoints, deliveries and the signed event stream

GET Event types an endpoint can subscribe to
POST Create a webhook endpoint
GET List webhook endpoints
PATCH Update, disable or re-enable an endpoint
DELETE Delete an endpoint
POST Rotate the signing secret
POST Send a webhook.test event to this endpoint
GET Recent deliveries to an endpoint
POST Retry a delivery now
POST Subscribe a REST hook
DELETE Unsubscribe a REST hook
GET A sample delivery for an event type

GETEvent types an endpoint can subscribe to#

/workspaces/{workspaceId}/webhooks/events

SDK: webhooks.eventTypes · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Response 200 · application/json

Field	Type	Notes
`events`required	array of string

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks/events" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTCreate a webhook endpoint#

/workspaces/{workspaceId}/webhooks

SDK: webhooks.create · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`url`required	string	min length 8, max length 2048
`events`required	array of string	min items 1, max items 50
`description`	string	max length 200

Response 201 · application/json

Field	Type	Notes
`id`required	string
`url`required	string
`description`required	string	nullable
`events`required	array of string
`status`required	"active" \| "disabled"
`failureCount`required	integer
`lastDeliveryAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time
`secret`required	string	Signing secret, shown once

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["…"],"description":"…"}'

GETList webhook endpoints#

/workspaces/{workspaceId}/webhooks

SDK: webhooks.list · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Response 200 · application/json

Field	Type	Notes
`id`required	string
`url`required	string
`description`required	string	nullable
`events`required	array of string
`status`required	"active" \| "disabled"
`failureCount`required	integer
`lastDeliveryAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks" \
  -H "Authorization: Bearer $BOITA_API_KEY"

PATCHUpdate, disable or re-enable an endpoint#

/workspaces/{workspaceId}/webhooks/{webhookId}

SDK: webhooks.update · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`webhookId`required	path	string

Request body (application/json, required)

Field	Type	Notes
`url`	string	min length 8, max length 2048
`events`	array of string	min items 1, max items 50
`description`	string	max length 200, nullable
`status`	"active" \| "disabled"

Response 200 · application/json

Field	Type	Notes
`id`required	string
`url`required	string
`description`required	string	nullable
`events`required	array of string
`status`required	"active" \| "disabled"
`failureCount`required	integer
`lastDeliveryAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X PATCH "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks/<webhookId>" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["…"],"description":"…"}'

DELETEDelete an endpoint#

/workspaces/{workspaceId}/webhooks/{webhookId}

SDK: webhooks.delete · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`webhookId`required	path	string

Response 204

No body.

curl -X DELETE "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks/<webhookId>" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTRotate the signing secret#

/workspaces/{workspaceId}/webhooks/{webhookId}/rotate-secret

SDK: webhooks.rotateSecret · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`webhookId`required	path	string

Response 201 · application/json

Field	Type	Notes
`id`required	string
`secret`required	string

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks/<webhookId>/rotate-secret" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTSend a webhook.test event to this endpoint#

/workspaces/{workspaceId}/webhooks/{webhookId}/test

SDK: webhooks.sendTest · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`webhookId`required	path	string

Response 201 · application/json

Field	Type	Notes
`eventId`required	string
`deliveryId`	string

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks/<webhookId>/test" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETRecent deliveries to an endpoint#

/workspaces/{workspaceId}/webhooks/{webhookId}/deliveries

SDK: webhooks.listDeliveries · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`webhookId`required	path	string

Response 200 · application/json

Field	Type	Notes
`id`required	string
`eventId`required	string
`type`required	string
`status`required	"pending" \| "delivered" \| "failed"
`attempts`required	integer
`nextAttemptAt`required	string (date-time)	ISO 8601 timestamp · date-time
`lastStatusCode`required	integer	nullable
`lastError`required	string	nullable
`deliveredAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks/<webhookId>/deliveries" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTRetry a delivery now#

/workspaces/{workspaceId}/webhooks/{webhookId}/deliveries/{deliveryId}/retry

SDK: webhooks.retryDelivery · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`webhookId`required	path	string
`deliveryId`required	path	string

Response 201 · application/json

Field	Type	Notes
`id`required	string
`status`required	string

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/webhooks/<webhookId>/deliveries/<deliveryId>/retry" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTSubscribe a REST hook#

/workspaces/{workspaceId}/hooks/subscribe

Zapier-style REST hook: creates a webhook endpoint for the event(s) and returns its id. Same limits as webhook endpoints (10 per workspace).

SDK: hooks.subscribe · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`target_url`required	string	Where to POST events (https) · min length 8, max length 2048
`event`	string	One event type (alternative to `events`) · min length 1, max length 64
`events`	array of string	Event types, or ["*"] · min items 1, max items 50
`source`	"zapier" \| "make" \| "n8n" \| "other"	Shown next to the endpoint on the Developers page

Response 201 · application/json

Field	Type	Notes
`id`required	string
`url`required	string
`events`required	array of string
`secret`required	string	Signing secret, shown once
`source`required	string
`unsubscribeUrl`required	string	Relative; DELETE it to unsubscribe

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/hooks/subscribe" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.com/hook","event":"…","events":["…"]}'

DELETEUnsubscribe a REST hook#

/workspaces/{workspaceId}/hooks/unsubscribe/{hookId}

SDK: hooks.unsubscribe · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`hookId`required	path	string

Response 204

No body.

curl -X DELETE "https://api.boita.io/v1/workspaces/$WORKSPACE/hooks/unsubscribe/<hookId>" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETA sample delivery for an event type#

/workspaces/{workspaceId}/hooks/sample

The exact envelope the worker POSTs, with realistic data, so a trigger can be built before the first event.

SDK: hooks.sample · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`event`required	query	string	min length 1, max length 64

Response 200 · application/json

Field Type Notes

idrequired string

typerequired string

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

workspaceIdrequired string

datarequired object

deliveryrequired

object

Field	Type	Notes
`id`required	string
`attempt`required	integer

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/hooks/sample?event=%E2%80%A6" \
  -H "Authorization: Bearer $BOITA_API_KEY"

Events#

Polling alternative to webhooks

GET Poll the workspace event stream

GETPoll the workspace event stream#

/workspaces/{workspaceId}/events

Pass `after` = the last id you saw to page forward; the same events webhooks deliver.

SDK: events.list · scope: webhooks:manage

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`after`	query	string	max length 64
`type`	query	string	max length 64
`limit`	query	integer	minimum 1, maximum 200

Response 200 · application/json

Field	Type	Notes
`id`required	string
`type`required	string
`data`required	object
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/events" \
  -H "Authorization: Bearer $BOITA_API_KEY"

Usage#

Storage and bandwidth figures

GET Storage usage and quota state
GET Bandwidth over the last 30 or 90 days

GETStorage usage and quota state#

/workspaces/{workspaceId}/usage

SDK: usage.summary · scope: usage:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Response 200 · application/json

Field Type Notes

quotaBytesrequired number

planCoderequired string

percentrequired number nullable

levelrequired integer

uploadsBlockedrequired boolean

latestrequired any

historyrequired

array of UsageSnapshot

Field	Type	Notes
`takenAt`required	string (date-time)	ISO 8601 timestamp · date-time
`bytesStored`required	number
`fileCount`required	integer
`bytesIn30d`required	number
`bytesOut30d`required	number

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/usage" \
  -H "Authorization: Bearer $BOITA_API_KEY"

GETBandwidth over the last 30 or 90 days#

/workspaces/{workspaceId}/usage/bandwidth

SDK: usage.bandwidth · scope: usage:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`days`	query	"30" \| "90"

Response 200 · application/json

Field	Type	Notes
`days`required	integer

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/usage/bandwidth" \
  -H "Authorization: Bearer $BOITA_API_KEY"

Cloud#

Deliveries to connected Google Drive, Dropbox, OneDrive and Box folders

POST Deliver files to a connected cloud folder
GET List cloud deliveries
POST Cancel a cloud delivery

POSTDeliver files to a connected cloud folder#

/workspaces/{workspaceId}/cloud/deliveries

Queues a server-side copy of a share's files (or explicit workspace paths) into a folder of a cloud account connected with delivery access. `destinationPath` is the provider-native folder locator from the web picker ("" = root).

SDK: cloud.deliver · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)

Request body (application/json, required)

Field	Type	Notes
`accountId`required	string	max length 64
`shareId`	string	max length 64
`sourcePaths`	array of string	max items 500
`destinationPath`	string	max length 2048 · default ""
`destinationLabel`	string	max length 300 · default ""
`overwrite`	boolean	· default false

Response 201 · application/json

Field Type Notes

idrequired string

accountrequired

object

Field	Type	Notes
`id`required	string
`provider`required	string
`label`required	string

shareIdrequired string nullable

sourcePathsrequired array of string

destinationPathrequired string

destinationLabelrequired string

overwriterequired boolean

statusrequired "queued" | "running" | "completed" | "failed" | "cancelled"

filesTotalrequired integer nullable

bytesTotalrequired number nullable

filesDonerequired integer

bytesDonerequired number

skippedrequired

array of object

nullable

Field	Type	Notes
`path`required	string
`reason`required	string

errorrequired string nullable

startedAtrequired string (date-time) date-time, nullable

finishedAtrequired string (date-time) date-time, nullable

createdAtrequired string (date-time) date-time

createdByrequired string

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/cloud/deliveries" \
  -H "Authorization: Bearer $BOITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"ckz7…","shareId":"ckz7…","sourcePaths":["deliveries/ep01/EP01_final.mov"]}'

GETList cloud deliveries#

/workspaces/{workspaceId}/cloud/deliveries

SDK: cloud.listDeliveries · scope: files:read

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`shareId`	query	string

Response 200 · application/json

Field Type Notes

idrequired string

accountrequired

object

Field	Type	Notes
`id`required	string
`provider`required	string
`label`required	string

shareIdrequired string nullable

sourcePathsrequired array of string

destinationPathrequired string

destinationLabelrequired string

overwriterequired boolean

statusrequired "queued" | "running" | "completed" | "failed" | "cancelled"

filesTotalrequired integer nullable

bytesTotalrequired number nullable

filesDonerequired integer

bytesDonerequired number

skippedrequired

array of object

nullable

Field	Type	Notes
`path`required	string
`reason`required	string

errorrequired string nullable

startedAtrequired string (date-time) date-time, nullable

finishedAtrequired string (date-time) date-time, nullable

createdAtrequired string (date-time) date-time

createdByrequired string

curl -X GET "https://api.boita.io/v1/workspaces/$WORKSPACE/cloud/deliveries" \
  -H "Authorization: Bearer $BOITA_API_KEY"

POSTCancel a cloud delivery#

/workspaces/{workspaceId}/cloud/deliveries/{deliveryId}/cancel

SDK: cloud.cancelDelivery · scope: files:write

Parameters

Name	In	Type	Notes
`workspaceId`required	path	string	The workspace id (the key is bound to one workspace)
`deliveryId`required	path	string

Response 200 · application/json

Field Type Notes

idrequired string

accountrequired

object

Field	Type	Notes
`id`required	string
`provider`required	string
`label`required	string

shareIdrequired string nullable

sourcePathsrequired array of string

destinationPathrequired string

destinationLabelrequired string

overwriterequired boolean

statusrequired "queued" | "running" | "completed" | "failed" | "cancelled"

filesTotalrequired integer nullable

bytesTotalrequired number nullable

filesDonerequired integer

bytesDonerequired number

skippedrequired

array of object

nullable

Field	Type	Notes
`path`required	string
`reason`required	string

errorrequired string nullable

startedAtrequired string (date-time) date-time, nullable

finishedAtrequired string (date-time) date-time, nullable

createdAtrequired string (date-time) date-time

createdByrequired string

curl -X POST "https://api.boita.io/v1/workspaces/$WORKSPACE/cloud/deliveries/<deliveryId>/cancel" \
  -H "Authorization: Bearer $BOITA_API_KEY"

Schemas#

Objects the operations above return, as named in the contract.

`FileEntry`#

Field	Type	Notes
`name`required	string
`path`required	string
`type`required	"file" \| "folder" \| "link"
`size`required	integer	nullable
`modifiedAt`required	string	nullable
`encrypted`required	boolean
`preview`	boolean

`FileListing`#

Field Type Notes

pathrequired string

accessrequired string

itemsrequired

array of FileEntry

Field	Type	Notes
`name`required	string
`path`required	string
`type`required	"file" \| "folder" \| "link"
`size`required	integer	nullable
`modifiedAt`required	string	nullable
`encrypted`required	boolean
`preview`	boolean

totalrequired integer

`SearchResult`#

Field Type Notes

itemsrequired

array of FileEntry

Field	Type	Notes
`name`required	string
`path`required	string
`type`required	"file" \| "folder" \| "link"
`size`required	integer	nullable
`modifiedAt`required	string	nullable
`encrypted`required	boolean
`preview`	boolean

`TrashItem`#

Field	Type	Notes
`id`required	string
`path`required	string
`name`required	string
`sizeBytes`required	number	nullable
`deletedAt`required	string (date-time)	ISO 8601 timestamp · date-time
`purgeAt`required	string (date-time)	ISO 8601 timestamp · date-time

`FileVersion`#

Field	Type	Notes
`id`required	string
`path`required	string
`sizeBytes`required	number	nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

`Ok`#

Field	Type	Notes
`ok`required	boolean

`Transfer`#

Field	Type	Notes
`id`required	string
`direction`required	"send" \| "receive"
`client`required	string
`engine`required	string
`status`required	"queued" \| "running" \| "paused" \| "completed" \| "failed" \| "cancelled"
`streams`required	integer
`priority`required	string
`usageId`required	string
`filesTotal`required	integer	nullable
`filesDone`required	integer
`bytesTotal`required	number	nullable
`bytesDone`required	number
`avgRateKbps`required	number	nullable
`startedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`finishedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`errorCode`required	string	nullable
`errorMessage`required	string	nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

`TransferCreated`#

Field	Type	Notes
`transferId`required	string
`transferSpec`required	object	Hand this to the transfer engine unchanged; it is valid for a short window.
`expiresAt`required	string (date-time)	ISO 8601 timestamp · date-time

`ShareItem`#

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

`ShareRecipient`#

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`url`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

`Share`#

Field Type Notes

idrequired string

slugrequired string

urlrequired string Relative on the app host, absolute on a custom domain

moderequired "drive" | "send"

titlerequired string nullable

messagerequired string nullable

hasPasswordrequired boolean

statusrequired string

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time

maxDownloadsrequired integer nullable

downloadCountrequired integer

viewCountrequired integer

requireEmailrequired boolean

allowCommentsrequired boolean

viewOnlyrequired boolean

watermarkrequired boolean

availableFromrequired string (date-time) ISO 8601 timestamp · date-time, nullable

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

recipientsrequired

array of ShareRecipient

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`url`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

`ShareDetail`#

Field Type Notes

idrequired string

slugrequired string

urlrequired string Relative on the app host, absolute on a custom domain

moderequired "drive" | "send"

titlerequired string nullable

messagerequired string nullable

hasPasswordrequired boolean

statusrequired string

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time

maxDownloadsrequired integer nullable

downloadCountrequired integer

viewCountrequired integer

requireEmailrequired boolean

allowCommentsrequired boolean

viewOnlyrequired boolean

watermarkrequired boolean

availableFromrequired string (date-time) ISO 8601 timestamp · date-time, nullable

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

recipientsrequired

array of ShareRecipient

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`url`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

eventsrequired

array of object

Field	Type	Notes
`type`required	string
`at`required	string (date-time)	ISO 8601 timestamp · date-time
`ip`required	string	nullable
`userAgent`required	string	nullable
`recipient`required	string	nullable

`BulkResult`#

Field Type Notes

donerequired integer

failed

array of object

Field	Type	Notes
`id`required	string
`error`required	string

`Comment`#

Field	Type	Notes
`id`required	string
`body`required	string
`author`required	string	nullable
`itemPath`required	string	nullable
`resolvedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

`Receipt`#

Field Type Notes

receiptIdrequired string

sharerequired

object

Field	Type	Notes
`url`required	string
`title`required	string	nullable
`status`required	string
`hasPassword`required	boolean
`maxDownloads`required	integer	nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time
`expiresAt`required	string (date-time)	ISO 8601 timestamp · date-time
`viewCount`required	integer
`downloadCount`required	integer

itemsrequired

array of ShareItem

Field	Type	Notes
`path`required	string
`name`required	string
`type`required	"file" \| "folder"
`sizeBytes`required	number	nullable

totalBytesrequired number nullable

recipientsrequired

array of object

Field	Type	Notes
`email`required	string	nullable
`phone`required	string	nullable
`label`required	string
`firstViewedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloadedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`verifiedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`downloads`required	integer
`status`required	"sent" \| "viewed" \| "downloaded"

anonymousrequired

object

Field	Type	Notes
`views`required	integer
`downloads`required	integer

downloadsrequired

array of object

Field	Type	Notes
`transferId`required	string
`recipient`required	string	nullable
`client`required	string
`files`required	integer
`bytes`required	number
`rateMbps`required	number	nullable
`completedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`seconds`required	number	nullable

timelinerequired

array of object

Field	Type	Notes
`type`required	string
`at`required	string (date-time)	ISO 8601 timestamp · date-time
`recipient`required	string	nullable
`client`required	string	nullable

integrityrequired "verified" | "none"

filesrequired

array of object

Field	Type	Notes
`path`required	string
`sizeBytes`required	number	nullable
`checksumType`required	string	nullable
`checksum`required	string	nullable
`downloads`required	integer
`verifiedDownloads`required	integer
`verified`required	boolean

checksumTyperequired string

`Portal`#

Field	Type	Notes
`id`required	string
`slug`required	string
`url`required	string
`title`required	string
`message`required	string	nullable
`targetPath`required	string
`requireEmail`required	boolean
`hasPassword`required	boolean
`maxBytesPerUpload`required	number	nullable
`expiresAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`notifyOnUpload`required	boolean
`status`required	"active" \| "paused" \| "revoked"
`uploadCount`required	integer
`bytesReceived`required	number
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

`PortalUpload`#

Field	Type	Notes
`id`required	string
`senderEmail`required	string	nullable
`senderName`required	string	nullable
`message`required	string	nullable
`folderPath`required	string
`fileCount`required	integer	nullable
`bytesTotal`required	number	nullable
`bytesDone`required	number
`status`required	string
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time
`completedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

`PortalDetail`#

Field Type Notes

idrequired string

slugrequired string

urlrequired string

titlerequired string

messagerequired string nullable

targetPathrequired string

requireEmailrequired boolean

hasPasswordrequired boolean

maxBytesPerUploadrequired number nullable

expiresAtrequired string (date-time) ISO 8601 timestamp · date-time, nullable

notifyOnUploadrequired boolean

statusrequired "active" | "paused" | "revoked"

uploadCountrequired integer

bytesReceivedrequired number

createdAtrequired string (date-time) ISO 8601 timestamp · date-time

uploadsrequired

array of PortalUpload

Field	Type	Notes
`id`required	string
`senderEmail`required	string	nullable
`senderName`required	string	nullable
`message`required	string	nullable
`folderPath`required	string
`fileCount`required	integer	nullable
`bytesTotal`required	number	nullable
`bytesDone`required	number
`status`required	string
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time
`completedAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable

`Webhook`#

Field	Type	Notes
`id`required	string
`url`required	string
`description`required	string	nullable
`events`required	array of string
`status`required	"active" \| "disabled"
`failureCount`required	integer
`lastDeliveryAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

`WebhookCreated`#

Field	Type	Notes
`id`required	string
`url`required	string
`description`required	string	nullable
`events`required	array of string
`status`required	"active" \| "disabled"
`failureCount`required	integer
`lastDeliveryAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time
`secret`required	string	Signing secret, shown once

`WebhookSecret`#

Field	Type	Notes
`id`required	string
`secret`required	string

`WebhookDelivery`#

Field	Type	Notes
`id`required	string
`eventId`required	string
`type`required	string
`status`required	"pending" \| "delivered" \| "failed"
`attempts`required	integer
`nextAttemptAt`required	string (date-time)	ISO 8601 timestamp · date-time
`lastStatusCode`required	integer	nullable
`lastError`required	string	nullable
`deliveredAt`required	string (date-time)	ISO 8601 timestamp · date-time, nullable
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

`DeliveryQueued`#

Field	Type	Notes
`id`required	string
`status`required	string

`TestQueued`#

Field	Type	Notes
`eventId`required	string
`deliveryId`	string

`EventCatalogue`#

Field	Type	Notes
`events`required	array of string

`WorkspaceEvent`#

Field	Type	Notes
`id`required	string
`type`required	string
`data`required	object
`createdAt`required	string (date-time)	ISO 8601 timestamp · date-time

`UsageSnapshot`#

Field	Type	Notes
`takenAt`required	string (date-time)	ISO 8601 timestamp · date-time
`bytesStored`required	number
`fileCount`required	integer
`bytesIn30d`required	number
`bytesOut30d`required	number

`UsageSummary`#

Field Type Notes

quotaBytesrequired number

planCoderequired string

percentrequired number nullable

levelrequired integer

uploadsBlockedrequired boolean

latestrequired any

historyrequired

array of UsageSnapshot

Field	Type	Notes
`takenAt`required	string (date-time)	ISO 8601 timestamp · date-time
`bytesStored`required	number
`fileCount`required	integer
`bytesIn30d`required	number
`bytesOut30d`required	number

`Bandwidth`#

Field	Type	Notes
`days`required	integer

`Error`#

Every error response

Field Type Notes

errorrequired

object

Field	Type	Notes
`code`required	"unauthenticated" \| "email_unverified" \| "mfa_required" \| "forbidden" \| "not_found" \| "validation_failed" \| "path_rejected" \| "quota_exceeded" \| "scheduled_hold" \| "plan_limit" \| "rate_limited" \| "share_expired" \| "share_locked" \| "node_unavailable" \| "node_busy" \| "conflict" \| "internal" \| "authorization_pending" \| "slow_down" \| "access_denied" \| "expired_token"
`message`required	string
`details`	any

Error codes#

The code field of the error envelope takes one of these values; the HTTP status says which class it is.

access_denied
authorization_pending
email_unverified
expired_token
forbidden
mfa_required
node_busy
not_found
path_rejected
plan_limit
rate_limited
slow_down
unauthenticated
validation_failed