{ "openapi": "3.1.0", "info": { "title": "Boita API", "version": "1.0.0", "description": "The Boita public API: files, transfers, share links, upload portals, delivery receipts, webhooks and usage for one workspace.\n\nAuthenticate with a workspace API key (`Authorization: Bearer boita_sk_…`) created on the Developers page. A key is bound to one workspace and carries scopes; each operation lists the scopes that allow it (any one is enough).\n\nErrors always look like `{ \"error\": { \"code\", \"message\", \"details\" } }`. Rate limit: 600 requests per minute per key (429 `rate_limited` beyond that).\n\nTransfers are never carried by this API: `POST …/transfers` returns a transfer spec for the transfer engine (the desktop app, the CLI agent or a gateway) to run.", "contact": { "name": "Boita support", "url": "https://boita.io/contact" } }, "servers": [ { "url": "https://api.boita.io/v1" } ], "tags": [ { "name": "Files", "description": "Browse, search and organise the workspace" }, { "name": "Transfers", "description": "Transfer specs and progress" }, { "name": "Shares", "description": "Share links and recipient comments" }, { "name": "Receipts", "description": "Delivery receipts, verification reports and delivery notes" }, { "name": "Portals", "description": "Upload portals and the uploads they receive" }, { "name": "Webhooks", "description": "Endpoints, deliveries and the signed event stream" }, { "name": "Events", "description": "Polling alternative to webhooks" }, { "name": "Usage", "description": "Storage and bandwidth figures" }, { "name": "Cloud", "description": "Deliveries to connected Google Drive, Dropbox, OneDrive and Box folders" } ], "security": [ { "apiKey": [] } ], "paths": { "/workspaces/{workspaceId}/files": { "get": { "operationId": "files.list", "summary": "List a folder", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "list", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4096, "default": "" } }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileListing" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "files.rename", "summary": "Rename a file or folder", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "rename", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "newName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "path", "newName" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "files.delete", "summary": "Move files to the trash (or delete permanently)", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "delete", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "minItems": 1, "maxItems": 500 }, "permanent": { "type": "boolean", "default": false } }, "required": [ "paths" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/search": { "get": { "operationId": "files.search", "summary": "Search files by name", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "search", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4096, "default": "" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/manifest": { "get": { "operationId": "files.manifest", "summary": "Every file under a folder with size and modification time (for sync clients)", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "manifest", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4096, "default": "", "description": "Workspace-relative folder; empty = the root" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "root": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "modifiedAt": { "type": [ "string", "null" ] } }, "required": [ "path", "size", "modifiedAt" ] } }, "truncated": { "type": "boolean" } }, "required": [ "root", "files", "truncated" ], "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/folder": { "post": { "operationId": "files.createFolder", "summary": "Create a folder", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "createFolder", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "path" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/trash": { "get": { "operationId": "files.listTrash", "summary": "List the trash", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "listTrash", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrashItem" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/trash/{itemId}/restore": { "post": { "operationId": "files.restoreFromTrash", "summary": "Restore a trashed item", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "restoreFromTrash", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/trash/{itemId}": { "delete": { "operationId": "files.purgeFromTrash", "summary": "Purge one trashed item now", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "purgeFromTrash", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/versions": { "get": { "operationId": "files.listVersions", "summary": "List kept versions of a file", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "listVersions", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileVersion" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/versions/{versionId}/restore": { "post": { "operationId": "files.restoreVersion", "summary": "Restore a kept version", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "restoreVersion", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/preview": { "get": { "operationId": "files.preview", "summary": "Thumbnail of a file", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "preview", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 4096 } } ], "responses": { "200": { "description": "OK", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/proxies": { "get": { "operationId": "files.proxyStatus", "summary": "Rendered proxies of a file", "description": "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.", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "proxyStatus", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4096, "default": "" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9]{10,40}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": [ "string", "null" ], "enum": [ "video", "audio", "image", "pdf" ] }, "fps": { "type": [ "number", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "proxies": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "proxy720", "waveform", "contact_sheet", "page" ] }, "page": { "type": "integer" }, "status": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "kind", "page", "status", "width", "height", "durationMs", "error" ] } } }, "required": [ "media", "fps", "durationMs", "proxies" ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "post": { "operationId": "files.renderProxies", "summary": "Render proxies now", "description": "Queues the proxies a file (or a kept version) needs. Video and audio queue on upload; images and PDFs render on demand.", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "renderProxies", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "maxItems": 50 }, "versions": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]{10,40}$" }, "maxItems": 50 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "integer" } }, "required": [ "queued" ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/proxy": { "get": { "operationId": "files.proxy", "summary": "A rendered proxy (supports Range)", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "proxy", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4096, "default": "", "description": "Workspace-relative path; omit when `version` is given" } }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "proxy720", "waveform", "contact_sheet", "page" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 50, "default": 0 } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9]{10,40}$", "description": "A kept version id instead of the live file" } } ], "responses": { "200": { "description": "OK", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/operations": { "post": { "operationId": "files.createOperation", "summary": "Queue a server-side move or copy", "description": "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).", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "createOperation", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "move", "copy" ] }, "paths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "minItems": 1, "maxItems": 200 }, "destination": { "type": "string", "maxLength": 4096, "default": "" }, "overwrite": { "type": "boolean", "default": false }, "expandSequences": { "type": "boolean", "default": true } }, "required": [ "kind", "paths" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "move", "copy" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "destination": { "type": "string" }, "overwrite": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "folder" ] }, "bytes": { "type": "number" } }, "required": [ "path", "type", "bytes" ] } }, "filesTotal": { "type": "integer" }, "filesDone": { "type": "integer" }, "bytesTotal": { "type": "number" }, "bytesDone": { "type": "number" }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "kind", "status", "destination", "overwrite", "items", "filesTotal", "filesDone", "bytesTotal", "bytesDone", "error", "createdAt", "startedAt", "finishedAt" ], "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "files.listOperations", "summary": "Move/copy jobs of the workspace", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "listOperations", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1", "true" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "move", "copy" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "destination": { "type": "string" }, "overwrite": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "folder" ] }, "bytes": { "type": "number" } }, "required": [ "path", "type", "bytes" ] } }, "filesTotal": { "type": "integer" }, "filesDone": { "type": "integer" }, "bytesTotal": { "type": "number" }, "bytesDone": { "type": "number" }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "kind", "status", "destination", "overwrite", "items", "filesTotal", "filesDone", "bytesTotal", "bytesDone", "error", "createdAt", "startedAt", "finishedAt" ], "additionalProperties": true } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/operations/{jobId}/cancel": { "post": { "operationId": "files.cancelOperation", "summary": "Cancel a queued or running move/copy job", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "cancelOperation", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "move", "copy" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "destination": { "type": "string" }, "overwrite": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "folder" ] }, "bytes": { "type": "number" } }, "required": [ "path", "type", "bytes" ] } }, "filesTotal": { "type": "integer" }, "filesDone": { "type": "integer" }, "bytesTotal": { "type": "number" }, "bytesDone": { "type": "number" }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "kind", "status", "destination", "overwrite", "items", "filesTotal", "filesDone", "bytesTotal", "bytesDone", "error", "createdAt", "startedAt", "finishedAt" ], "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/files/rename-batch": { "post": { "operationId": "files.renameBatch", "summary": "Rename many items with a pattern (preview with dryRun)", "description": "Find/replace, prefix/suffix and numbering with padding. `dryRun: true` returns the plan and conflicts without touching anything; the apply runs exactly that plan.", "tags": [ "Files" ], "x-boita-group": "files", "x-boita-method": "renameBatch", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "minItems": 1, "maxItems": 200 }, "pattern": { "type": "object", "properties": { "find": { "type": "string", "maxLength": 255 }, "replace": { "type": "string", "maxLength": 255 }, "regex": { "type": "boolean" }, "ignoreCase": { "type": "boolean" }, "includeExtension": { "type": "boolean" }, "prefix": { "type": "string", "maxLength": 120 }, "suffix": { "type": "string", "maxLength": 120 }, "numbering": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "maximum": 999999, "default": 1 }, "step": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "padding": { "type": "integer", "minimum": 1, "maximum": 8, "default": 3 }, "position": { "type": "string", "enum": [ "prefix", "suffix", "replace" ], "default": "suffix" }, "separator": { "type": "string", "maxLength": 8, "default": "_" } } } } }, "dryRun": { "type": "boolean", "default": false }, "overwrite": { "type": "boolean", "default": false }, "expandSequences": { "type": "boolean", "default": true } }, "required": [ "paths", "pattern" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "expanded": { "type": "integer" }, "changed": { "type": "integer" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "name": { "type": "string" }, "newName": { "type": "string" }, "changed": { "type": "boolean" } }, "required": [ "from", "to", "name", "newName", "changed" ] } }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string", "enum": [ "duplicate_target", "exists", "invalid" ] } }, "required": [ "path", "name", "reason" ] } }, "applied": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } }, "failed": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "error": { "type": "string" } }, "required": [ "from", "to", "error" ] } }, "required": [ "dryRun", "expanded", "changed", "steps", "conflicts", "applied", "failed" ], "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/transfers": { "post": { "operationId": "transfers.create", "summary": "Request a transfer spec", "description": "Returns a spec the transfer engine (Boita desktop, the CLI agent or a gateway) runs; the API never moves bytes itself.", "tags": [ "Transfers" ], "x-boita-group": "transfers", "x-boita-method": "create", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "send", "receive" ] }, "paths": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 4096 }, "destination": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "source" ] }, "minItems": 1, "maxItems": 10000 }, "destinationRoot": { "anyOf": [ { "const": "", "type": "string" }, { "type": "string", "minLength": 1, "maxLength": 4096 } ] }, "sourceRoot": { "anyOf": [ { "const": "", "type": "string" }, { "type": "string", "minLength": 1, "maxLength": 4096 } ] }, "fileCount": { "type": "integer", "minimum": 0 }, "totalBytes": { "type": "integer", "minimum": 0 }, "streams": { "type": "integer", "minimum": 1, "maximum": 128 }, "growingFileWaitSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "contentProtectionPassword": { "type": "string", "minLength": 8, "maxLength": 256 }, "priority": { "type": "string", "enum": [ "normal", "deadline", "background" ] }, "deliverTo": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "rawAscp": { "type": "boolean" }, "speedMode": { "type": "boolean" }, "client": { "type": "string", "enum": [ "web", "desktop", "mobile", "gateway", "share", "portal", "agent" ], "default": "agent" }, "deviceId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,64}$" }, "shareId": { "type": "string" }, "portalId": { "type": "string" } }, "required": [ "direction", "paths" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferCreated" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "transfers.list", "summary": "List recent transfers", "tags": [ "Transfers" ], "x-boita-group": "transfers", "x-boita-method": "list", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/transfers/{transferId}": { "get": { "operationId": "transfers.get", "summary": "Get one transfer", "tags": [ "Transfers" ], "x-boita-group": "transfers", "x-boita-method": "get", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transfer" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "transfers.reportProgress", "summary": "Report client-side progress", "tags": [ "Transfers" ], "x-boita-group": "transfers", "x-boita-method": "reportProgress", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "running", "paused", "completed", "failed", "cancelled" ] }, "bytesDone": { "type": "integer", "minimum": 0 }, "bytesTotal": { "type": "integer", "minimum": 0 }, "filesDone": { "type": "integer", "minimum": 0 }, "filesTotal": { "type": "integer", "minimum": 0 }, "rateKbps": { "type": "number", "minimum": 0 }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string", "maxLength": 500 } }, "required": [ "status", "bytesDone", "filesDone" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transfer" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares": { "post": { "operationId": "shares.create", "summary": "Create a share link", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "create", "x-boita-scopes": [ "shares:write" ], "security": [ { "apiKey": [ "shares:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "drive", "send" ], "default": "drive" }, "paths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "minItems": 1, "maxItems": 500 }, "title": { "type": "string", "maxLength": 200 }, "message": { "type": "string", "maxLength": 4000 }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "maxDownloads": { "type": "integer", "minimum": 1, "maximum": 100000 }, "password": { "type": "string", "minLength": 8, "maxLength": 256 }, "notifyOnDownload": { "type": "boolean" }, "allowPreview": { "type": "boolean" }, "allowComments": { "type": "boolean" }, "requireEmail": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 200 }, "phones": { "type": "array", "items": { "type": "string", "minLength": 8, "maxLength": 20 }, "maxItems": 200 }, "availableFrom": { "type": "string", "format": "date-time" }, "viewOnly": { "type": "boolean" }, "watermark": { "type": "boolean" }, "templateId": { "type": "string", "maxLength": 64 }, "recipientGroups": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 20 }, "reviewRoles": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "viewer", "reviewer", "approver" ] } }, "projectId": { "type": [ "string", "null" ], "maxLength": 64 }, "locale": { "type": [ "string", "null" ], "enum": [ "en" ] } }, "required": [ "paths" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Share" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "shares.list", "summary": "List share links", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "list", "x-boita-scopes": [ "shares:write", "receipts:read" ], "security": [ { "apiKey": [ "shares:write", "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Share" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares/{shareId}": { "get": { "operationId": "shares.get", "summary": "Get a share link with its activity", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "get", "x-boita-scopes": [ "shares:write", "receipts:read" ], "security": [ { "apiKey": [ "shares:write", "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareDetail" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "shares.extend", "summary": "Extend a share link", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "extend", "x-boita-scopes": [ "shares:write" ], "security": [ { "apiKey": [ "shares:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "projectId": { "type": [ "string", "null" ], "maxLength": 64 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Share" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "shares.revoke", "summary": "Revoke a share link", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "revoke", "x-boita-scopes": [ "shares:write" ], "security": [ { "apiKey": [ "shares:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares/bulk": { "post": { "operationId": "shares.bulk", "summary": "Extend, revoke or re-notify many links", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "bulk", "x-boita-scopes": [ "shares:write" ], "security": [ { "apiKey": [ "shares:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 200 }, "action": { "type": "string", "enum": [ "extend", "revoke", "renotify" ] }, "days": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "required": [ "ids", "action" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares/{shareId}/recipients": { "post": { "operationId": "shares.addRecipients", "summary": "Add recipients (email or WhatsApp number) to a live link", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "addRecipients", "x-boita-scopes": [ "shares:write" ], "security": [ { "apiKey": [ "shares:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 200 }, "phones": { "type": "array", "items": { "type": "string", "minLength": 8, "maxLength": 20 }, "maxItems": 200 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareDetail" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares/{shareId}/comments": { "get": { "operationId": "shares.listComments", "summary": "List recipient comments", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "listComments", "x-boita-scopes": [ "receipts:read" ], "security": [ { "apiKey": [ "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "post": { "operationId": "shares.reply", "summary": "Reply to recipients", "tags": [ "Shares" ], "x-boita-group": "shares", "x-boita-method": "reply", "x-boita-scopes": [ "shares:write" ], "security": [ { "apiKey": [ "shares:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemPath": { "type": "string", "maxLength": 4096 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "parentId": { "type": "string", "maxLength": 64 }, "timecode": { "type": "string", "maxLength": 20 }, "timecodeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000 }, "annotation": { "type": "object", "properties": { "v": { "const": 1, "type": "number" }, "aspect": { "type": "number", "minimum": 0.1, "maximum": 10 }, "page": { "type": "integer", "minimum": 1, "maximum": 50 }, "strokes": { "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "pen", "arrow", "rect" ] }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "width": { "type": "number", "minimum": 0.001, "maximum": 0.05 }, "points": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "number", "minimum": 0, "maximum": 1 } ], "items": false }, "minItems": 2, "maxItems": 2000 } }, "required": [ "tool", "color", "width", "points" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "v", "strokes" ] } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares/{shareId}/receipt": { "get": { "operationId": "receipts.get", "summary": "Delivery receipt", "description": "Who viewed, who downloaded, per-file checksums and whether every download verified.", "tags": [ "Receipts" ], "x-boita-group": "receipts", "x-boita-method": "get", "x-boita-scopes": [ "receipts:read" ], "security": [ { "apiKey": [ "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares/{shareId}/receipt.pdf": { "get": { "operationId": "receipts.pdf", "summary": "Delivery receipt as PDF", "tags": [ "Receipts" ], "x-boita-group": "receipts", "x-boita-method": "pdf", "x-boita-scopes": [ "receipts:read" ], "security": [ { "apiKey": [ "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares/{shareId}/receipt.csv": { "get": { "operationId": "receipts.verificationCsv", "summary": "Verification report as CSV", "tags": [ "Receipts" ], "x-boita-group": "receipts", "x-boita-method": "verificationCsv", "x-boita-scopes": [ "receipts:read" ], "security": [ { "apiKey": [ "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/shares/{shareId}/delivery-note.pdf": { "get": { "operationId": "receipts.deliveryNotePdf", "summary": "Printable delivery note", "tags": [ "Receipts" ], "x-boita-group": "receipts", "x-boita-method": "deliveryNotePdf", "x-boita-scopes": [ "receipts:read" ], "security": [ { "apiKey": [ "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/portals": { "post": { "operationId": "portals.create", "summary": "Create an upload portal", "tags": [ "Portals" ], "x-boita-group": "portals", "x-boita-method": "create", "x-boita-scopes": [ "portals:write" ], "security": [ { "apiKey": [ "portals:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9_]+$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean", "default": false }, "type": { "type": "string", "enum": [ "text", "select" ], "default": "text" }, "options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 50 }, "hint": { "type": "string", "maxLength": 200 } }, "required": [ "key", "label" ] }, "maxItems": 20 }, "rules": { "type": "object", "properties": { "allowedExtensions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 12, "pattern": "^[a-z0-9]+$" }, "maxItems": 50 }, "maxFiles": { "type": "integer", "minimum": 1, "maximum": 5000 }, "namePattern": { "type": "string", "maxLength": 200 }, "namePatternHint": { "type": "string", "maxLength": 200 }, "minBytes": { "type": "integer", "minimum": 0 } } }, "spec": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "containers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20 }, "maxItems": 20 }, "videoCodecs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 30 }, "maxItems": 20 }, "audioCodecs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 30 }, "maxItems": 20 }, "minWidth": { "type": "integer", "exclusiveMinimum": 0 }, "minHeight": { "type": "integer", "exclusiveMinimum": 0 }, "fps": { "type": "array", "items": { "type": "number", "exclusiveMinimum": 0 }, "maxItems": 10 }, "audioChannels": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0 }, "maxItems": 5 }, "minDurationSeconds": { "type": "number", "minimum": 0 }, "maxDurationSeconds": { "type": "number", "exclusiveMinimum": 0 } } }, "dueAt": { "type": "string", "format": "date-time" }, "inviteEmails": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 100 }, "invitePhones": { "type": "array", "items": { "type": "string", "minLength": 8, "maxLength": 20 }, "maxItems": 100 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "message": { "type": "string", "maxLength": 2000 }, "targetPath": { "type": "string", "maxLength": 4096, "default": "" }, "requireEmail": { "type": "boolean" }, "password": { "type": "string", "minLength": 8, "maxLength": 256 }, "maxBytesPerUpload": { "type": "integer", "exclusiveMinimum": 0 }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "notifyOnUpload": { "type": "boolean" }, "projectId": { "type": [ "string", "null" ], "maxLength": 64 } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Portal" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "portals.list", "summary": "List upload portals", "tags": [ "Portals" ], "x-boita-group": "portals", "x-boita-method": "list", "x-boita-scopes": [ "portals:write", "receipts:read" ], "security": [ { "apiKey": [ "portals:write", "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Portal" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/portals/{portalId}": { "get": { "operationId": "portals.get", "summary": "Get a portal with its uploads", "tags": [ "Portals" ], "x-boita-group": "portals", "x-boita-method": "get", "x-boita-scopes": [ "portals:write", "receipts:read" ], "security": [ { "apiKey": [ "portals:write", "receipts:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "portalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalDetail" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "portals.update", "summary": "Update or pause a portal", "tags": [ "Portals" ], "x-boita-group": "portals", "x-boita-method": "update", "x-boita-scopes": [ "portals:write" ], "security": [ { "apiKey": [ "portals:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "portalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": [ "string", "null" ], "maxLength": 64 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "message": { "type": [ "string", "null" ], "maxLength": 2000 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "requireEmail": { "type": "boolean" }, "password": { "type": [ "string", "null" ], "minLength": 8, "maxLength": 256 }, "maxBytesPerUpload": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "expiresInDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650 }, "notifyOnUpload": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Portal" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "portals.revoke", "summary": "Revoke a portal", "tags": [ "Portals" ], "x-boita-group": "portals", "x-boita-method": "revoke", "x-boita-scopes": [ "portals:write" ], "security": [ { "apiKey": [ "portals:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "portalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/portals/{portalId}/uploads/{uploadId}/review": { "post": { "operationId": "portals.reviewUpload", "summary": "Approve or reject an upload", "tags": [ "Portals" ], "x-boita-group": "portals", "x-boita-method": "reviewUpload", "x-boita-scopes": [ "portals:write" ], "security": [ { "apiKey": [ "portals:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "portalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected", "pending" ] }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "decision" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalUpload" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/webhooks/events": { "get": { "operationId": "webhooks.eventTypes", "summary": "Event types an endpoint can subscribe to", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "eventTypes", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCatalogue" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/webhooks": { "post": { "operationId": "webhooks.create", "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "create", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 50 }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "webhooks.list", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "list", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/webhooks/{webhookId}": { "patch": { "operationId": "webhooks.update", "summary": "Update, disable or re-enable an endpoint", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "update", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 50 }, "description": { "type": [ "string", "null" ], "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "webhooks.delete", "summary": "Delete an endpoint", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "delete", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/webhooks/{webhookId}/rotate-secret": { "post": { "operationId": "webhooks.rotateSecret", "summary": "Rotate the signing secret", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "rotateSecret", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecret" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/webhooks/{webhookId}/test": { "post": { "operationId": "webhooks.sendTest", "summary": "Send a webhook.test event to this endpoint", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "sendTest", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestQueued" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/webhooks/{webhookId}/deliveries": { "get": { "operationId": "webhooks.listDeliveries", "summary": "Recent deliveries to an endpoint", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "listDeliveries", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/webhooks/{webhookId}/deliveries/{deliveryId}/retry": { "post": { "operationId": "webhooks.retryDelivery", "summary": "Retry a delivery now", "tags": [ "Webhooks" ], "x-boita-group": "webhooks", "x-boita-method": "retryDelivery", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryQueued" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/hooks/subscribe": { "post": { "operationId": "hooks.subscribe", "summary": "Subscribe a REST hook", "description": "Zapier-style REST hook: creates a webhook endpoint for the event(s) and returns its id. Same limits as webhook endpoints (10 per workspace).", "tags": [ "Webhooks" ], "x-boita-group": "hooks", "x-boita-method": "subscribe", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string", "minLength": 8, "maxLength": 2048, "description": "Where to POST events (https)" }, "event": { "type": "string", "minLength": 1, "maxLength": 64, "description": "One event type (alternative to `events`)" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 50, "description": "Event types, or [\"*\"]" }, "source": { "type": "string", "enum": [ "zapier", "make", "n8n", "other" ], "description": "Shown next to the endpoint on the Developers page" } }, "required": [ "target_url" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "description": "Signing secret, shown once" }, "source": { "type": "string" }, "unsubscribeUrl": { "type": "string", "description": "Relative; DELETE it to unsubscribe" } }, "required": [ "id", "url", "events", "secret", "source", "unsubscribeUrl" ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/hooks/unsubscribe/{hookId}": { "delete": { "operationId": "hooks.unsubscribe", "summary": "Unsubscribe a REST hook", "tags": [ "Webhooks" ], "x-boita-group": "hooks", "x-boita-method": "unsubscribe", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "hookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/hooks/sample": { "get": { "operationId": "hooks.sample", "summary": "A sample delivery for an event type", "description": "The exact envelope the worker POSTs, with realistic data, so a trigger can be built before the first event.", "tags": [ "Webhooks" ], "x-boita-group": "hooks", "x-boita-method": "sample", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "event", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "workspaceId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "attempt": { "type": "integer" } }, "required": [ "id", "attempt" ] } }, "required": [ "id", "type", "createdAt", "workspaceId", "data", "delivery" ], "description": "One delivery as the worker POSTs it" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/events": { "get": { "operationId": "events.list", "summary": "Poll the workspace event stream", "description": "Pass `after` = the last id you saw to page forward; the same events webhooks deliver.", "tags": [ "Events" ], "x-boita-group": "events", "x-boita-method": "list", "x-boita-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [ "webhooks:manage" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceEvent" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/usage": { "get": { "operationId": "usage.summary", "summary": "Storage usage and quota state", "tags": [ "Usage" ], "x-boita-group": "usage", "x-boita-method": "summary", "x-boita-scopes": [ "usage:read" ], "security": [ { "apiKey": [ "usage:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/usage/bandwidth": { "get": { "operationId": "usage.bandwidth", "summary": "Bandwidth over the last 30 or 90 days", "tags": [ "Usage" ], "x-boita-group": "usage", "x-boita-method": "bandwidth", "x-boita-scopes": [ "usage:read" ], "security": [ { "apiKey": [ "usage:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "30", "90" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bandwidth" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/cloud/deliveries": { "post": { "operationId": "cloud.deliver", "summary": "Deliver files to a connected cloud folder", "description": "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).", "tags": [ "Cloud" ], "x-boita-group": "cloud", "x-boita-method": "deliver", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "maxLength": 64 }, "shareId": { "type": "string", "maxLength": 64 }, "sourcePaths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "maxItems": 500 }, "destinationPath": { "type": "string", "maxLength": 2048, "default": "" }, "destinationLabel": { "type": "string", "maxLength": 300, "default": "" }, "overwrite": { "type": "boolean", "default": false } }, "required": [ "accountId" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "provider", "label" ] }, "shareId": { "type": [ "string", "null" ] }, "sourcePaths": { "type": "array", "items": { "type": "string" } }, "destinationPath": { "type": "string" }, "destinationLabel": { "type": "string" }, "overwrite": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "filesTotal": { "type": [ "integer", "null" ] }, "bytesTotal": { "type": [ "number", "null" ] }, "filesDone": { "type": "integer" }, "bytesDone": { "type": "number" }, "skipped": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "path": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "path", "reason" ] } }, "error": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string" } }, "required": [ "id", "account", "shareId", "sourcePaths", "destinationPath", "destinationLabel", "overwrite", "status", "filesTotal", "bytesTotal", "filesDone", "bytesDone", "skipped", "error", "startedAt", "finishedAt", "createdAt", "createdBy" ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "cloud.listDeliveries", "summary": "List cloud deliveries", "tags": [ "Cloud" ], "x-boita-group": "cloud", "x-boita-method": "listDeliveries", "x-boita-scopes": [ "files:read" ], "security": [ { "apiKey": [ "files:read" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "shareId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "provider", "label" ] }, "shareId": { "type": [ "string", "null" ] }, "sourcePaths": { "type": "array", "items": { "type": "string" } }, "destinationPath": { "type": "string" }, "destinationLabel": { "type": "string" }, "overwrite": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "filesTotal": { "type": [ "integer", "null" ] }, "bytesTotal": { "type": [ "number", "null" ] }, "filesDone": { "type": "integer" }, "bytesDone": { "type": "number" }, "skipped": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "path": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "path", "reason" ] } }, "error": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string" } }, "required": [ "id", "account", "shareId", "sourcePaths", "destinationPath", "destinationLabel", "overwrite", "status", "filesTotal", "bytesTotal", "filesDone", "bytesDone", "skipped", "error", "startedAt", "finishedAt", "createdAt", "createdBy" ] } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/workspaces/{workspaceId}/cloud/deliveries/{deliveryId}/cancel": { "post": { "operationId": "cloud.cancelDelivery", "summary": "Cancel a cloud delivery", "tags": [ "Cloud" ], "x-boita-group": "cloud", "x-boita-method": "cancelDelivery", "x-boita-scopes": [ "files:write" ], "security": [ { "apiKey": [ "files:write" ] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The workspace id (the key is bound to one workspace)" }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "provider", "label" ] }, "shareId": { "type": [ "string", "null" ] }, "sourcePaths": { "type": "array", "items": { "type": "string" } }, "destinationPath": { "type": "string" }, "destinationLabel": { "type": "string" }, "overwrite": { "type": "boolean" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "filesTotal": { "type": [ "integer", "null" ] }, "bytesTotal": { "type": [ "number", "null" ] }, "filesDone": { "type": "integer" }, "bytesDone": { "type": "number" }, "skipped": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "path": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "path", "reason" ] } }, "error": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string" } }, "required": [ "id", "account", "shareId", "sourcePaths", "destinationPath", "destinationLabel", "overwrite", "status", "filesTotal", "bytesTotal", "filesDone", "bytesDone", "skipped", "error", "startedAt", "finishedAt", "createdAt", "createdBy" ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "boita_sk_…", "description": "Workspace API key. Scopes:\n- `files:read` — List and search files, folders, versions and trash; read transfers and watch folders\n- `files:write` — Create folders, rename, delete and restore; start transfers; manage watch folders\n- `shares:write` — Create, extend and revoke share links and read their details\n- `portals:write` — Create, update and revoke upload portals and review their uploads\n- `receipts:read` — Read delivery receipts, verification reports, comments and share details\n- `webhooks:manage` — Manage webhook endpoints and REST-hook subscriptions (Zapier, Make, n8n), read deliveries, retry and test them; poll the event stream\n- `usage:read` — Read storage, bandwidth, dashboard figures and the audit log" } }, "schemas": { "FileEntry": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "folder", "link" ] }, "size": { "type": [ "integer", "null" ] }, "modifiedAt": { "type": [ "string", "null" ] }, "encrypted": { "type": "boolean" }, "preview": { "type": "boolean" } }, "required": [ "name", "path", "type", "size", "modifiedAt", "encrypted" ], "additionalProperties": true }, "FileListing": { "type": "object", "properties": { "path": { "type": "string" }, "access": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FileEntry" } }, "total": { "type": "integer" } }, "required": [ "path", "access", "items", "total" ], "additionalProperties": true }, "SearchResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FileEntry" } } }, "required": [ "items" ], "additionalProperties": true }, "TrashItem": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "name": { "type": "string" }, "sizeBytes": { "type": [ "number", "null" ] }, "deletedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "purgeAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "path", "name", "sizeBytes", "deletedAt", "purgeAt" ], "additionalProperties": true }, "FileVersion": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "sizeBytes": { "type": [ "number", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "path", "sizeBytes", "createdAt" ], "additionalProperties": true }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": true }, "Transfer": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "send", "receive" ] }, "client": { "type": "string" }, "engine": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "completed", "failed", "cancelled" ] }, "streams": { "type": "integer" }, "priority": { "type": "string" }, "usageId": { "type": "string" }, "filesTotal": { "type": [ "integer", "null" ] }, "filesDone": { "type": "integer" }, "bytesTotal": { "type": [ "number", "null" ] }, "bytesDone": { "type": "number" }, "avgRateKbps": { "type": [ "number", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "direction", "client", "engine", "status", "streams", "priority", "usageId", "filesTotal", "filesDone", "bytesTotal", "bytesDone", "avgRateKbps", "startedAt", "finishedAt", "errorCode", "errorMessage", "createdAt" ], "additionalProperties": true }, "TransferCreated": { "type": "object", "properties": { "transferId": { "type": "string" }, "transferSpec": { "type": "object", "additionalProperties": {}, "description": "Hand this to the transfer engine unchanged; it is valid for a short window." }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "transferId", "transferSpec", "expiresAt" ], "additionalProperties": true }, "ShareItem": { "type": "object", "properties": { "path": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "folder" ] }, "sizeBytes": { "type": [ "number", "null" ] } }, "required": [ "path", "name", "type", "sizeBytes" ] }, "ShareRecipient": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "url": { "type": "string" }, "firstViewedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "downloadedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "email", "phone", "label", "url", "firstViewedAt", "downloadedAt", "verifiedAt" ], "additionalProperties": true }, "Share": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "description": "Relative on the app host, absolute on a custom domain" }, "mode": { "type": "string", "enum": [ "drive", "send" ] }, "title": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "hasPassword": { "type": "boolean" }, "status": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "maxDownloads": { "type": [ "integer", "null" ] }, "downloadCount": { "type": "integer" }, "viewCount": { "type": "integer" }, "requireEmail": { "type": "boolean" }, "allowComments": { "type": "boolean" }, "viewOnly": { "type": "boolean" }, "watermark": { "type": "boolean" }, "availableFrom": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ShareItem" } }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/ShareRecipient" } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "slug", "url", "mode", "title", "message", "hasPassword", "status", "expiresAt", "maxDownloads", "downloadCount", "viewCount", "requireEmail", "allowComments", "viewOnly", "watermark", "availableFrom", "items", "recipients", "createdAt" ], "additionalProperties": true }, "ShareDetail": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "description": "Relative on the app host, absolute on a custom domain" }, "mode": { "type": "string", "enum": [ "drive", "send" ] }, "title": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "hasPassword": { "type": "boolean" }, "status": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "maxDownloads": { "type": [ "integer", "null" ] }, "downloadCount": { "type": "integer" }, "viewCount": { "type": "integer" }, "requireEmail": { "type": "boolean" }, "allowComments": { "type": "boolean" }, "viewOnly": { "type": "boolean" }, "watermark": { "type": "boolean" }, "availableFrom": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ShareItem" } }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/ShareRecipient" } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "ip": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] }, "recipient": { "type": [ "string", "null" ] } }, "required": [ "type", "at", "ip", "userAgent", "recipient" ], "additionalProperties": true } } }, "required": [ "id", "slug", "url", "mode", "title", "message", "hasPassword", "status", "expiresAt", "maxDownloads", "downloadCount", "viewCount", "requireEmail", "allowComments", "viewOnly", "watermark", "availableFrom", "items", "recipients", "createdAt", "events" ], "additionalProperties": true }, "BulkResult": { "type": "object", "properties": { "done": { "type": "integer" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "error" ] } } }, "required": [ "done" ], "additionalProperties": true }, "Comment": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author": { "type": [ "string", "null" ] }, "itemPath": { "type": [ "string", "null" ] }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "body", "author", "itemPath", "resolvedAt", "createdAt" ], "additionalProperties": true }, "Receipt": { "type": "object", "properties": { "receiptId": { "type": "string" }, "share": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "hasPassword": { "type": "boolean" }, "maxDownloads": { "type": [ "integer", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "viewCount": { "type": "integer" }, "downloadCount": { "type": "integer" } }, "required": [ "url", "title", "status", "hasPassword", "maxDownloads", "createdAt", "expiresAt", "viewCount", "downloadCount" ], "additionalProperties": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ShareItem" } }, "totalBytes": { "type": [ "number", "null" ] }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "firstViewedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "downloadedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "downloads": { "type": "integer" }, "status": { "type": "string", "enum": [ "sent", "viewed", "downloaded" ] } }, "required": [ "email", "phone", "label", "firstViewedAt", "downloadedAt", "verifiedAt", "downloads", "status" ], "additionalProperties": true } }, "anonymous": { "type": "object", "properties": { "views": { "type": "integer" }, "downloads": { "type": "integer" } }, "required": [ "views", "downloads" ] }, "downloads": { "type": "array", "items": { "type": "object", "properties": { "transferId": { "type": "string" }, "recipient": { "type": [ "string", "null" ] }, "client": { "type": "string" }, "files": { "type": "integer" }, "bytes": { "type": "number" }, "rateMbps": { "type": [ "number", "null" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "seconds": { "type": [ "number", "null" ] } }, "required": [ "transferId", "recipient", "client", "files", "bytes", "rateMbps", "completedAt", "seconds" ], "additionalProperties": true } }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "recipient": { "type": [ "string", "null" ] }, "client": { "type": [ "string", "null" ] } }, "required": [ "type", "at", "recipient", "client" ], "additionalProperties": true } }, "integrity": { "type": "string", "enum": [ "verified", "none" ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sizeBytes": { "type": [ "number", "null" ] }, "checksumType": { "type": [ "string", "null" ] }, "checksum": { "type": [ "string", "null" ] }, "downloads": { "type": "integer" }, "verifiedDownloads": { "type": "integer" }, "verified": { "type": "boolean" } }, "required": [ "path", "sizeBytes", "checksumType", "checksum", "downloads", "verifiedDownloads", "verified" ] } }, "checksumType": { "type": "string" } }, "required": [ "receiptId", "share", "items", "totalBytes", "recipients", "anonymous", "downloads", "timeline", "integrity", "files", "checksumType" ], "additionalProperties": true }, "Portal": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "targetPath": { "type": "string" }, "requireEmail": { "type": "boolean" }, "hasPassword": { "type": "boolean" }, "maxBytesPerUpload": { "type": [ "number", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "notifyOnUpload": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "uploadCount": { "type": "integer" }, "bytesReceived": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "slug", "url", "title", "message", "targetPath", "requireEmail", "hasPassword", "maxBytesPerUpload", "expiresAt", "notifyOnUpload", "status", "uploadCount", "bytesReceived", "createdAt" ], "additionalProperties": true }, "PortalUpload": { "type": "object", "properties": { "id": { "type": "string" }, "senderEmail": { "type": [ "string", "null" ] }, "senderName": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "folderPath": { "type": "string" }, "fileCount": { "type": [ "integer", "null" ] }, "bytesTotal": { "type": [ "number", "null" ] }, "bytesDone": { "type": "number" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "senderEmail", "senderName", "message", "folderPath", "fileCount", "bytesTotal", "bytesDone", "status", "createdAt", "completedAt" ], "additionalProperties": true }, "PortalDetail": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "targetPath": { "type": "string" }, "requireEmail": { "type": "boolean" }, "hasPassword": { "type": "boolean" }, "maxBytesPerUpload": { "type": [ "number", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "notifyOnUpload": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused", "revoked" ] }, "uploadCount": { "type": "integer" }, "bytesReceived": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/PortalUpload" } } }, "required": [ "id", "slug", "url", "title", "message", "targetPath", "requireEmail", "hasPassword", "maxBytesPerUpload", "expiresAt", "notifyOnUpload", "status", "uploadCount", "bytesReceived", "createdAt", "uploads" ], "additionalProperties": true }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "failureCount": { "type": "integer" }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "url", "description", "events", "status", "failureCount", "lastDeliveryAt", "createdAt" ], "additionalProperties": true }, "WebhookCreated": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "failureCount": { "type": "integer" }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "secret": { "type": "string", "description": "Signing secret, shown once" } }, "required": [ "id", "url", "description", "events", "status", "failureCount", "lastDeliveryAt", "createdAt", "secret" ], "additionalProperties": true }, "WebhookSecret": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "secret" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "nextAttemptAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "lastStatusCode": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "eventId", "type", "status", "attempts", "nextAttemptAt", "lastStatusCode", "lastError", "deliveredAt", "createdAt" ], "additionalProperties": true }, "DeliveryQueued": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "const": "pending", "type": "string" } }, "required": [ "id", "status" ] }, "TestQueued": { "type": "object", "properties": { "eventId": { "type": "string" }, "deliveryId": { "type": "string" } }, "required": [ "eventId" ] }, "EventCatalogue": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "events" ] }, "WorkspaceEvent": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "type", "data", "createdAt" ] }, "UsageSnapshot": { "type": "object", "properties": { "takenAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "bytesStored": { "type": "number" }, "fileCount": { "type": "integer" }, "bytesIn30d": { "type": "number" }, "bytesOut30d": { "type": "number" } }, "required": [ "takenAt", "bytesStored", "fileCount", "bytesIn30d", "bytesOut30d" ], "additionalProperties": true }, "UsageSummary": { "type": "object", "properties": { "quotaBytes": { "type": "number" }, "planCode": { "type": "string" }, "percent": { "type": [ "number", "null" ] }, "level": { "type": "integer" }, "uploadsBlocked": { "type": "boolean" }, "latest": { "anyOf": [ { "$ref": "#/components/schemas/UsageSnapshot" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/UsageSnapshot" } } }, "required": [ "quotaBytes", "planCode", "percent", "level", "uploadsBlocked", "latest", "history" ], "additionalProperties": true }, "Bandwidth": { "type": "object", "properties": { "days": { "type": "integer" } }, "required": [ "days" ], "additionalProperties": true }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "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": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ], "description": "Every error response" } }, "responses": { "400": { "description": "validation_failed | path_rejected | authorization_pending | slow_down | access_denied | expired_token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "email_unverified | mfa_required | forbidden | plan_limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited | node_busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "x-boita-scopes": { "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" } }