{ "openapi": "3.1.0", "info": { "title": "SendFlo API", "version": "2026-08-07", "description": "The SendFlo API moves files between people, teams and AI agents. This reference covers every operation an API key can call; it is built from the API's own routes, and a test fails when the two disagree.\n\n- **Authentication:** `Authorization: Bearer sk_live_…` with an API key from Settings → Developer. Each operation names the scope its key needs.\n- **Versioning:** by date. Every response carries `sendflo-version`; additive changes keep the date, breaking changes get a new one.\n- **Errors:** RFC 9457 problem documents (`application/problem+json`) with a machine `code`.\n- **Rate limits:** per key (set when you create it); over the limit you get 429 `rate_limited`.\n- **Files:** bytes never pass through this API. Uploads and downloads use presigned storage URLs that the API hands out.\n- **Webhooks:** signed the [Standard Webhooks](https://www.standardwebhooks.com) way, so any Standard Webhooks library verifies them: `webhook-id` (the event's id, the same on every retry — deduplicate on it), `webhook-timestamp` (unix seconds) and `webhook-signature: v1,..\">`, keyed with the secret after `whsec_`, base64-decoded. Reject a timestamp more than 5 minutes off. Until 28 April 2027 the old `sendflo-signature: t=,v1=.\">` (keyed with the whole secret string) is sent too. Each event is tried 6 times with growing waits; every attempt is in the endpoint's delivery log for 30 days, where you can Resend it.", "contact": { "name": "SendFlo developers", "email": "dev@sendflo.app", "url": "https://sendflo.app/docs" }, "termsOfService": "https://sendflo.app/terms" }, "servers": [ { "url": "https://api.sendflo.app/v1", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "transfers", "description": "Upload a file: create a transfer, PUT the parts to storage, complete it." }, { "name": "links", "description": "Share links for stored files: create, list, change, revoke." }, { "name": "activity", "description": "What happened to a send: who opened and downloaded what, the audit report, per-person access." }, { "name": "files", "description": "Your stored files, and sending a stored file again." }, { "name": "received", "description": "Files people uploaded to you through upload pages and requests." }, { "name": "file-requests", "description": "Ask a person for files: a request link with its own rules." }, { "name": "inboxes", "description": "Addressable inboxes that receive files for an agent." }, { "name": "webhooks", "description": "Signed HTTPS callbacks for events in your workspace." }, { "name": "notifications", "description": "Where SendFlo notifies you: Slack, Discord, Teams, webhooks, email." }, { "name": "feedback", "description": "Recipients' comments, ratings and approvals on a send." }, { "name": "branding", "description": "Logos, colours and brand kits shown on your pages and emails." }, { "name": "agent-tasks", "description": "Hand work to AI agents and follow it to the result." }, { "name": "cloud-agents", "description": "The cloud agents (webhook, A2A, routine) your tasks can go to." }, { "name": "destinations", "description": "Deliver files to a team's shared destination." }, { "name": "account", "description": "Usage, credits and the requests made with your keys." }, { "name": "audit", "description": "The audit log: who did what across your workspace or team, with filters and exports." }, { "name": "team-inboxes", "description": "Who uses a team's inboxes: keep access in sync from an HR or identity system." }, { "name": "intakes", "description": "Secure intakes: a bot collects files it can't open, and hands them to people." }, { "name": "drive", "description": "Drive — My files: folders, uploads, versions, the trash, and the change feed a sync client reads." }, { "name": "backup", "description": "Backup — your devices' backup sets: devices, the chunk index, pack uploads, snapshots, and where blobs are for a restore." }, { "name": "encryption", "description": "Make the SDK or the CLI one of your encryption devices, to open end-to-end files you received." } ], "paths": { "/agent-rosters": { "get": { "operationId": "getAgentRosters", "tags": [ "agent-tasks" ], "summary": "List the agents on your computers", "description": "What the SendFlo connector on each of the key creator's computers offers: its agents, presets, sessions and public key, and whether the computer is online.", "security": [ { "apiKey": [ "agent_tasks.read" ] } ], "x-scope": "agent_tasks.read", "responses": { "200": { "description": "List the agents on your computers", "content": { "application/json": { "schema": { "type": "object", "required": [ "rosters" ], "properties": { "rosters": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRoster" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agent-targets": { "get": { "operationId": "getAgentTargets", "tags": [ "agent-tasks" ], "summary": "List where tasks can be sent", "description": "Everything this workspace can hand a task to: project folders bound to an agent on a computer (100 at most) and its cloud agents. `available: false` with `unavailable` says why one can't take a task now.", "security": [ { "apiKey": [ "agent_tasks.read" ] } ], "x-scope": "agent_tasks.read", "responses": { "200": { "description": "List where tasks can be sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "targets" ], "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTarget" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agent-tasks": { "get": { "operationId": "getAgentTasks", "tags": [ "agent-tasks" ], "summary": "List agent tasks", "description": "`box=out` (the default): tasks the key's creator sent from this workspace, newest first; page with `before` (the last id you got). `box=in`: tasks for the creator's own computers in this workspace. `box=pull`: queued tasks for this workspace's pull agents, oldest first, plus the ones this key claimed and hasn't finished. `limit` 1–100 (50 by default). With `q` (`box=out` or `in`): the tasks whose agent, instruction, files or sender match, best first, 25 a page (`page` 1–8; see `search`). A sealed instruction is never searched.", "security": [ { "apiKey": [ "agent_tasks.read" ] } ], "x-scope": "agent_tasks.read", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search words (`box=out` or `in`).", "schema": { "maxLength": 400, "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "With `q`: the page of results, 1–8.", "schema": { "pattern": "^\\d{1,2}$", "type": "string" } }, { "name": "box", "in": "query", "required": false, "description": "`out`, `in` or `pull` (`device` is for the SendFlo connector).", "schema": { "anyOf": [ { "const": "out", "type": "string" }, { "const": "in", "type": "string" }, { "const": "device", "type": "string" }, { "const": "pull", "type": "string" } ] } }, { "name": "agent", "in": "query", "required": false, "description": "For `box=pull`: only this cloud agent's tasks.", "schema": { "pattern": "^\\d{1,20}$", "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "For `box=out`: only tasks in this stored state.", "schema": { "maxLength": 20, "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "For `box=out`: tasks older than this id.", "schema": { "pattern": "^\\d{1,20}$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Tasks per page, 1–100 (50 by default).", "schema": { "pattern": "^\\d{1,3}$", "type": "string" } }, { "name": "active", "in": "query", "required": false, "description": "For the SendFlo connector.", "schema": { "maxLength": 1, "type": "string" } } ], "responses": { "200": { "description": "List agent tasks", "content": { "application/json": { "schema": { "type": "object", "required": [ "tasks" ], "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTask" } }, "search": { "$ref": "#/components/schemas/SearchMeta" } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postAgentTasks", "tags": [ "agent-tasks" ], "summary": "Send a task to a cloud agent", "description": "Hands 1–50 of this workspace's stored files to one of its cloud agents with an instruction, a preset or a voice note (at least one). Webhook, A2A and routine agents get it in the background; a pull agent's task waits (`queued`) until claimed. Refused for flagged or expired files, files over the agent's size limit, a paused agent, or an agent with 50 unfinished tasks. Sends the `agent_task.created` webhook.", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cloud_agent_id", "file_ids" ], "properties": { "cloud_agent_id": { "pattern": "^\\d{1,20}$", "type": "string", "description": "One of this workspace's cloud agents." }, "file_ids": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "pattern": "^\\d{1,20}$", "type": "string" }, "description": "1–50 stored file ids." }, "instruction": { "maxLength": 8000, "type": "string", "description": "What the agent should do (8000 characters at most)." }, "preset": { "maxLength": 64, "type": "string", "description": "A preset id of the agent." }, "voice_file": { "maxLength": 255, "type": "string", "description": "The name of one of the files that holds a spoken instruction." }, "instruction_enc": { "description": "Not for cloud agents (422 `e2e_not_for_cloud`)." }, "from_name": { "maxLength": 120, "type": "string", "description": "The sender name the agent sees (the key creator's name by default)." } } } } } }, "responses": { "200": { "description": "Send a task to a cloud agent", "content": { "application/json": { "schema": { "type": "object", "required": [ "task" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" } } } } } }, "default": { "description": "An error: `no_user`, `agent_not_found`, `agent_paused`, `file_not_found`, `file_expired`, `file_flagged`, `invalid_task`, `instruction_required`, `e2e_not_for_cloud`, `agent_file_too_large`, `rate_limited`, `agent_queue_full`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agent-tasks/{id}": { "get": { "operationId": "getAgentTasksById", "tags": [ "agent-tasks" ], "summary": "Get a task with its events", "description": "The task (with 1-hour download URLs for its results), its events (oldest first, 500 at most) and the tasks that re-ran it. Visible to its sender and to the owner of the computer it went to.", "security": [ { "apiKey": [ "agent_tasks.read" ] } ], "x-scope": "agent_tasks.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a task with its events", "content": { "application/json": { "schema": { "type": "object", "required": [ "task", "events" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskEvent" } }, "retries": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTaskRetryRef" } } } } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agent-tasks/{id}/answer": { "post": { "operationId": "postAgentTasksByIdAnswer", "tags": [ "agent-tasks" ], "summary": "Answer a task's question", "description": "Answers the agent's open question, as the task's sender or the computer's owner: one of its `option_id`s, or free `text` when it allows it (stored up to 4000 characters). The answer is passed to the computer or cloud agent; `reached` says whether it got it now. For a task waiting for approval, `approve` or `reject` decides it (the computer's owner only).", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question_id" ], "properties": { "question_id": { "minLength": 1, "maxLength": 64, "type": "string", "description": "The open question's id." }, "option_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "One of the question's options." }, "text": { "anyOf": [ { "maxLength": 8000, "type": "string" }, { "type": "null" } ], "description": "A free-text answer." } } } } } }, "responses": { "200": { "description": "Answer a task's question", "content": { "application/json": { "schema": { "type": "object", "required": [ "task" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "reached": { "description": "Whether the agent or computer got it now (otherwise it picks it up on its next check).", "type": "boolean" } } } } } }, "default": { "description": "An error: `not_found`, `owner_decides`, `unknown_option`, `no_question`, `question_changed`, `already_answered`, `invalid_answer`, `option_required`, `text_required`, `terminal`, `not_awaiting_approval`, `illegal_transition`, `contended`, `rate_limited`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agent-tasks/{id}/cancel": { "post": { "operationId": "postAgentTasksByIdCancel", "tags": [ "agent-tasks" ], "summary": "Cancel a task", "description": "As the sender or the computer's owner. A cloud task, or one not yet handed to the agent, is canceled at once. A running task on a computer gets a stop request (`cancel_requested`) and reports `canceled` when it stops. A finished task comes back unchanged.", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel a task", "content": { "application/json": { "schema": { "type": "object", "required": [ "task" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "reached": { "description": "Whether the agent or computer got it now (otherwise it picks it up on its next check).", "type": "boolean" } } } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agent-tasks/{id}/claim": { "post": { "operationId": "postAgentTasksByIdClaim", "tags": [ "agent-tasks" ], "summary": "Claim a pull agent's task", "description": "For a pull agent, with an API key: takes a `queued` task of this workspace (one claimer wins) and returns what a webhook agent would receive, with a per-task callback token (`sfcb_…`, shown once). Report progress with `Authorization: Bearer ` to the `callback` URLs. File URLs last 7 days; blocked files are left out.", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id (from GET /v1/agent-tasks?box=pull).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claim a pull agent's task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudTaskClaim" } } } }, "default": { "description": "An error: `not_found`, `already_claimed`, `not_claimable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/agent-tasks/{id}/retry": { "post": { "operationId": "postAgentTasksByIdRetry", "tags": [ "agent-tasks" ], "summary": "Run a task again", "description": "As its sender: a new task (`retry_of` = this one) from a finished task whose files were delivered. Cloud tasks reuse the same uploads; a computer's task re-checks the computer and its agent first.", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run a task again", "content": { "application/json": { "schema": { "type": "object", "required": [ "task" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" } } } } } }, "default": { "description": "An error: `not_found`, `not_retryable`, `files_not_on_device`, `rate_limited`, `agent_unavailable`, `agent_paused`, `device_gone`, `agent_owner_only`, `agent_queue_full`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/audit": { "get": { "operationId": "getAudit", "tags": [ "audit" ], "summary": "Read the audit log", "description": "Who did what, newest first: sign-ins, links, every open, view and download, requests, collections, team changes, billing, the API, and SendFlo staff (shown as \"SendFlo staff\"). 50 events per page (up to 200 with `limit`); pass `next_cursor` back as `cursor`. Team Pro and Team Enterprise: a key reads its own workspace's log, or the whole team's with `plan_id` when the key's maker is the team's owner or an admin. Events are kept 365 days on Team Pro and 730 on Team Enterprise.", "security": [ { "apiKey": [ "audit.read" ] } ], "x-scope": "audit.read", "parameters": [ { "name": "plan_id", "in": "query", "required": false, "description": "A team's id: read the whole team's log (owners and admins). Without it: the key's own workspace.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only events at or after this time (ISO 8601).", "schema": { "format": "date-time", "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only events before this time.", "schema": { "format": "date-time", "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "One or more actions, comma-separated (`FILE_DOWNLOAD,FILE_PREVIEWED`) — the list is the catalogue in the docs.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "One or more of ACCOUNT, SECURITY, LINK, ACCESS, REQUEST, COLLECTION, TEAM, DEVICE, BILLING, API, STAFF.", "schema": { "type": "string" } }, { "name": "actor", "in": "query", "required": false, "description": "Who did it: an email address or a user id.", "schema": { "type": "string" } }, { "name": "ip", "in": "query", "required": false, "description": "One IPv4 / IPv6 address, or a CIDR block (`203.0.113.0/24`).", "schema": { "type": "string" } }, { "name": "link_id", "in": "query", "required": false, "description": "Only events on this link.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "outcome", "in": "query", "required": false, "description": "`success`, `failure` or `denied`.", "schema": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "denied", "type": "string" } ] } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Events per page, 1–200 (50 by default).", "schema": { "minimum": 1, "maximum": 200, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "type": "integer" } ] } } ], "responses": { "200": { "description": "Read the audit log", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPage" } } } }, "default": { "description": "An error: `invalid_query`, `plan_required`, `forbidden`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/audit/export": { "get": { "operationId": "getAuditExport", "tags": [ "audit" ], "summary": "Download the audit log", "description": "The same events and filters as a file (`sendflo-audit--.csv` or `.json`), newest first, 100,000 at most. CSV by default (UTF-8 with a byte-order mark, formula-safe cells, `details` as JSON in its column); a JSON array of events with `format=json`. The export is itself recorded (`AUDIT_EXPORTED`).", "security": [ { "apiKey": [ "audit.read" ] } ], "x-scope": "audit.read", "parameters": [ { "name": "plan_id", "in": "query", "required": false, "description": "A team's id: read the whole team's log (owners and admins). Without it: the key's own workspace.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only events at or after this time (ISO 8601).", "schema": { "format": "date-time", "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only events before this time.", "schema": { "format": "date-time", "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "One or more actions, comma-separated (`FILE_DOWNLOAD,FILE_PREVIEWED`) — the list is the catalogue in the docs.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "One or more of ACCOUNT, SECURITY, LINK, ACCESS, REQUEST, COLLECTION, TEAM, DEVICE, BILLING, API, STAFF.", "schema": { "type": "string" } }, { "name": "actor", "in": "query", "required": false, "description": "Who did it: an email address or a user id.", "schema": { "type": "string" } }, { "name": "ip", "in": "query", "required": false, "description": "One IPv4 / IPv6 address, or a CIDR block (`203.0.113.0/24`).", "schema": { "type": "string" } }, { "name": "link_id", "in": "query", "required": false, "description": "Only events on this link.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "outcome", "in": "query", "required": false, "description": "`success`, `failure` or `denied`.", "schema": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "denied", "type": "string" } ] } }, { "name": "format", "in": "query", "required": false, "description": "`csv` (the default) or `json`.", "schema": { "anyOf": [ { "const": "csv", "type": "string" }, { "const": "json", "type": "string" } ] } } ], "responses": { "200": { "description": "Download the audit log", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } } }, "default": { "description": "An error: `invalid_query`, `plan_required`, `forbidden`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup": { "get": { "operationId": "getBackup", "tags": [ "backup" ], "summary": "Your Backup plans and devices", "description": "The plans you back up to (your own, and each team's you're on) with what they store and how many devices they cover, and every device you can see — a team's owner and admins see every member's.", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "responses": { "200": { "description": "Your Backup plans and devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupOverview" } } } }, "default": { "description": "An error: `no_backup`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices": { "post": { "operationId": "postBackupDevices", "tags": [ "backup" ], "summary": "Add a device", "description": "Register this computer, server, phone or external drive as a device with its own backup set. It goes on your own plan, or `team_id`'s (`choose_team` when you could back up to more than one). Computers, servers and phones count against the plan's devices (`device_limit`); an external drive (`kind: volume`, with its `volume_serial`) doesn't, and registering it again reattaches its set (200, `reattached: true`).", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "maxLength": 120, "type": "string", "description": "What to call it (\"Dana's laptop\")." }, "kind": { "type": "string", "description": "`computer` (the default), `server`, `phone` or `volume`." }, "os": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "description": "Its operating system and version." }, "client": { "type": "string", "description": "`cli` (the default), `desktop` or `phone`." }, "client_version": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "description": "The backup client's version." }, "volume_serial": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "description": "An external drive's volume serial." }, "policy": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ], "description": "What the client backs up: paths, exclude, schedule_hours, max_file_bytes." }, "key_mode": { "type": "string", "description": "`sendflo` (the default: previews and restore from the web work) or `private` (only your key opens it)." }, "team_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The team plan to back up to." } } } } } }, "responses": { "200": { "description": "an external drive already known by its serial", "content": { "application/json": { "schema": { "type": "object", "required": [ "device", "reattached", "plan" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDevice" }, "reattached": { "const": true, "type": "boolean" }, "plan": { "$ref": "#/components/schemas/BackupPlan" } } } } } }, "201": { "description": "Add a device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupDeviceRegistered" } } } }, "default": { "description": "An error: `no_backup`, `read_only`, `choose_team`, `not_on_team`, `device_limit`, `bad_name`, `bad_kind`, `bad_client`, `bad_key_mode`, `no_private_key`, `volume_serial`, `bad_team`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}": { "get": { "operationId": "getBackupDevicesById", "tags": [ "backup" ], "summary": "Get a device", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupDeviceWithPlan" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "patchBackupDevicesById", "tags": [ "backup" ], "summary": "Rename, pause or set a device's policy", "description": "A paused device's client stops at its next heartbeat; its packs and snapshots are refused (`paused`) until it's resumed.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "maxLength": 120, "type": "string", "description": "A new name." }, "paused": { "type": "boolean", "description": "Pause or resume its backup." }, "policy": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ], "description": "What the client backs up." } } } } } }, "responses": { "200": { "description": "Rename, pause or set a device's policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupDeviceResult" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `bad_name`, `backup_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteBackupDevicesById", "tags": [ "backup" ], "summary": "Remove a device", "description": "It stops counting against the plan and can't back up any more. Its backups stay until the plan's retention ends.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Remove a device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupDeviceRemoved" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `backup_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/blobs/have": { "post": { "operationId": "postBackupDevicesByIdBlobsHave", "tags": [ "backup" ], "summary": "Which chunks the plan already stores", "description": "Ask before packing: the blobs (BLAKE3 ids of chunks and folder trees) the plan holds already — from any of its devices — need no upload. Up to 5,000 ids a call.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "maxItems": 5000, "type": "array", "items": { "type": "string" }, "description": "Blob ids (64 hex characters)." } } } } } }, "responses": { "200": { "description": "Which chunks the plan already stores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupHave" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `bad_ids`, `bad_blob_id`, `too_many`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/blobs/locate": { "post": { "operationId": "postBackupDevicesByIdBlobsLocate", "tags": [ "backup" ], "summary": "Where blobs are stored (restore)", "description": "For each blob: a short-lived URL of the pack that holds it, and its byte range (`offset`, `length`); `compression: df` means the bytes are raw-deflate compressed (RFC 1951; a browser inflates them with `DecompressionStream(\"deflate-raw\")`). Up to 5,000 ids a call; ids the plan doesn't hold are left out.", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "maxItems": 5000, "type": "array", "items": { "type": "string" }, "description": "Blob ids." } } } } } }, "responses": { "200": { "description": "Where blobs are stored (restore)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupLocate" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `bad_ids`, `too_many`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/heartbeat": { "post": { "operationId": "postBackupDevicesByIdHeartbeat", "tags": [ "backup" ], "summary": "Report a device's backup state", "description": "The client reports every ~15 seconds while it runs (`running` with its progress), when it finishes (`idle`) and when it fails (`error` with what happened). The answer says whether the device is paused and its policy.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "description": "`running`, `idle` or `error`." }, "progress": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ], "description": "phase, files_done, files_total, bytes_done, bytes_total." }, "error": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "What went wrong." }, "client_version": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "description": "The client's version." }, "run_start": { "type": "boolean", "description": "`true` on a run's first heartbeat, before it asks which blobs are stored: a snapshot from a run that a cleanup overtook is refused (`pruned_during_run`)." } } } } } }, "responses": { "200": { "description": "Report a device's backup state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupHeartbeat" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `backup_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/live-reports": { "post": { "operationId": "postBackupDevicesByIdLiveReports", "tags": [ "backup" ], "summary": "Start a live report (private-key device)", "description": "The server can't read a private-key device's folder lists, so its computer reports which blobs its owner's live snapshots use; the prune then frees that person's unused private packs. The answer names every snapshot to walk (all of the owner's private devices in this plan — they share a key). `live_report_due` on the device says when one is worth making.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id (a private-key device, its own computer).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Start a live report (private-key device)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupLiveReportStart" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `read_only`, `paused`, `backup_role`, `not_private`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/live-reports/{rid}/blobs": { "post": { "operationId": "postBackupDevicesByIdLiveReportsByRidBlobs", "tags": [ "backup" ], "summary": "Add blobs to a live report", "description": "Blob ids (trees and chunks) the walked snapshots use, up to 20,000 a call.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } }, { "name": "rid", "in": "path", "required": true, "description": "The report's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "maxItems": 20000, "type": "array", "items": { "maxLength": 64, "type": "string" }, "description": "Blob ids (64 hex characters)." } } } } } }, "responses": { "200": { "description": "Add blobs to a live report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupLiveReportBlobs" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `read_only`, `paused`, `no_report`, `report_closed`, `too_many`, `bad_blob_id`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/live-reports/{rid}/complete": { "post": { "operationId": "postBackupDevicesByIdLiveReportsByRidComplete", "tags": [ "backup" ], "summary": "Finish a live report", "description": "The snapshots walked — exactly those the report named; every one's root folder list must be among the blobs. A cleanup is then queued. A report counts for a day, and only while no private snapshot of its owner was made after it began.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } }, { "name": "rid", "in": "path", "required": true, "description": "The report's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "snapshots" ], "properties": { "snapshots": { "maxItems": 100000, "type": "array", "items": { "maxLength": 20, "type": "string" }, "description": "The ids of the snapshots walked." } } } } } }, "responses": { "200": { "description": "Finish a live report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupLiveReportDone" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `read_only`, `paused`, `no_report`, `report_closed`, `snapshots_differ`, `root_missing`, `no_chunks`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/location": { "get": { "operationId": "getBackupDevicesByIdLocation", "tags": [ "backup" ], "summary": "Where a computer is", "description": "Find a lost or stolen computer. Off unless the computer's person turns it on (in the app); then each heartbeat's approximate place is kept: the city of the address it comes from (about 25 km), else that address's country. A new place when it moved more than 5 km or six hours passed; the newest 50. The person sees it always; a team's owner and admins only when the team shows its members' locations and the person shared this computer with the team (`location_private` otherwise; each look is in the audit log).", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Where a computer is", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLocation" } } } }, "default": { "description": "An error: `no_device`, `location_private`, `no_backup`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "putBackupDevicesByIdLocation", "tags": [ "backup" ], "summary": "Turn a computer's location on or off", "description": "The computer's own person only. `on: true` (optionally `share_team: true` on a team's plan) works only in the app's signed-in session — a key gets `session_only`; a key may turn it off. Off deletes every place kept.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "on" ], "properties": { "on": { "type": "boolean", "description": "true to keep where it is, false to stop and delete the history." }, "share_team": { "type": "boolean", "description": "Also let the team's owner and admins see it (only while the team shows locations)." } } } } } }, "responses": { "200": { "description": "Turn a computer's location on or off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLocationSet" } } } }, "default": { "description": "An error: `no_device`, `backup_role`, `session_only`, `no_backup`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/packs": { "post": { "operationId": "postBackupDevicesByIdPacks", "tags": [ "backup" ], "summary": "Start a pack's upload", "description": "A pack is blobs back to back, then a JSON header (`{v: 1, blobs: [{id, kind, offset, length, z?}]}`), its length as a 32-bit little-endian integer, and the magic `SFPK1`. Declare the blobs here exactly as the header lists them; PUT each part to its URL (`part_size` each, the last one the rest), then POST …/complete. A pack the plan already holds (the same BLAKE3) answers `state: done`. SendFlo reads each new pack once to check it; one that disagrees is dropped and its chunks are uploaded again on the next run. `backup_full` past the plan's room.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hash", "size", "blobs" ], "properties": { "hash": { "type": "string", "description": "BLAKE3 of the whole pack (64 hex characters)." }, "size": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ], "description": "The pack's bytes (up to 1 GiB)." }, "blobs": { "maxItems": 200000, "type": "array", "items": { "type": "object", "required": [ "id", "kind", "offset", "length" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "offset": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ] }, "length": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, "z": { "type": "string" } } }, "description": "Each blob's id, kind (`data` or `tree`), offset, length and `z: df` when raw-deflate compressed." } } } } } }, "responses": { "200": { "description": "Start a pack's upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupPackStart" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `read_only`, `paused`, `backup_role`, `bad_hash`, `bad_size`, `bad_blobs`, `pack_too_large`, `backup_full`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/restores": { "post": { "operationId": "postBackupDevicesByIdRestores", "tags": [ "backup" ], "summary": "Restore files as a ZIP", "description": "Choose files and folders from a backup: SendFlo puts them together into one ZIP (stored entries, ZIP64 when needed) and tells you when it's ready — download it within 7 days. Up to 100,000 files and 2 TB; bigger restores: the desktop app or the CLI. A path is a JSON list of names from the snapshot's root — the backed-up path, then folders (`[\"C:/Users/dana\",\"Documents\"]`); `[]` is the root.", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "snapshot_id", "paths" ], "properties": { "snapshot_id": { "type": "string", "description": "The backup to restore from." }, "paths": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "maxItems": 200, "type": "array", "items": { "maxLength": 1024, "type": "string" } }, "description": "The files and folders, each a JSON list of names." } } } } } }, "responses": { "201": { "description": "Restore files as a ZIP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupRestoreResult" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `no_snapshot`, `no_path`, `bad_path`, `bad_paths`, `bad_snapshot`, `nothing_to_restore`, `zip_too_large`, `sealed`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/snapshots": { "post": { "operationId": "postBackupDevicesByIdSnapshots", "tags": [ "backup" ], "summary": "Make a snapshot", "description": "After a run's packs are complete: the snapshot is the device as it was, from its root tree (`tree_missing` until the tree's pack has arrived). `skipped` lists files the client couldn't read (the snapshot is `partial`). `pruned_during_run`: old backups were cleaned up after the run began (its `run_start` heartbeat), so a blob it was told is stored may be gone — run again; nothing already sent is sent twice.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "root_tree" ], "properties": { "root_tree": { "type": "string", "description": "The root tree blob's id." }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the run began." }, "files": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "Files it covers." }, "dirs": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "Folders." }, "bytes": { "anyOf": [ { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ] }, { "type": "string" } ], "description": "Bytes it covers." }, "new_bytes": { "anyOf": [ { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ] }, { "type": "string" } ], "description": "Bytes this run stored." }, "new_blobs": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "Blobs this run stored." }, "paths": { "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "The backed-up paths." }, "skipped": { "maxItems": 1000, "type": "array", "items": {}, "description": "Files not read, each {path, reason}." }, "trigger": { "type": "string", "description": "`first`, `scheduled` or `manual`." }, "client_version": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "description": "The client's version." } } } } } }, "responses": { "201": { "description": "Make a snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSnapshotResult" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `read_only`, `paused`, `backup_role`, `bad_tree`, `tree_missing`, `bad_started_at`, `pruned_during_run`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "getBackupDevicesByIdSnapshots", "tags": [ "backup" ], "summary": "List a device's snapshots", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many (100 by default, up to 500).", "schema": { "minimum": 1, "maximum": 500, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 500, "type": "number" } ] } } ], "responses": { "200": { "description": "List a device's snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSnapshots" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/snapshots/{sid}/file": { "get": { "operationId": "getBackupDevicesByIdSnapshotsBySidFile", "tags": [ "backup" ], "summary": "Where one backed-up file's chunks are", "description": "One file of a backup, to put together on your side: each chunk's pack URL and byte range in order (`compression: df` = raw deflate), each chunk's BLAKE3 is its id. Up to 2 GB (`use_zip` past it). A path is a JSON list of names from the snapshot's root — the backed-up path, then folders (`[\"C:/Users/dana\",\"Documents\"]`); `[]` is the root.", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } }, { "name": "sid", "in": "path", "required": true, "description": "The snapshot's id.", "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "description": "The file, as a JSON list of names.", "schema": { "maxLength": 20000, "type": "string" } } ], "responses": { "200": { "description": "Where one backed-up file's chunks are", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupFileChunks" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `no_snapshot`, `no_path`, `not_a_file`, `use_zip`, `bad_path`, `sealed`, `blob_missing`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/snapshots/{sid}/tree": { "get": { "operationId": "getBackupDevicesByIdSnapshotsBySidTree", "tags": [ "backup" ], "summary": "List a folder of a backup", "description": "The files and folders in a folder of one of a device's backups: names, sizes, dates. A path is a JSON list of names from the snapshot's root — the backed-up path, then folders (`[\"C:/Users/dana\",\"Documents\"]`); `[]` is the root. A device backed up with a private key answers `sealed` (only its key reads it).", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } }, { "name": "sid", "in": "path", "required": true, "description": "The snapshot's id.", "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": false, "description": "The folder, as a JSON list of names.", "schema": { "maxLength": 20000, "type": "string" } } ], "responses": { "200": { "description": "List a folder of a backup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupFolder" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `no_snapshot`, `no_path`, `not_a_folder`, `bad_path`, `sealed`, `blob_missing`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/devices/{id}/suspicious": { "post": { "operationId": "postBackupDevicesByIdSuspicious", "tags": [ "backup" ], "summary": "Report ransomware-like changes", "description": "A backup client saw many files change in an unusual way (rewritten unreadable, ransomware extensions, ransom notes) and uploaded none of them: the device pauses (status `suspicious`) — its last good backup stays the latest — and its owner and a team's admins are alerted. Resuming it (PATCH paused: false, \"It was me\") clears it for a day.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason", "changed" ], "properties": { "reason": { "maxLength": 40, "type": "string", "description": "`extensions`, `ransom_note` or `entropy`." }, "changed": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "How many files changed." }, "sample": { "maxItems": 50, "type": "array", "items": { "maxLength": 1024, "type": "string" }, "description": "Some of their paths." }, "extensions": { "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } }, "description": "Counts per extension." } } } } } }, "responses": { "200": { "description": "Report ransomware-like changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupDeviceResult" } } } }, "default": { "description": "An error: `no_backup`, `no_device`, `backup_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/keys": { "get": { "operationId": "getBackupKeys", "tags": [ "backup" ], "summary": "Your private key's wrapped copies", "description": "For a plan where you chose \"Only me\": your data key, wrapped by your passphrase (PBKDF2-SHA256) and by your recovery key — base64 of nonce | AES-256-GCM ciphertext | tag. SendFlo never holds it unwrapped. Your client unwraps it and checks it against `key_id`.", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "team_id", "in": "query", "required": false, "description": "A team plan (your own plan when absent).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Your private key's wrapped copies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeys" } } } }, "default": { "description": "An error: `no_backup`, `not_on_team`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postBackupKeys", "tags": [ "backup" ], "summary": "Set up your private key", "description": "Store a new data key's wrapped copies (by your passphrase and by your recovery key). One per person per plan: `key_exists` when you have one. Then register devices with `key_mode: private`; their chunks and folder trees are sealed on the device, and SendFlo can't recover the backup if both the passphrase and the recovery key are lost.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key_id", "passphrase", "recovery" ], "properties": { "team_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A team plan." }, "key_id": { "maxLength": 64, "type": "string", "description": "BLAKE3 derive_key(\"sendflo backup 2026-10-29 key id\", key), hex." }, "passphrase": { "type": "object", "required": [ "wrapped", "kdf" ], "properties": { "wrapped": { "maxLength": 200, "type": "string" }, "kdf": { "type": "object", "patternProperties": { "^(.*)$": {} } } }, "description": "{wrapped, kdf: {alg: pbkdf2-sha256, iterations ≥ 600000, salt}}." }, "recovery": { "type": "object", "required": [ "wrapped", "kdf" ], "properties": { "wrapped": { "maxLength": 200, "type": "string" }, "kdf": { "type": "object", "patternProperties": { "^(.*)$": {} } } }, "description": "{wrapped, kdf: {alg: raw}}." } } } } } }, "responses": { "201": { "description": "Set up your private key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeysMade" } } } }, "default": { "description": "An error: `no_backup`, `no_private_key`, `key_exists`, `bad_key`, `not_on_team`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/keys/passphrase": { "put": { "operationId": "putBackupKeysPassphrase", "tags": [ "backup" ], "summary": "Change your private key's passphrase", "description": "The same key, wrapped by a new passphrase (`key_mismatch` when key_id isn't this plan's key). The recovery key still opens it.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key_id", "wrapped", "kdf" ], "properties": { "team_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A team plan." }, "key_id": { "maxLength": 64, "type": "string", "description": "The key's id." }, "wrapped": { "maxLength": 200, "type": "string", "description": "The key wrapped by the new passphrase." }, "kdf": { "type": "object", "patternProperties": { "^(.*)$": {} }, "description": "Its PBKDF2 parameters." } } } } } }, "responses": { "200": { "description": "Change your private key's passphrase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeyPassphrase" } } } }, "default": { "description": "An error: `no_backup`, `no_key`, `key_mismatch`, `bad_key`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/packs/{upload}": { "delete": { "operationId": "deleteBackupPacksByUpload", "tags": [ "backup" ], "summary": "Cancel a pack's upload", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "upload", "in": "path", "required": true, "description": "The upload's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel a pack's upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupPackCancelled" } } } }, "default": { "description": "An error: `no_backup`, `no_upload`, `upload_closed`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/packs/{upload}/complete": { "post": { "operationId": "postBackupPacksByUploadComplete", "tags": [ "backup" ], "summary": "Finish a pack's upload", "description": "SendFlo checks the parts the storage holds against the pack's size, then adds its blobs to the plan's index. Safe to call again.", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "upload", "in": "path", "required": true, "description": "The upload's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Finish a pack's upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupPackDone" } } } }, "default": { "description": "An error: `no_backup`, `no_upload`, `upload_closed`, `read_only`, `parts_missing`, `size_mismatch`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/packs/{upload}/parts": { "post": { "operationId": "postBackupPacksByUploadParts", "tags": [ "backup" ], "summary": "More part URLs for a pack", "security": [ { "apiKey": [ "backup.write" ] } ], "x-scope": "backup.write", "parameters": [ { "name": "upload", "in": "path", "required": true, "description": "The upload's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parts" ], "properties": { "parts": { "maxItems": 200, "type": "array", "items": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, "description": "Part numbers (from 1)." } } } } } }, "responses": { "200": { "description": "More part URLs for a pack", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupPackParts" } } } }, "default": { "description": "An error: `no_backup`, `no_upload`, `upload_closed`, `bad_parts`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/restores": { "get": { "operationId": "getBackupRestores", "tags": [ "backup" ], "summary": "List your restores", "description": "Your ZIP restores, newest first, with each one's device; a team's owner and admins also see the restores of the team's devices.", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "responses": { "200": { "description": "List your restores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupRestores" } } } }, "default": { "description": "An error: `no_backup`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/restores/{rid}": { "get": { "operationId": "getBackupRestoresByRid", "tags": [ "backup" ], "summary": "Get a restore", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "rid", "in": "path", "required": true, "description": "The restore's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a restore", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupRestoreOne" } } } }, "default": { "description": "An error: `no_restore`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteBackupRestoresByRid", "tags": [ "backup" ], "summary": "Cancel a restore", "description": "Stop a ZIP that's waiting or being put together.", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "rid", "in": "path", "required": true, "description": "The restore's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel a restore", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupRestoreCanceled" } } } }, "default": { "description": "An error: `no_restore`, `not_running`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/restores/{rid}/download": { "get": { "operationId": "getBackupRestoresByRidDownload", "tags": [ "backup" ], "summary": "Download a restore's ZIP", "description": "A short-lived URL for a ready ZIP (`not_ready` before; `expired` after its 7 days).", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "rid", "in": "path", "required": true, "description": "The restore's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Download a restore's ZIP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupRestoreDownload" } } } }, "default": { "description": "An error: `no_restore`, `not_ready`, `expired`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/teams/{id}/location": { "get": { "operationId": "getBackupTeamsByIdLocation", "tags": [ "backup" ], "summary": "Does a team show its members' computers' locations", "description": "`shows` for anyone on the team. To its owner and admins while it does, each computer whose person shared it with the team, with its last place (the look is in the audit log).", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The team plan's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Does a team show its members' computers' locations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDeviceLocations" } } } }, "default": { "description": "An error: `not_on_team`, `no_backup`, `no_team`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/backup/teams/{id}/policy": { "get": { "operationId": "getBackupTeamsByIdPolicy", "tags": [ "backup" ], "summary": "A team's Backup policy", "description": "What every member's computer follows: required folders (desktop, documents, pictures), extra exclusions, an upload cap, whether members may pause or remove a device, and who restores (members, admins, or members through a backup app). The team's owner and admins only; changed in the app (two-factor).", "security": [ { "apiKey": [ "backup.read" ] } ], "x-scope": "backup.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The team plan's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A team's Backup policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamBackupPolicy" } } } }, "default": { "description": "An error: `team_admin`, `not_on_team`, `no_backup`, `no_team`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/branding": { "get": { "operationId": "getBranding", "tags": [ "branding" ], "summary": "Read the default brand kit", "description": "The workspace's default brand kit; every field is null when there is none. `logo_url` and `wallpaper_url` are previews valid for 1 hour.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "responses": { "200": { "description": "Read the default brand kit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branding" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "putBranding", "tags": [ "branding" ], "summary": "Replace the default brand kit", "description": "Paid plans. Replaces the whole default kit: a field you leave out is cleared. Creates the kit when there is none (then `name` names it). Images are checked when you save (PNG, JPEG, WebP, GIF or an SVG without scripts).", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 80, "type": "string", "description": "The kit's name, used only when this creates it." }, "logo_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key from POST /v1/branding/assets; null or \"\" clears it." }, "wallpaper_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "Like `logo_key`." }, "accent": { "anyOf": [ { "maxLength": 9, "type": "string" }, { "type": "null" } ], "description": "A colour, `#RRGGBB`." }, "heading_color": { "anyOf": [ { "maxLength": 9, "type": "string" }, { "type": "null" } ], "description": "A colour, `#RRGGBB`." }, "page_text": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Text shown on your pages (500 characters at most)." }, "link_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "An `https:` link shown on your pages." }, "link_label": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "description": "The link's label (80 characters at most)." }, "thank_you_text": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "description": "Shown to uploaders when their files have arrived (300 characters). Every kit." }, "appearance": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "description": "`auto` (the visitor's system), `light` or `dark`; null follows the visitor's own theme. Every kit." }, "receipt": { "type": "boolean", "description": "Mail the uploader a receipt when their files arrive (when the page knows their address). Every kit." }, "sender_name": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ], "description": "\" via SendFlo\" in the From line of emails to uploaders (letters, numbers, spaces, `.,&'-`). Every kit." }, "reply_to": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "description": "Where replies to those emails go; used only once confirmed with POST /v1/brands/:id/reply-to/send and /confirm. Every kit." }, "redirect_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "An `https:` address uploaders are sent to after their files arrive. Plus and up." }, "favicon_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key from POST /v1/branding/assets (`kind: favicon`): the tab icon. Plus and up." }, "tab_title": { "anyOf": [ { "maxLength": 70, "type": "string" }, { "type": "null" } ], "description": "The browser tab's title (70 characters). Plus and up." }, "og_image_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key (`kind: og`, PNG, JPEG, WebP or GIF): the image chat apps show for the page's link. Plus and up." }, "og_title": { "anyOf": [ { "maxLength": 90, "type": "string" }, { "type": "null" } ], "description": "The link preview's title (90 characters). Plus and up." }, "og_description": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "The link preview's description (200 characters). Plus and up." }, "font": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "`inter`, `dm-sans`, `montserrat`, `poppins`, `space-grotesk`, `lora`, `merriweather` or `playfair`. Plus and up." }, "extra_wallpaper_keys": { "anyOf": [ { "maxItems": 4, "type": "array", "items": { "maxLength": 512, "type": "string" } }, { "type": "null" } ], "description": "Up to 4 more wallpaper keys: the page rotates through all of them. Pro and up." }, "video_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key (`kind: video`, MP4 or WebM, 20 MB): a muted, looping background (a still wallpaper for visitors who prefer less motion). Pro and up." }, "language": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "description": "The upload page's language: `en`, `de`, `es`, `fr`, `it`, `nl` or `pt`. Pro and up." }, "texts": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": { "maxLength": 300, "type": "string" } } }, { "type": "null" } ], "description": "Your own words for the upload page: `heading` (60), `intro` (200), `button` (40). Pro and up." } } } } } }, "responses": { "200": { "description": "Replace the default brand kit", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "logo_url", "wallpaper_url" ], "properties": { "ok": { "const": true, "type": "boolean" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "wallpaper_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "description": "An error: `paid_required`, `invalid_color`, `invalid_asset_key`, `invalid_link`, `unsafe_image`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/branding/assets": { "post": { "operationId": "postBrandingAssets", "tags": [ "branding" ], "summary": "Get an upload URL for a brand image", "description": "Paid plans. Returns a storage `key` and a presigned `put_url` (valid for 1 hour). Upload the file with `PUT put_url`, sending `content-type` equal to the `content_type` you gave and exactly `size` bytes (both are part of the signature), then use the key in the kit (`logo_key`, `wallpaper_key`, `extra_wallpaper_keys`, `favicon_key`, `og_image_key` or `video_key`). Sizes: a logo 2 MB, a wallpaper 10 MB, a favicon 512 KB, a link-preview image 5 MB, a video 20 MB; 60 upload URLs an hour per workspace. A favicon and a link-preview image need Plus, a video Pro. An uploaded file no kit uses is deleted after a day.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "content_type", "size" ], "properties": { "kind": { "anyOf": [ { "const": "logo", "type": "string" }, { "const": "wallpaper", "type": "string" }, { "const": "favicon", "type": "string" }, { "const": "og", "type": "string" }, { "const": "video", "type": "string" } ], "description": "`logo`, `wallpaper`, `favicon`, `og` (link preview) or `video`." }, "content_type": { "maxLength": 100, "type": "string", "description": "An image type (`image/…`), or `video/mp4` / `video/webm` for a video." }, "size": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ], "description": "The file's exact size in bytes." } } } } } }, "responses": { "200": { "description": "Get an upload URL for a brand image", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "put_url" ], "properties": { "key": { "type": "string" }, "put_url": { "type": "string" } } } } } }, "default": { "description": "An error: `paid_required`, `plan_required`, `invalid_content_type`, `too_large`, `rate_limited`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/brands": { "get": { "operationId": "getBrands", "tags": [ "branding" ], "summary": "List brand kits", "description": "Every kit (the default first), with 1-hour preview URLs, how many the plan allows, which options the plan carries, and — on Free with kits left from a paid plan — when they'll be deleted.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "responses": { "200": { "description": "List brand kits", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "limit", "options", "dormant_until", "team" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } }, "limit": { "type": "object", "required": [ "used", "max", "plan_class" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "max": { "description": "Kits the plan allows (0 on Free).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Kits the plan allows (0 on Free).", "type": "integer" } ] }, "plan_class": { "anyOf": [ { "const": "free", "type": "string" }, { "const": "starter", "type": "string" }, { "const": "plus", "type": "string" }, { "const": "pro", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, "options": { "description": "Each option (thank_you, appearance, receipt, sender_name, reply_to, email_kit, redirect, favicon, tab_title, link_preview, font, wallpapers, video, language, texts) and whether this plan has it.", "type": "object", "patternProperties": { "^(.*)$": { "type": "object", "required": [ "allowed", "needs" ], "properties": { "allowed": { "type": "boolean" }, "needs": { "description": "The plan an option needs: Lite, Plus or Pro.", "type": "string" } } } } }, "dormant_until": { "anyOf": [ { "format": "date-time", "description": "On Free: the kits are hidden and deleted at this time unless the plan has kits again.", "type": "string" }, { "type": "null" } ] }, "team": { "anyOf": [ { "description": "On a team seat: the team's brand kits and policy (Dropzone follow-up DZ5b). Null on a personal workspace.", "type": "object", "required": [ "plan_id", "allowed", "needs", "kits", "policy", "can_manage" ], "properties": { "plan_id": { "description": "The team (its subscription id).", "type": "string" }, "allowed": { "description": "Team Plus and up: the team's kits and its lock apply.", "type": "boolean" }, "needs": { "description": "The plan team kits need (Team Plus).", "type": "string" }, "kits": { "description": "The team's kits, read-only here: a page or link may name any of them.", "type": "array", "items": { "$ref": "#/components/schemas/Brand" } }, "policy": { "type": "object", "required": [ "locked", "default_kit_id" ], "properties": { "locked": { "description": "Members are locked to the team's kits: their own kits don't show, and new ones (or pages naming one) answer 409 brand_locked.", "type": "boolean" }, "default_kit_id": { "anyOf": [ { "description": "The team kit pages wear when they name none (and, locked, always).", "type": "string" }, { "type": "null" } ] } } }, "can_manage": { "description": "The caller is the team's Owner or an Admin (they manage team kits in the team console).", "type": "boolean" } } }, { "type": "null" } ] } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postBrands", "tags": [ "branding" ], "summary": "Create a brand kit", "description": "Paid plans, up to the plan's number of kits. The workspace's first kit becomes the default. On a team that locks members to its kits: 409 `brand_locked`.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 80, "type": "string", "description": "The kit's name (\"Brand N\" when blank)." }, "logo_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key from POST /v1/branding/assets; null or \"\" clears it." }, "wallpaper_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "Like `logo_key`." }, "accent": { "anyOf": [ { "maxLength": 9, "type": "string" }, { "type": "null" } ], "description": "A colour, `#RRGGBB`." }, "heading_color": { "anyOf": [ { "maxLength": 9, "type": "string" }, { "type": "null" } ], "description": "A colour, `#RRGGBB`." }, "page_text": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Text shown on your pages (500 characters at most)." }, "link_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "An `https:` link shown on your pages." }, "link_label": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "description": "The link's label (80 characters at most)." }, "thank_you_text": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "description": "Shown to uploaders when their files have arrived (300 characters). Every kit." }, "appearance": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "description": "`auto` (the visitor's system), `light` or `dark`; null follows the visitor's own theme. Every kit." }, "receipt": { "type": "boolean", "description": "Mail the uploader a receipt when their files arrive (when the page knows their address). Every kit." }, "sender_name": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ], "description": "\" via SendFlo\" in the From line of emails to uploaders (letters, numbers, spaces, `.,&'-`). Every kit." }, "reply_to": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "description": "Where replies to those emails go; used only once confirmed with POST /v1/brands/:id/reply-to/send and /confirm. Every kit." }, "redirect_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "An `https:` address uploaders are sent to after their files arrive. Plus and up." }, "favicon_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key from POST /v1/branding/assets (`kind: favicon`): the tab icon. Plus and up." }, "tab_title": { "anyOf": [ { "maxLength": 70, "type": "string" }, { "type": "null" } ], "description": "The browser tab's title (70 characters). Plus and up." }, "og_image_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key (`kind: og`, PNG, JPEG, WebP or GIF): the image chat apps show for the page's link. Plus and up." }, "og_title": { "anyOf": [ { "maxLength": 90, "type": "string" }, { "type": "null" } ], "description": "The link preview's title (90 characters). Plus and up." }, "og_description": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "The link preview's description (200 characters). Plus and up." }, "font": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "`inter`, `dm-sans`, `montserrat`, `poppins`, `space-grotesk`, `lora`, `merriweather` or `playfair`. Plus and up." }, "extra_wallpaper_keys": { "anyOf": [ { "maxItems": 4, "type": "array", "items": { "maxLength": 512, "type": "string" } }, { "type": "null" } ], "description": "Up to 4 more wallpaper keys: the page rotates through all of them. Pro and up." }, "video_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key (`kind: video`, MP4 or WebM, 20 MB): a muted, looping background (a still wallpaper for visitors who prefer less motion). Pro and up." }, "language": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "description": "The upload page's language: `en`, `de`, `es`, `fr`, `it`, `nl` or `pt`. Pro and up." }, "texts": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": { "maxLength": 300, "type": "string" } } }, { "type": "null" } ], "description": "Your own words for the upload page: `heading` (60), `intro` (200), `button` (40). Pro and up." } } } } } }, "responses": { "201": { "description": "Create a brand kit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "default": { "description": "An error: `paid_required`, `plan_required`, `brand_limit`, `brand_locked`, `invalid_color`, `invalid_asset_key`, `invalid_link`, `invalid_redirect`, `invalid_appearance`, `invalid_font`, `invalid_language`, `invalid_reply_to`, `invalid_sender_name`, `unsafe_image`, `unsafe_video`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/brands/{id}": { "patch": { "operationId": "patchBrandsById", "tags": [ "branding" ], "summary": "Update a brand kit", "description": "Paid plans. Changes only the fields you send; null or \"\" clears one. An option above the plan answers 403 `plan_required` with the `option` and the plan it `needs`; clearing one never does. Changing `reply_to` needs it confirmed again.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kit's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 80, "type": "string", "description": "The kit's name." }, "logo_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key from POST /v1/branding/assets; null or \"\" clears it." }, "wallpaper_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "Like `logo_key`." }, "accent": { "anyOf": [ { "maxLength": 9, "type": "string" }, { "type": "null" } ], "description": "A colour, `#RRGGBB`." }, "heading_color": { "anyOf": [ { "maxLength": 9, "type": "string" }, { "type": "null" } ], "description": "A colour, `#RRGGBB`." }, "page_text": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Text shown on your pages (500 characters at most)." }, "link_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "An `https:` link shown on your pages." }, "link_label": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "description": "The link's label (80 characters at most)." }, "thank_you_text": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "description": "Shown to uploaders when their files have arrived (300 characters). Every kit." }, "appearance": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "description": "`auto` (the visitor's system), `light` or `dark`; null follows the visitor's own theme. Every kit." }, "receipt": { "type": "boolean", "description": "Mail the uploader a receipt when their files arrive (when the page knows their address). Every kit." }, "sender_name": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ], "description": "\" via SendFlo\" in the From line of emails to uploaders (letters, numbers, spaces, `.,&'-`). Every kit." }, "reply_to": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "description": "Where replies to those emails go; used only once confirmed with POST /v1/brands/:id/reply-to/send and /confirm. Every kit." }, "redirect_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "An `https:` address uploaders are sent to after their files arrive. Plus and up." }, "favicon_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key from POST /v1/branding/assets (`kind: favicon`): the tab icon. Plus and up." }, "tab_title": { "anyOf": [ { "maxLength": 70, "type": "string" }, { "type": "null" } ], "description": "The browser tab's title (70 characters). Plus and up." }, "og_image_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key (`kind: og`, PNG, JPEG, WebP or GIF): the image chat apps show for the page's link. Plus and up." }, "og_title": { "anyOf": [ { "maxLength": 90, "type": "string" }, { "type": "null" } ], "description": "The link preview's title (90 characters). Plus and up." }, "og_description": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "The link preview's description (200 characters). Plus and up." }, "font": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "`inter`, `dm-sans`, `montserrat`, `poppins`, `space-grotesk`, `lora`, `merriweather` or `playfair`. Plus and up." }, "extra_wallpaper_keys": { "anyOf": [ { "maxItems": 4, "type": "array", "items": { "maxLength": 512, "type": "string" } }, { "type": "null" } ], "description": "Up to 4 more wallpaper keys: the page rotates through all of them. Pro and up." }, "video_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "A key (`kind: video`, MP4 or WebM, 20 MB): a muted, looping background (a still wallpaper for visitors who prefer less motion). Pro and up." }, "language": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "description": "The upload page's language: `en`, `de`, `es`, `fr`, `it`, `nl` or `pt`. Pro and up." }, "texts": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": { "maxLength": 300, "type": "string" } } }, { "type": "null" } ], "description": "Your own words for the upload page: `heading` (60), `intro` (200), `button` (40). Pro and up." } } } } } }, "responses": { "200": { "description": "Update a brand kit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "default": { "description": "An error: `paid_required`, `plan_required`, `not_found`, `invalid_color`, `invalid_asset_key`, `invalid_link`, `invalid_redirect`, `invalid_appearance`, `invalid_font`, `invalid_language`, `invalid_reply_to`, `invalid_sender_name`, `unsafe_image`, `unsafe_video`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteBrandsById", "tags": [ "branding" ], "summary": "Delete a brand kit", "description": "Links and upload pages that used it fall back to the default kit; deleting the default makes the oldest remaining kit the default.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kit's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete a brand kit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/brands/{id}/default": { "post": { "operationId": "postBrandsByIdDefault", "tags": [ "branding" ], "summary": "Make a brand kit the default", "description": "The default kit is what links and upload pages without their own kit show.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kit's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Make a brand kit the default", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/brands/{id}/reply-to/confirm": { "post": { "operationId": "postBrandsByIdReplyToConfirm", "tags": [ "branding" ], "summary": "Confirm a kit's Reply-To with its code", "description": "From then on, replies to emails sent for this kit go to its `reply_to`. Five wrong codes end the code.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kit's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "minLength": 4, "maxLength": 12, "type": "string", "description": "The 6-digit code from the email." } } } } } }, "responses": { "200": { "description": "Confirm a kit's Reply-To with its code", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verified" ], "properties": { "ok": { "const": true, "type": "boolean" }, "verified": { "const": true, "type": "boolean" } } } } } }, "default": { "description": "An error: `not_found`, `code_expired`, `wrong_code`, `too_many_attempts`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/brands/{id}/reply-to/send": { "post": { "operationId": "postBrandsByIdReplyToSend", "tags": [ "branding" ], "summary": "Mail a code to confirm a kit's Reply-To", "description": "Every kit (Lite and up). Mails a 6-digit code to the kit's saved `reply_to`, valid for 15 minutes; 5 codes an hour per workspace. Answers `verified: true` at once when the address is already confirmed.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The kit's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mail a code to confirm a kit's Reply-To", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verified" ], "properties": { "ok": { "const": true, "type": "boolean" }, "verified": { "type": "boolean" }, "expires_in": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "default": { "description": "An error: `plan_required`, `not_found`, `no_reply_to`, `rate_limited`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/cloud-agents": { "get": { "operationId": "getCloudAgents", "tags": [ "cloud-agents" ], "summary": "List cloud agents", "description": "This workspace's cloud agents, newest first (32 at most). Secrets are never returned (`has_secret`).", "security": [ { "apiKey": [ "agent_tasks.read" ] } ], "x-scope": "agent_tasks.read", "responses": { "200": { "description": "List cloud agents", "content": { "application/json": { "schema": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/CloudAgent" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postCloudAgents", "tags": [ "cloud-agents" ], "summary": "Add a cloud agent", "description": "A `webhook` agent (needs `config.url`; its signing `secret` is made here and shown once), an `a2a` agent (needs `config.url`; its agent card is fetched now), a `routine` (needs `config.routine_id` and `secret`), or a `pull` agent (nothing needed; it claims tasks with a key). URLs must be https and public. 32 per workspace.", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "minLength": 1, "maxLength": 120, "description": "The agent's name.", "type": "string" }, "kind": { "anyOf": [ { "const": "webhook", "type": "string" }, { "const": "a2a", "type": "string" }, { "const": "routine", "type": "string" }, { "const": "pull", "type": "string" } ], "description": "`webhook`, `a2a`, `routine` or `pull` (can't be changed later)." }, "config": { "anyOf": [ { "type": "object", "properties": { "url": { "maxLength": 1000, "description": "Webhook agents: where tasks are posted. A2A agents: the agent card, site or endpoint. https and public.", "type": "string" }, "routine_id": { "description": "Routine agents: the routine's id.", "type": "string" }, "max_minutes": { "description": "A2A agents: how long a task may run, 1–1440 minutes (120 by default).", "type": "number" } } }, { "type": "null" } ], "description": "`{ url?, routine_id?, max_minutes? }`: what the kind needs (see above)." }, "secret": { "anyOf": [ { "maxLength": 4000, "description": "A2A: sent to the agent as a bearer token. Routine: the trigger token (required). Webhook: ignored on create (SendFlo makes the signing secret).", "type": "string" }, { "type": "null" } ], "description": "A2A: a bearer token sent to the agent. Routine: its trigger token. Webhook: ignored (SendFlo makes the signing secret)." }, "enabled": { "description": "Pause (false) or resume (true); a new agent is always on.", "type": "boolean" }, "presets": { "maxItems": 12, "description": "Up to 12 ready-made instructions `{ id, label, instruction }` senders can pick.", "type": "array", "items": { "type": "object", "required": [ "id", "label", "instruction" ], "properties": { "id": { "type": "string" }, "label": { "maxLength": 60, "type": "string" }, "instruction": { "maxLength": 2000, "type": "string" } } } }, "accept": { "anyOf": [ { "type": "object", "properties": { "types": { "maxItems": 20, "type": "array", "items": { "type": "string" } }, "max_mb": { "type": "number" } } }, { "type": "null" } ], "description": "`{ types?, max_mb? }`: tasks whose files total more than `max_mb` are refused." } } } } } }, "responses": { "200": { "description": "Add a cloud agent", "content": { "application/json": { "schema": { "type": "object", "required": [ "agent" ], "properties": { "agent": { "$ref": "#/components/schemas/CloudAgent" }, "secret": { "description": "Webhook agents: the signing secret, shown once.", "type": "string" } } } } } }, "default": { "description": "An error: `invalid_agent`, `too_many_agents`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/cloud-agents/{id}": { "patch": { "operationId": "patchCloudAgentsById", "tags": [ "cloud-agents" ], "summary": "Change a cloud agent", "description": "Changes the fields you send (`kind` can't change). `config` keys are merged over the stored ones; `secret: null` clears the secret; `presets` replaces the list. After changing an A2A agent's URL, run its test to refresh the endpoint.", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The cloud agent's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 120, "description": "The agent's name.", "type": "string" }, "kind": { "anyOf": [ { "const": "webhook", "type": "string" }, { "const": "a2a", "type": "string" }, { "const": "routine", "type": "string" }, { "const": "pull", "type": "string" } ], "description": "`webhook`, `a2a`, `routine` or `pull` (can't be changed later)." }, "config": { "anyOf": [ { "type": "object", "properties": { "url": { "maxLength": 1000, "description": "Webhook agents: where tasks are posted. A2A agents: the agent card, site or endpoint. https and public.", "type": "string" }, "routine_id": { "description": "Routine agents: the routine's id.", "type": "string" }, "max_minutes": { "description": "A2A agents: how long a task may run, 1–1440 minutes (120 by default).", "type": "number" } } }, { "type": "null" } ], "description": "`{ url?, routine_id?, max_minutes? }`: what the kind needs (see above)." }, "secret": { "anyOf": [ { "maxLength": 4000, "description": "A2A: sent to the agent as a bearer token. Routine: the trigger token (required). Webhook: ignored on create (SendFlo makes the signing secret).", "type": "string" }, { "type": "null" } ], "description": "A2A: a bearer token sent to the agent. Routine: its trigger token. Webhook: ignored (SendFlo makes the signing secret)." }, "enabled": { "description": "Pause (false) or resume (true); a new agent is always on.", "type": "boolean" }, "presets": { "maxItems": 12, "description": "Up to 12 ready-made instructions `{ id, label, instruction }` senders can pick.", "type": "array", "items": { "type": "object", "required": [ "id", "label", "instruction" ], "properties": { "id": { "type": "string" }, "label": { "maxLength": 60, "type": "string" }, "instruction": { "maxLength": 2000, "type": "string" } } } }, "accept": { "anyOf": [ { "type": "object", "properties": { "types": { "maxItems": 20, "type": "array", "items": { "type": "string" } }, "max_mb": { "type": "number" } } }, { "type": "null" } ], "description": "`{ types?, max_mb? }`: tasks whose files total more than `max_mb` are refused." } } } } } }, "responses": { "200": { "description": "Change a cloud agent", "content": { "application/json": { "schema": { "type": "object", "required": [ "agent" ], "properties": { "agent": { "$ref": "#/components/schemas/CloudAgent" } } } } } }, "default": { "description": "An error: `not_found`, `invalid_agent`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteCloudAgentsById", "tags": [ "cloud-agents" ], "summary": "Delete a cloud agent", "description": "Deletes it. Its tasks not yet sent fail (`agent_missing`).", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The cloud agent's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete a cloud agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/cloud-agents/{id}/test": { "post": { "operationId": "postCloudAgentsByIdTest", "tags": [ "cloud-agents" ], "summary": "Health-check a cloud agent", "description": "A2A: reads the agent card again. Webhook: posts a signed `{ \"type\": \"agent_task.ping\" }` (10-second timeout) and reports the HTTP status. Routine and pull: checks the configuration only. The result is stored as the agent's `status`.", "security": [ { "apiKey": [ "agent_tasks.write" ] } ], "x-scope": "agent_tasks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The cloud agent's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Health-check a cloud agent", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/CloudAgentHealth" } } } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/credits": { "get": { "operationId": "getCredits", "tags": [ "account" ], "summary": "Get your credit balance and prices", "description": "The workspace's prepaid credit balance and the price list, as integer strings. The balance can go negative after metered use.", "security": [ { "apiKey": [ "usage.read" ] } ], "x-scope": "usage.read", "responses": { "200": { "description": "Get your credit balance and prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credits" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive": { "get": { "operationId": "getDrive", "tags": [ "drive" ], "summary": "Get your Drive", "description": "Your My files space (its top folder, the room used) and your Drive plan. A key acts as the person who made it. `no_drive` when they have no Drive plan. An app the person allowed only some folders (DA3) gets those `folders` instead (space and plan null) — it starts from them; every other folder answers `drive_folder_grant`.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "Get your Drive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSummary" } } } }, "default": { "description": "An error: `no_drive`, `drive_folder_grant`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/automations/{id}": { "patch": { "operationId": "patchDriveAutomationsById", "tags": [ "drive" ], "summary": "Change, pause or resume an automation", "description": "Any of its fields, or `enabled`.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The automation's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "maxLength": 120, "type": "string", "description": "Its name." }, "trigger": { "maxLength": 12, "type": "string", "description": "Its trigger." }, "subfolders": { "type": "boolean", "description": "Files in subfolders too." }, "conditions": { "type": "object", "patternProperties": { "^(.*)$": {} }, "description": "Its conditions." }, "actions": { "maxItems": 6, "type": "array", "items": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "description": "Its actions." }, "enabled": { "type": "boolean", "description": "false pauses it." } } } } } }, "responses": { "200": { "description": "Change, pause or resume an automation", "content": { "application/json": { "schema": { "type": "object", "required": [ "automation" ], "properties": { "automation": { "$ref": "#/components/schemas/DriveAutomation" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_automation`, `automations_role`, `bad_rule`, `bad_folder`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveAutomationsById", "tags": [ "drive" ], "summary": "Remove an automation", "description": "It stops; its run log goes with it.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The automation's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Remove an automation", "content": { "application/json": { "schema": { "type": "object", "required": [ "removed" ], "properties": { "removed": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_automation`, `automations_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/automations/{id}/runs": { "get": { "operationId": "getDriveAutomationsByIdRuns", "tags": [ "drive" ], "summary": "What an automation did", "description": "Its last 50 runs, newest first: `done` (with each step), `failed` (why), `skipped` (which condition didn't hold) or `loop_stopped`. Kept 30 days.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The automation's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "What an automation did", "content": { "application/json": { "schema": { "type": "object", "required": [ "automation", "runs" ], "properties": { "automation": { "$ref": "#/components/schemas/DriveAutomation" }, "runs": { "type": "array", "items": { "type": "object", "required": [ "id", "node_id", "name", "trigger", "status", "steps", "error", "at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "node_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "trigger": { "type": "string" }, "status": { "anyOf": [ { "const": "done", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "skipped", "type": "string" }, { "const": "loop_stopped", "type": "string" } ] }, "steps": { "type": "array", "items": { "type": "string" } }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "at": { "format": "date-time", "type": "string" } } } } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_automation`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/changes": { "get": { "operationId": "getDriveChanges", "tags": [ "drive" ], "summary": "List changes since a point", "description": "Every change to My files after `since` (a `seq`), in order — what a sync client reads to stay current. `cursor` is the last change returned; `more` says there are more. Changes are numbered without gaps.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "since", "in": "query", "required": false, "description": "The last `seq` you have (0: from the start).", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1–5,000 (1,000 by default).", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "List changes since a point", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveChanges" } } } }, "default": { "description": "An error: `no_drive`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/clients": { "get": { "operationId": "getDriveClients", "tags": [ "drive" ], "summary": "List your computers syncing Drive", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "List your computers syncing Drive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSyncClients" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postDriveClients", "tags": [ "drive" ], "summary": "Register a computer's sync client", "description": "Once per install: its name (shown in conflict copies and Settings), OS, client version and kind of drive. No local paths are sent.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "root_kind" ], "properties": { "name": { "maxLength": 120, "type": "string", "description": "The computer's name." }, "os": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "description": "e.g. `windows 10.0.19045`." }, "client_version": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "description": "The client's version." }, "root_kind": { "maxLength": 12, "type": "string", "description": "`cfapi` (Windows), `fileprovider` (macOS), `fuse` (Linux) or `folder` (a synced folder)." } } } } } }, "responses": { "200": { "description": "Register a computer's sync client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSyncClientResult" } } } }, "default": { "description": "An error: `bad_root_kind`, `bad_name`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/clients/{id}": { "delete": { "operationId": "deleteDriveClientsById", "tags": [ "drive" ], "summary": "Remove a computer's sync client", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Remove a computer's sync client", "content": { "application/json": { "schema": { "type": "object", "required": [ "removed" ], "properties": { "removed": { "const": true, "type": "boolean" } } } } } }, "default": { "description": "An error: `no_client`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/clients/{id}/heartbeat": { "post": { "operationId": "postDriveClientsByIdHeartbeat", "tags": [ "drive" ], "summary": "Report a sync client's state", "description": "Every few minutes and on a change of state: the client's state, its problems by reason, items waiting, its cache, folders hidden on this computer, and how far each space's feed was applied.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "maxLength": 10, "type": "string", "description": "`ok`, `syncing`, `paused`, `problems` or `offline`." }, "problems": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "Items that failed." }, "problem_reasons": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ] } } }, { "type": "null" } ], "description": "{reason: count}." }, "pending": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "Items waiting." }, "cache_bytes": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ] } ] }, { "type": "null" } ], "description": "Bytes kept locally." }, "cache_budget": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ] } ] }, { "type": "null" } ], "description": "The cache's limit." }, "hidden": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "Folders hidden on this computer." }, "spaces": { "anyOf": [ { "maxItems": 200, "type": "array", "items": { "type": "object", "required": [ "space_id", "cursor" ], "properties": { "space_id": { "type": "string" }, "cursor": { "type": "string" } } } }, { "type": "null" } ], "description": "[{space_id, cursor}]." }, "client_version": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "description": "If it changed." }, "managed": { "anyOf": [ { "type": "object", "properties": { "keys": { "maxItems": 10, "type": "array", "items": { "maxLength": 20, "type": "string" } }, "team": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ], "description": "{keys, team}: the settings an organisation's device management set on this computer (unknown keys dropped); null clears them, absent keeps them." }, "peer": { "anyOf": [ { "type": "object", "required": [ "addr", "port", "token" ], "properties": { "addr": { "maxLength": 45, "type": "string" }, "port": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "token": { "maxLength": 64, "type": "string" } } }, { "type": "null" } ], "description": "{addr, port, token}: where this computer serves Drive files to nearby computers (a private address; the token is random per run and never shown to anyone). null: it stopped." }, "peer_in": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "Bytes fetched from nearby computers since the last heartbeat." }, "peer_out": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "Bytes served to them since the last heartbeat." }, "shared": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "description": "Why several people use this computer at once (Windows Server, a multi-session edition): nearby devices and the hotspot are off there. null clears it, absent keeps it." } } } } } }, "responses": { "200": { "description": "Report a sync client's state", "content": { "application/json": { "schema": { "type": "object", "required": [ "client" ], "properties": { "client": { "$ref": "#/components/schemas/DriveSyncClient" } } } } } }, "default": { "description": "An error: `no_client`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/comments/{id}": { "patch": { "operationId": "patchDriveCommentsById", "tags": [ "drive" ], "summary": "Edit or resolve a comment", "description": "`body` edits your own comment; `resolved` resolves or reopens a thread (its author or an editor).", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The comment's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "maxLength": 2000, "type": "string", "description": "The new text." }, "resolved": { "type": "boolean", "description": "true resolves, false reopens." } } } } } }, "responses": { "200": { "description": "Edit or resolve a comment", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_comment`, `not_yours`, `bad_body`, `deleted`, `reply`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveCommentsById", "tags": [ "drive" ], "summary": "Delete a comment", "description": "Your own (a co-owner any). A comment with replies stays as \"Comment deleted\".", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The comment's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete a comment", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `not_yours`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/comments/{id}/task": { "post": { "operationId": "postDriveCommentsByIdTask", "tags": [ "drive" ], "summary": "Turn a comment into a task", "description": "For someone who can open the file, with an optional due date; they're notified. Editors. Again on the same comment reassigns it.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The comment's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assignee_id" ], "properties": { "assignee_id": { "type": "string", "description": "Their user id." }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When it's due." } } } } } }, "responses": { "200": { "description": "Turn a comment into a task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveTask" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_comment`, `assignee_no_access`, `deleted`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/conflicts": { "get": { "operationId": "getDriveConflicts", "tags": [ "drive" ], "summary": "List your open sync conflicts", "description": "Saves that arrived after the file had changed: each became a copy beside the file. Yours, in every space you sync (a team's admins see their spaces' all).", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "List your open sync conflicts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveConflicts" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/conflicts/{id}/resolve": { "post": { "operationId": "postDriveConflictsByIdResolve", "tags": [ "drive" ], "summary": "Resolve a sync conflict", "description": "`file`: keep the file (the copy goes to the trash); `copy`: the copy's content becomes the file's newest version (the copy goes to the trash); `both`: keep both as they are. Nothing is deleted for good. Someone else's conflict notifies them.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The conflict's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keep" ], "properties": { "keep": { "maxLength": 8, "type": "string", "description": "`file`, `copy` or `both`." } } } } } }, "responses": { "200": { "description": "Resolve a sync conflict", "content": { "application/json": { "schema": { "type": "object", "required": [ "conflict" ], "properties": { "conflict": { "$ref": "#/components/schemas/DriveConflict" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_conflict`, `resolved`, `gone`, `bad_keep`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/folders": { "post": { "operationId": "postDriveFolders", "tags": [ "drive" ], "summary": "Make a folder", "description": "In `parent_id` (the top folder when absent). A name already there (compared case-insensitively) is refused with `name_taken`, or numbered — \"Reports (2)\" — with `on_conflict: rename`.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "parent_id": { "type": "string", "description": "The folder to make it in." }, "name": { "maxLength": 1024, "type": "string", "description": "Its name (no `/`, 255 bytes at most). In a private space, the name sealed on your device." }, "name_key": { "maxLength": 64, "type": "string", "description": "In a private space (end-to-end): the name's index (64 hex) your device computed — required there, ignored elsewhere." }, "on_conflict": { "type": "string", "description": "`fail` (the default) or `rename`." } } } } } }, "responses": { "200": { "description": "Make a folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveNodeResult" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `no_folder`, `name_taken`, `bad_name`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/folders/{id}": { "get": { "operationId": "getDriveFoldersById", "tags": [ "drive" ], "summary": "List a folder", "description": "A folder, its path from the top, and what is in it: folders first, then by `sort` (`name`, `modified`, `size`) and `dir`. `root` is the top folder.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The folder's id, or `root`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`name` (the default), `modified` or `size`.", "schema": { "anyOf": [ { "const": "name", "type": "string" }, { "const": "modified", "type": "string" }, { "const": "size", "type": "string" } ] } }, { "name": "dir", "in": "query", "required": false, "description": "`asc` (the default) or `desc`.", "schema": { "anyOf": [ { "const": "asc", "type": "string" }, { "const": "desc", "type": "string" } ] } } ], "responses": { "200": { "description": "List a folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveFolder" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `no_folder`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/links": { "get": { "operationId": "getDriveLinks", "tags": [ "drive" ], "summary": "List your Drive links", "description": "Every live link you made, newest first, with the file or folder it opens.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "List your Drive links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyDriveLinks" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/links/{id}": { "patch": { "operationId": "patchDriveLinksById", "tags": [ "drive" ], "summary": "Change a link", "description": "Its end (`expires_at`; a public link keeps one), `download_limit`, `delivery` or `password` (null removes it).", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The link's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When it ends (null: never, not for a public link)." }, "download_limit": { "anyOf": [ { "minimum": 1, "maximum": 100000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100000, "type": "integer" } ] }, { "type": "null" } ], "description": "1–100,000, or null." }, "delivery": { "type": "string", "description": "preview_download, download_only or preview_only." }, "password": { "anyOf": [ { "minLength": 4, "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "4–128 characters, or null to remove it." } } } } } }, "responses": { "200": { "description": "Change a link", "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "anyOf": [ { "$ref": "#/components/schemas/DriveLink" }, { "type": "null" } ] } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_link`, `bad_expiry`, `bad_delivery`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveLinksById", "tags": [ "drive" ], "summary": "Turn a link off", "description": "Its page then says the owner turned it off.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The link's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Turn a link off", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}": { "get": { "operationId": "getDriveNodesById", "tags": [ "drive" ], "summary": "Get a file or folder", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a file or folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveNodeWithPath" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "patchDriveNodesById", "tags": [ "drive" ], "summary": "Rename or move a file or folder", "description": "`name` renames; `parent_id` moves it (with everything in it) to another folder — a name already there is refused, or numbered with `on_conflict: rename`. A folder can't go inside itself.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "maxLength": 1024, "type": "string", "description": "The new name (in a private space, sealed on your device)." }, "name_key": { "maxLength": 64, "type": "string", "description": "In a private space: the new name's index (64 hex), with the sealed `name`." }, "parent_id": { "type": "string", "description": "The folder to move it to." }, "on_conflict": { "type": "string", "description": "When moving: `fail` (the default) or `rename`." } } } } } }, "responses": { "200": { "description": "Rename or move a file or folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveNodeResult" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `name_taken`, `bad_name`, `into_itself`, `root`, `bad_parent`, `agent_bulk_limit`, `drive_folder_grant`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveNodesById", "tags": [ "drive" ], "summary": "Move a file or folder to the trash", "description": "With everything in it. Kept the plan's version days, then deleted for good; restore it with POST …/restore. An app that signed in with OAuth needs `drive.delete` (an API key's `drive.write` covers it); an app or agent moves at most 25 files at once (`agent_bulk_limit`).", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Move a file or folder to the trash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveTrashed" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `root`, `agent_bulk_limit`, `drive_folder_grant`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/automations": { "get": { "operationId": "getDriveNodesByIdAutomations", "tags": [ "drive" ], "summary": "A folder's automations", "description": "Its rules (trigger, conditions, actions), and whether you may change them: edit access to the folder, and in a team space its policy (Policies › Drive: owner and admins, the default, or everyone who can edit the folder).", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A folder's automations", "content": { "application/json": { "schema": { "type": "object", "required": [ "automations", "can_manage" ], "properties": { "automations": { "type": "array", "items": { "$ref": "#/components/schemas/DriveAutomation" } }, "can_manage": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `not_a_folder`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postDriveNodesByIdAutomations", "tags": [ "drive" ], "summary": "Add an automation to a folder", "description": "A rule that runs on its own, as you: when a file is `added` to the folder, `changed` (a new version) or `labeled`; if every condition holds (`extensions`, `name_contains`, `min_bytes`, `max_bytes`, `label_ids`, `people`); do each action in order — `move` / `copy` {folder_id} (a folder in the same space), `label` {label_ids} (team spaces), `notify` {user_ids, message?}, `review` {user_ids, message?, due_days?} (a comment with a task for each reviewer). People who can't see the file aren't told about it. `subfolders` (default true): files in its subfolders too. A rule never fires on its own change; a chain of automations stops at its third step. 25 rules a space.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The folder's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "maxLength": 120, "type": "string", "description": "The rule's name." }, "trigger": { "maxLength": 12, "type": "string", "description": "`added`, `changed` or `labeled` (which needs conditions.label_ids)." }, "subfolders": { "type": "boolean", "description": "Files in subfolders too (default true)." }, "conditions": { "type": "object", "patternProperties": { "^(.*)$": {} }, "description": "All must hold." }, "actions": { "maxItems": 6, "type": "array", "items": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "description": "1 to 6, done in order." }, "enabled": { "type": "boolean", "description": "false: made paused." } } } } } }, "responses": { "200": { "description": "Add an automation to a folder", "content": { "application/json": { "schema": { "type": "object", "required": [ "automation" ], "properties": { "automation": { "$ref": "#/components/schemas/DriveAutomation" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `not_a_folder`, `automations_role`, `bad_rule`, `bad_folder`, `too_many_rules`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/comments": { "get": { "operationId": "getDriveNodesByIdComments", "tags": [ "drive" ], "summary": "List a file's comments", "description": "Its threads, oldest first: each comment with one level of replies, its author, an anchor (`time`, `page`, `region` of the version it was made on), whether it's resolved, and its task. `can_task`: may you turn comments into tasks (editors).", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List a file's comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveComments" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postDriveNodesByIdComments", "tags": [ "drive" ], "summary": "Comment on a file", "description": "Anyone the file is shared with may comment (previewers too). `parent_id` replies to a thread; `anchor` points at a time (`{kind: \"time\", t}` seconds), a page (`{kind: \"page\", page}`) or a region (`{kind: \"region\", x, y, w, h}` fractions). `mentions`: user ids of people who can open the file — they're notified.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "maxLength": 2000, "type": "string", "description": "1–2,000 characters." }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reply to this comment." }, "anchor": { "anyOf": [ {}, { "type": "null" } ], "description": "Where it points." }, "mentions": { "maxItems": 20, "type": "array", "items": { "type": "string" }, "description": "Up to 20 user ids." } } } } } }, "responses": { "200": { "description": "Comment on a file", "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "object", "required": [ "id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" } } } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `bad_body`, `no_comment`, `nested_reply`, `mention_no_access`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/copy": { "post": { "operationId": "postDriveNodesByIdCopy", "tags": [ "drive" ], "summary": "Copy a file or folder", "description": "Into `parent_id` (its own folder when absent), as \"name (2)\" when the name is taken. Instant — the copies share the stored content — and they count against the room like any file. 10,000 items at most per copy.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "type": "string", "description": "The folder to copy it into." } } } } } }, "responses": { "200": { "description": "Copy a file or folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveNodeResult" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `into_itself`, `too_many`, `drive_full`, `agent_bulk_limit`, `drive_folder_grant`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/download": { "get": { "operationId": "getDriveNodesByIdDownload", "tags": [ "drive" ], "summary": "Download a file", "description": "A short-lived URL (an hour) for the current version, or an earlier one with `version`; `inline=1` for viewing in a browser. Works on a plan that ended (until the files are deleted). Empty files answer a `data:` URL.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "description": "An earlier version's id (GET …/versions).", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "inline", "in": "query", "required": false, "description": "`1`: for viewing, not saving.", "schema": { "const": "1", "type": "string" } } ], "responses": { "200": { "description": "Download a file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveDownload" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `no_version`, `gone`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/links": { "get": { "operationId": "getDriveNodesByIdLinks", "tags": [ "drive" ], "summary": "List a file's or folder's links", "description": "Its live links (owners and co-owners).", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List a file's or folder's links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveLinks" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postDriveNodesByIdLinks", "tags": [ "drive" ], "summary": "Make a link to a file or folder", "description": "A page at `url` that opens it: `public` (anyone with the link), `verified` (anyone who confirms their email with a code) or `restricted` (only `emails`). A file link serves the latest version (`mode: latest`, the default) or the current one for good (`mode: version`); a folder link lists the folder's current contents. Optional `password`, `download_limit` and `delivery` (`preview_download`, `download_only`, `preview_only`). Public links end after 30 days unless `expires_at` says otherwise (a year at most). Bytes go out only once the malware scan cleared them. Owners and co-owners.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audience": { "type": "string", "description": "public (default), verified or restricted." }, "emails": { "maxItems": 50, "type": "array", "items": { "maxLength": 320, "type": "string" }, "description": "restricted: up to 50 addresses." }, "password": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "4–128 characters." }, "delivery": { "type": "string", "description": "preview_download (default), download_only or preview_only." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When it ends." }, "download_limit": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ], "description": "1–100,000 downloads." }, "mode": { "type": "string", "description": "Files: latest (default) or version." }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "mode version: which version (the current one when absent)." } } } } } }, "responses": { "200": { "description": "Make a link to a file or folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveLinkResult" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `read_only`, `link_root`, `file_flagged`, `bad_audience`, `bad_delivery`, `bad_email`, `no_emails`, `too_many_emails`, `bad_expiry`, `bad_limit`, `bad_password`, `no_version`, `public_links_paused`, `free_plan_restricted`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/lock": { "post": { "operationId": "postDriveNodesByIdLock", "tags": [ "drive" ], "summary": "Lock a file for editing", "description": "Others' saves are refused (`locked`) until it's unlocked or `minutes` pass (60 by default, up to a day). Locking it again extends your lock; someone else's lock answers `locked`.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minutes": { "minimum": 1, "maximum": 1440, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 1440, "type": "integer" } ], "description": "1–1,440." }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your sync client, if a computer locked it." } } } } } }, "responses": { "200": { "description": "Lock a file for editing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveLockResult" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `locked`, `not_a_file`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveNodesByIdLock", "tags": [ "drive" ], "summary": "Unlock a file", "description": "Whoever locked it, or the space's owner (a team's admins).", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unlock a file", "content": { "application/json": { "schema": { "type": "object", "required": [ "unlocked" ], "properties": { "unlocked": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/parts": { "get": { "operationId": "getDriveNodesByIdParts", "tags": [ "drive" ], "summary": "A version's part hashes", "description": "The BLAKE3 hash of each part of a file's version (its current one unless `version_id`), at the part size it was stored with: compare a new version's parts with these and upload only the changed ones (`parts` on POST /v1/drive/uploads). Known once SendFlo has checked the stored bytes, for files of two parts or more; `parts_not_ready` until then — send the whole file.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } }, { "name": "version_id", "in": "query", "required": false, "description": "A version of the file (the current one by default).", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "A version's part hashes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveParts" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `no_version`, `parts_not_ready`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/peers": { "post": { "operationId": "postDriveNodesByIdPeers", "tags": [ "drive" ], "summary": "Nearby computers that hold a file", "description": "For a sync client about to download a file: the computers on its network (the same public address) whose person may open it, each with where it listens and a key only that computer and this one can make. GET `http://:/dp/?a=&e=&p=` answers the file in AES-256-GCM frames under the key; check the whole file's BLAKE3 against `hash` before using it. Empty when none is nearby, the version isn't checked yet, or the team turned it off (`off`).", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "maxLength": 20, "type": "string", "description": "This computer's sync-client id (POST /v1/drive/clients): the key binds it." }, "version_id": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ], "description": "The version wanted (the current one by default)." } } } } } }, "responses": { "200": { "description": "Nearby computers that hold a file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrivePeers" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `no_client`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/people": { "get": { "operationId": "getDriveNodesByIdPeople", "tags": [ "drive" ], "summary": "List who can open a file", "description": "Its owner and everyone its shares reach (people, and the members of the groups and teams they name — 200 at most): whom you can @mention or give a task.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List who can open a file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrivePeople" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/restore": { "post": { "operationId": "postDriveNodesByIdRestore", "tags": [ "drive" ], "summary": "Restore from the trash", "description": "To its folder — or the top folder if that is gone — with everything that was in it; numbered when the name is taken.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The trashed item's id (as listed by GET /v1/drive/trash).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Restore from the trash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveRestored" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `not_in_trash`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/shares": { "get": { "operationId": "getDriveNodesByIdShares", "tags": [ "drive" ], "summary": "List who has access", "description": "The owner and every share that reaches a file or folder: its own, and those on folders above (`inherited_from`). Someone it's shared with sees the shares from their shared folder down. `roles` lists the roles with their one-line descriptions.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List who has access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveShares" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postDriveNodesByIdShares", "tags": [ "drive" ], "summary": "Share a file or folder", "description": "Gives each of `people` the `role` (an existing share is changed to it): `previewer` sees and previews, no download; `viewer` also downloads; `uploader` also adds files and folders; `editor` also changes, renames, moves and deletes; `co_owner` also shares. A share on a folder reaches everything in it. A person is `{kind: \"email\", email}` (an address with no account gets an email and the share becomes theirs when they sign in with it) or `{kind: \"user\", id}`; a team group `{kind: \"group\", id}` and the whole team `{kind: \"team\", id}` must be your team's. The owner and co-owners share; the top of My files can't be shared.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "people", "role" ], "properties": { "people": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "email": { "maxLength": 320, "type": "string" } } }, "description": "1–50 people, groups or teams." }, "role": { "type": "string", "description": "previewer, viewer, uploader, editor or co_owner." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When it ends (optional; in the future)." }, "message": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "A note for them (500 characters)." } } } } } }, "responses": { "200": { "description": "Share a file or folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveShareList" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `read_only`, `share_root`, `bad_role`, `bad_email`, `bad_person`, `bad_group`, `bad_team`, `bad_expiry`, `bad_people`, `self`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/star": { "put": { "operationId": "putDriveNodesByIdStar", "tags": [ "drive" ], "summary": "Star a file or folder", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Star a file or folder", "content": { "application/json": { "schema": { "type": "object", "required": [ "starred" ], "properties": { "starred": { "const": true, "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveNodesByIdStar", "tags": [ "drive" ], "summary": "Unstar a file or folder", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's or folder's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unstar a file or folder", "content": { "application/json": { "schema": { "type": "object", "required": [ "starred" ], "properties": { "starred": { "const": false, "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/text-in-image": { "get": { "operationId": "getDriveNodesByIdTextInImage", "tags": [ "drive" ], "summary": "What text in images made of a file", "description": "The line a file's Details shows for a picture or a scanned PDF on a Drive with text in images: `read`, `partly_read` (some words may be missing), `unreadable` (lines of text no model reads yet, usually a language not supported yet), `damaged` (damaged, or too small or too large to read), `no_text`, `not_read_yet` or `off` (turned off in Preferences). `null` when it doesn't apply: not a picture or a scan, a private space, or a plan without text in images. Never the text itself.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "What text in images made of a file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveTextInImage" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/versions": { "get": { "operationId": "getDriveNodesByIdVersions", "tags": [ "drive" ], "summary": "List a file's versions", "description": "Newest first; the current one is marked. Earlier versions are kept the plan's version days (`purge_after`).", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List a file's versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveVersions" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/versions/{vid}": { "delete": { "operationId": "deleteDriveNodesByIdVersionsByVid", "tags": [ "drive" ], "summary": "Delete an earlier version", "description": "For good. The current version can't be deleted (`current_version`): restore another first, or trash the file. Not for apps and agents (`agent_no_purge`).", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } }, { "name": "vid", "in": "path", "required": true, "description": "The version's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete an earlier version", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "const": true, "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `no_version`, `current_version`, `agent_no_purge`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/nodes/{id}/versions/{vid}/restore": { "post": { "operationId": "postDriveNodesByIdVersionsByVidRestore", "tags": [ "drive" ], "summary": "Restore an earlier version", "description": "Its content becomes the current version — as a new version, so nothing is lost.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file's id.", "schema": { "type": "string" } }, { "name": "vid", "in": "path", "required": true, "description": "The version's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Restore an earlier version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveNodeResult" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `no_version`, `drive_full`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/notes": { "post": { "operationId": "postDriveNotes", "tags": [ "drive" ], "summary": "Make a note", "description": "A new, empty note in a folder: a Markdown file (`Untitled note.md`, or `name` with `.md` added; a number is added when the name is taken). It's a file like any other — versions, sharing, sync — that people edit together, live.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The folder (your Drive's top when absent)." }, "name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "The note's name." } } } } } }, "responses": { "200": { "description": "Make a note", "content": { "application/json": { "schema": { "type": "object", "required": [ "note" ], "properties": { "note": { "$ref": "#/components/schemas/DriveNote" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `drive_full`, `read_only`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/notes/{id}": { "get": { "operationId": "getDriveNotesById", "tags": [ "drive" ], "summary": "Open a note", "description": "Its text, and for live editing its Yjs state (`state`, base64, one Y.Text named `t`), the `epoch` and the last update's `seq`; who else is in it (`presence`); whether you may edit it. Any `.md` file opens as a note.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The note's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Open a note", "content": { "application/json": { "schema": { "type": "object", "required": [ "note", "epoch", "state", "seq", "saved", "text", "presence", "you", "can_edit" ], "properties": { "note": { "$ref": "#/components/schemas/DriveNote" }, "epoch": { "type": "string" }, "state": { "type": "string" }, "seq": { "type": "string" }, "saved": { "description": "The last `seq` already saved as a version.", "type": "string" }, "text": { "type": "string" }, "presence": { "type": "array", "items": { "$ref": "#/components/schemas/DriveNotePresence" } }, "you": { "pattern": "^[0-9]+$", "type": "string" }, "can_edit": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `not_a_note`, `note_too_large`, `note_unreadable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "putDriveNotesById", "tags": [ "drive" ], "summary": "Set a note's text", "description": "The whole text, from an agent or a script: merged into the live note as one edit (people editing it see it at once) and saved as a new version now.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The note's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "maxLength": 1100000, "type": "string", "description": "The note's Markdown (up to 1 MB)." } } } } } }, "responses": { "200": { "description": "Set a note's text", "content": { "application/json": { "schema": { "type": "object", "required": [ "note" ], "properties": { "note": { "$ref": "#/components/schemas/DriveNote" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `not_a_note`, `note_too_large`, `note_saving`, `read_only`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/notes/{id}/presence": { "post": { "operationId": "postDriveNotesByIdPresence", "tags": [ "drive" ], "summary": "Say where you are in a note", "description": "Your cursor (no edit), or `leave: true` when you close it. Presence lasts 30 seconds unless renewed.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The note's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client" ], "properties": { "client": { "minLength": 4, "maxLength": 40, "pattern": "^[A-Za-z0-9_-]+$", "type": "string", "description": "Your client's id." }, "anchor": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "description": "Your selection's anchor." }, "head": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "description": "Your selection's head." }, "leave": { "type": "boolean", "description": "You closed the note." } } } } } }, "responses": { "200": { "description": "Say where you are in a note", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `not_a_note`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/notes/{id}/updates": { "get": { "operationId": "getDriveNotesByIdUpdates", "tags": [ "drive" ], "summary": "A note's edits since yours", "description": "Live editing: the Yjs updates after `since` (base64), and who's in the note — or, when a save already folded what you missed, the whole `state`. `note_reloaded` (409) when a version from elsewhere arrived: open the note again.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The note's id.", "schema": { "type": "string" } }, { "name": "epoch", "in": "query", "required": true, "description": "The epoch the note opened with.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "The last `seq` you have.", "schema": { "pattern": "^[0-9]+-[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "A note's edits since yours", "content": { "application/json": { "schema": { "type": "object", "required": [ "epoch", "seq", "saved", "updates", "presence" ], "properties": { "epoch": { "type": "string" }, "seq": { "type": "string" }, "saved": { "description": "The last `seq` already saved as a version.", "type": "string" }, "updates": { "type": "array", "items": { "type": "object", "required": [ "seq", "client", "update" ], "properties": { "seq": { "type": "string" }, "client": { "type": "string" }, "update": { "type": "string" } } } }, "presence": { "type": "array", "items": { "$ref": "#/components/schemas/DriveNotePresence" } }, "state": { "description": "When you're behind the last save: the note's whole state (apply it; it holds every edit you missed).", "type": "string" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `not_a_note`, `note_reloaded`, `bad_epoch`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postDriveNotesByIdUpdates", "tags": [ "drive" ], "summary": "Send an edit to a note", "description": "One Yjs update (base64) from your client, and where your cursor is (Yjs relative positions, base64). It's saved as a new version once nobody has typed for a few seconds (at most a minute after the first unsaved edit), naming everyone who edited.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The note's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "epoch", "client", "update" ], "properties": { "epoch": { "maxLength": 16, "type": "string", "description": "The note's epoch." }, "client": { "minLength": 4, "maxLength": 40, "pattern": "^[A-Za-z0-9_-]+$", "type": "string", "description": "Your client's id (4–40 letters, digits, - or _)." }, "update": { "maxLength": 400000, "type": "string", "description": "The Yjs update, base64." }, "anchor": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "description": "Your selection's anchor." }, "head": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "description": "Your selection's head." } } } } } }, "responses": { "200": { "description": "Send an edit to a note", "content": { "application/json": { "schema": { "type": "object", "required": [ "seq" ], "properties": { "seq": { "type": "string" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `not_a_note`, `note_reloaded`, `bad_update`, `update_too_large`, `note_too_large`, `read_only`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/recent": { "get": { "operationId": "getDriveRecent", "tags": [ "drive" ], "summary": "List recently changed files", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1–500 (200 by default).", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "List recently changed files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveListing" } } } }, "default": { "description": "An error: `no_drive`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/search": { "get": { "operationId": "getDriveSearch", "tags": [ "drive" ], "summary": "Search your Drive", "description": "Files and folders by name across everything you can open in Drive — My files, the team spaces you're in and what is shared with you — best first (typos forgiven), 25 a page. Each result carries the folders above it from the top you can see (never above a folder shared with you), its space, and your role. An end-to-end space's files are found by type, size and date, never by name or contents. `in` limits it to a folder's subtree; `trashed=1` searches your trash (and the team trash you manage). `contents=1` also searches the words inside files where the Drive plan includes it (Drive 2 TB and up, every Team Drive plan): names and contents come back in one list, best first, each item saying how it matched, and a file found by its text carries the words around the match.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search words (200 characters at most).", "schema": { "minLength": 1, "maxLength": 200, "type": "string" } }, { "name": "in", "in": "query", "required": false, "description": "A folder: search only inside it.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "trashed", "in": "query", "required": false, "description": "`1`: search the trash instead.", "schema": { "const": "1", "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "`file` or `folder` only.", "schema": { "anyOf": [ { "const": "file", "type": "string" }, { "const": "folder", "type": "string" } ] } }, { "name": "page", "in": "query", "required": false, "description": "The page of results, 1–8.", "schema": { "pattern": "^[0-9]{1,2}$", "type": "string" } }, { "name": "contents", "in": "query", "required": false, "description": "`1`: search inside files too (never the trash or folders). `0` (the default): names only.", "schema": { "anyOf": [ { "const": "0", "type": "string" }, { "const": "1", "type": "string" } ] } } ], "responses": { "200": { "description": "Search your Drive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSearch" } } } }, "default": { "description": "An error: `invalid_query`, `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/share-targets": { "get": { "operationId": "getDriveShareTargets", "tags": [ "drive" ], "summary": "List the teams and groups you can share with", "description": "Each team you're on (share with `{kind: \"team\", id}`) and its groups (`{kind: \"group\", id}`), with their sizes.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "List the teams and groups you can share with", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveShareTargets" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/shared": { "get": { "operationId": "getDriveShared", "tags": [ "drive" ], "summary": "List what's shared with you", "description": "Files and folders other people share with you — with you, your address, a group you're in or your team — newest first, each with its owner and your role. A share inside a folder that's also shared with you is reached from that folder. Needs no Drive plan. `count=1` answers `{count}` only (how many shares name you).", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "count", "in": "query", "required": false, "description": "`1`: only how many.", "schema": { "const": "1", "type": "string" } } ], "responses": { "200": { "description": "List what's shared with you", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSharedWithMe" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/shares/{id}": { "patch": { "operationId": "patchDriveSharesById", "tags": [ "drive" ], "summary": "Change a share", "description": "Its `role`, or when it ends (`expires_at`; null: never). The owner and co-owners.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The share's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "previewer, viewer, uploader, editor or co_owner." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When it ends, or null." } } } } } }, "responses": { "200": { "description": "Change a share", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_share`, `bad_role`, `bad_expiry`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveSharesById", "tags": [ "drive" ], "summary": "Remove a share", "description": "The owner and co-owners remove anyone's; the person a share names may leave it (`left: true`). Removing what's already gone answers `removed: false`.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The share's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Remove a share", "content": { "application/json": { "schema": { "type": "object", "required": [ "removed" ], "properties": { "removed": { "type": "boolean" }, "left": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/spaces": { "get": { "operationId": "getDriveSpaces", "tags": [ "drive" ], "summary": "List your team spaces", "description": "The team spaces you reach — every space of a team you own or administer, and those shared with you — with your role, the team and how many shares it has; and the teams whose Drive plan has team spaces, with whether you may make one there.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "List your team spaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveTeamSpaces" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postDriveSpaces", "tags": [ "drive" ], "summary": "Make a team space", "description": "A space owned by the team: its files stay with the team when someone leaves, and count against the team's Drive pool. The team's policy says who may make one (its owner and admins by default); its maker gets a co-owner share on it.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "team_id", "name" ], "properties": { "team_id": { "type": "string", "description": "The team (subscription) id." }, "name": { "maxLength": 200, "type": "string", "description": "Its name (unique in the team)." }, "private": { "type": "object", "required": [ "public_key", "seals" ], "properties": { "public_key": { "maxLength": 2048, "type": "string" }, "seals": { "maxItems": 200, "type": "array", "items": { "type": "object", "required": [ "user_id", "identity_version", "sealed" ], "properties": { "user_id": { "type": "string" }, "identity_version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "sealed": { "maxLength": 2048, "type": "string" } } } } }, "description": "Make it a private space (end-to-end; Team Drive Enterprise): `{ public_key, seals }` — the space key's public half and its seed sealed to you. Names and files are then sealed on the devices of the people it's shared with; needs encryption set up (Settings › Encryption)." } } } } } }, "responses": { "200": { "description": "Make a team space", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSpaceResult" } } } }, "default": { "description": "An error: `not_on_team`, `no_team_drive`, `space_policy`, `name_taken`, `bad_name`, `plan_required`, `encryption_setup_required`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/spaces/{id}": { "patch": { "operationId": "patchDriveSpacesById", "tags": [ "drive" ], "summary": "Rename a team space", "description": "Co-owners and the team's owner and admins.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The space's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "maxLength": 200, "type": "string", "description": "Its new name." } } } } } }, "responses": { "200": { "description": "Rename a team space", "content": { "application/json": { "schema": { "type": "object", "required": [ "space" ], "properties": { "space": { "$ref": "#/components/schemas/DriveSpace" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_space`, `bad_name`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveSpacesById", "tags": [ "drive" ], "summary": "Archive a team space", "description": "The team's owner and admins.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The space's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archive a team space", "content": { "application/json": { "schema": { "type": "object", "required": [ "archived" ], "properties": { "archived": { "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_space`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/spaces/{id}/changes": { "get": { "operationId": "getDriveSpacesByIdChanges", "tags": [ "drive" ], "summary": "List a space's changes since a point", "description": "The space's change journal after `since`, each change with the node as it is now (`node: null` — trashed or deleted for good: remove it). Apply them in order; `more` says there are more.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The space's id.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "The last `seq` you applied.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1–5,000 (1,000 by default).", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "List a space's changes since a point", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSpaceChanges" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/spaces/{id}/snapshot": { "get": { "operationId": "getDriveSpacesByIdSnapshot", "tags": [ "drive" ], "summary": "List a space for a first sync", "description": "Every live file and folder of the space, a page at a time in id order (`next` → `after`). Take `seq` from the first page and then read GET …/changes from it: changes made while you listed come again there.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The space's id.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "The last node id you have (0: from the start).", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1–5,000 (1,000 by default).", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "List a space for a first sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSnapshot" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/starred": { "get": { "operationId": "getDriveStarred", "tags": [ "drive" ], "summary": "List starred files and folders", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "List starred files and folders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveListing" } } } }, "default": { "description": "An error: `no_drive`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/sync/roots": { "get": { "operationId": "getDriveSyncRoots", "tags": [ "drive" ], "summary": "List the spaces a computer syncs", "description": "My files, and every team space whose top folder the caller can reach — with their role there (`read_only`: a viewer's placeholders can't be changed) and each space's change counter. A sync client lists each with GET …/snapshot, then follows GET …/changes from the snapshot's `seq`.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "List the spaces a computer syncs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSyncRoots" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/tasks": { "get": { "operationId": "getDriveTasks", "tags": [ "drive" ], "summary": "List your open tasks", "description": "Tasks given to you on Drive files, due first. `count=1` answers `{count}` only.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "count", "in": "query", "required": false, "description": "`1`: only how many.", "schema": { "const": "1", "type": "string" } } ], "responses": { "200": { "description": "List your open tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveTasks" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/tasks/{id}": { "patch": { "operationId": "patchDriveTasksById", "tags": [ "drive" ], "summary": "Change a task", "description": "Mark it `done` (or `open` again) or change when it's due — its assignee, its maker or an editor.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "open or done." }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When it's due, or null." } } } } } }, "responses": { "200": { "description": "Change a task", "content": { "application/json": { "schema": { "type": "object", "required": [ "task" ], "properties": { "task": { "type": "object", "required": [ "id", "status", "due_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "done", "type": "string" } ] }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `drive_role`, `no_task`, `not_yours`, `bad_status`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/teams/{id}/conflicts": { "get": { "operationId": "getDriveTeamsByIdConflicts", "tags": [ "drive" ], "summary": "List a team's open sync conflicts", "description": "The conflict center: every open conflict in the team's spaces. The team's owner and admins.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The team plan's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List a team's open sync conflicts", "content": { "application/json": { "schema": { "type": "object", "required": [ "conflicts" ], "properties": { "conflicts": { "type": "array", "items": { "$ref": "#/components/schemas/DriveConflict" } } } } } } }, "default": { "description": "An error: `team_admin`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/teams/{id}/conflicts/resolve": { "post": { "operationId": "postDriveTeamsByIdConflictsResolve", "tags": [ "drive" ], "summary": "Resolve a team's conflicts by a rule", "description": "`newest`: whichever of the file and the copy was saved last; `file`: the file; `both`: keep both. Every open conflict of the team's spaces, or those in `ids`.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The team plan's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rule" ], "properties": { "rule": { "maxLength": 8, "type": "string", "description": "`newest`, `file` or `both`." }, "ids": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Conflict ids (all when absent)." } } } } } }, "responses": { "200": { "description": "Resolve a team's conflicts by a rule", "content": { "application/json": { "schema": { "type": "object", "required": [ "resolved", "skipped" ], "properties": { "resolved": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "skipped": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "default": { "description": "An error: `team_admin`, `bad_rule`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/teams/{id}/policy": { "get": { "operationId": "getDriveTeamsByIdPolicy", "tags": [ "drive" ], "summary": "Get a team's Drive policy", "description": "Who may make team spaces (`admins`, `managers`, `members`) and whether spaces may be shared outside the team (`allow`, `off` — Team Drive Pro and up). The team's owner and admins.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The team (subscription) id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a team's Drive policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveTeamPolicy" } } } }, "default": { "description": "An error: `team_admin`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "putDriveTeamsByIdPolicy", "tags": [ "drive" ], "summary": "Change a team's Drive policy", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The team (subscription) id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "create": { "type": "string", "description": "admins, managers or members." }, "outside": { "type": "string", "description": "allow or off." }, "peers": { "type": "string", "description": "on (the default) or off: the team's computers on one network fetch its spaces' files from each other." }, "automations": { "type": "string", "description": "Who sets up folder automations in the team's spaces: `admins` (the owner and admins, the default) or `members` (everyone who can edit the folder)." } } } } } }, "responses": { "200": { "description": "Change a team's Drive policy", "content": { "application/json": { "schema": { "type": "object", "required": [ "policy" ], "properties": { "policy": { "type": "object", "required": [ "create", "outside", "peers" ], "properties": { "create": { "anyOf": [ { "const": "admins", "type": "string" }, { "const": "managers", "type": "string" }, { "const": "members", "type": "string" } ] }, "outside": { "anyOf": [ { "const": "allow", "type": "string" }, { "const": "off", "type": "string" } ] }, "peers": { "anyOf": [ { "const": "on", "type": "string" }, { "const": "off", "type": "string" } ] } } } } } } } }, "default": { "description": "An error: `team_admin`, `bad_policy`, `plan_feature`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/trash": { "get": { "operationId": "getDriveTrash", "tags": [ "drive" ], "summary": "List the trash", "description": "One row per trashed item (a trashed folder is one row; `inside` says how much it holds), newest first.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "List the trash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveTrash" } } } }, "default": { "description": "An error: `no_drive`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDriveTrash", "tags": [ "drive" ], "summary": "Empty the trash", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "responses": { "200": { "description": "Empty the trash", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "default": { "description": "An error: `no_drive`, `agent_no_purge`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/trash/{id}": { "delete": { "operationId": "deleteDriveTrashById", "tags": [ "drive" ], "summary": "Delete a trashed item for good", "description": "With everything in it and every version. It can't be brought back. Not for apps and agents (`agent_no_purge`): deleting for good is the person's own act.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The trashed item's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete a trashed item for good", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "description": "Items deleted.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Items deleted.", "type": "integer" } ] } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `not_in_trash`, `agent_no_purge`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/uploads": { "post": { "operationId": "postDriveUploads", "tags": [ "drive" ], "summary": "Start an upload", "description": "Upload a file into `parent_id` (the top folder when absent): this answers `part_urls`; PUT each part's bytes (`part_size` each, the last one the rest) to its URL, then POST …/complete. The URLs live an hour — ask for more with POST …/parts. Send `hash` (BLAKE3 of the whole file, hex) and content already in My files needs no upload at all: the answer is `state: done` with the file. The hash is only a hint: SendFlo computes it from the stored bytes and uses its own. A name already there: `rename` (the default, \"name (2)\"), `replace` (a new version of that file) or `fail`. `node_id` adds a version to that file. Up to 5 TB a file; `drive_full` past the plan's room.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "size" ], "properties": { "parent_id": { "type": "string", "description": "The folder." }, "name": { "maxLength": 1024, "type": "string", "description": "The file's name." }, "size": { "minimum": 0, "type": "number", "description": "Bytes." }, "mime": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Its media type." }, "hash": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "BLAKE3 of the content (64 hex characters), optional." }, "on_conflict": { "type": "string", "description": "`rename` (the default), `replace` or `fail`." }, "node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A file to add a version to." }, "source": { "type": "string", "description": "`api` (the default for keys), `desktop` or `phone`." }, "modified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the content last changed on the device." }, "base_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "With `node_id`: the version this save started from. If the file has a newer one by the time the upload finishes, nothing is overwritten: the content becomes a conflict copy beside it (`conflict_of` in the answer)." }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A sync client's id (POST /v1/drive/clients): a conflict copy is named after that computer." }, "parts": { "type": "object", "required": [ "part_size", "hashes" ], "properties": { "part_size": { "minimum": 5242880, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 5242880, "type": "integer" } ] }, "hashes": { "maxItems": 10000, "type": "array", "items": { "maxLength": 64, "type": "string" } } }, "description": "With `node_id`: send only what changed. `part_size` is the base version's (GET /v1/drive/nodes/:id/parts), `hashes` the new file's BLAKE3 of each part at that size. Parts the base version's object holds unchanged are copied by SendFlo; the answer's `upload_parts` lists the ones to send." }, "name_key": { "maxLength": 64, "type": "string", "description": "In a private space (end-to-end): the name's index (64 hex) your device computed, with the sealed `name`." }, "sealed": { "type": "object", "required": [ "space_key_id", "sealed_key" ], "properties": { "space_key_id": { "maxLength": 24, "type": "string" }, "sealed_key": { "maxLength": 4096, "type": "string" } }, "description": "In a private space: `{ space_key_id, sealed_key }` — the space key's current version and the file's key sealed to it. The bytes you upload are the sealed (SFE2) file; a name already there is refused (`fail`), never numbered." } } } } } }, "responses": { "200": { "description": "Start an upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveUploadStart" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `no_folder`, `name_taken`, `bad_name`, `bad_size`, `bad_hash`, `bad_parts`, `too_large`, `drive_full`, `locked`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/uploads/{id}": { "delete": { "operationId": "deleteDriveUploadsById", "tags": [ "drive" ], "summary": "Cancel an upload", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The upload's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel an upload", "content": { "application/json": { "schema": { "type": "object", "required": [ "aborted" ], "properties": { "aborted": { "const": true, "type": "boolean" } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/uploads/{id}/complete": { "post": { "operationId": "postDriveUploadsByIdComplete", "tags": [ "drive" ], "summary": "Finish an upload", "description": "SendFlo checks every part the storage holds against the file's size and makes the file. Safe to call again: a repeated call answers the same file. `parts_missing` until every part has arrived; `size_mismatch` when a part is the wrong size (the upload is cancelled — start again). A save from a version that's no longer current answers its conflict copy, with `conflict_of`; `locked` when someone else locked the file meanwhile.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The upload's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Finish an upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveUploadDone" } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `read_only`, `no_upload`, `upload_closed`, `parts_missing`, `size_mismatch`, `name_taken`, `no_folder`, `locked`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/uploads/{id}/parts": { "post": { "operationId": "postDriveUploadsByIdParts", "tags": [ "drive" ], "summary": "Get more part URLs", "description": "Fresh URLs for the parts named (1-based, 500 at most a call): for the parts past the first 64, a resumed upload, or URLs that expired.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The upload's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parts" ], "properties": { "parts": { "maxItems": 500, "type": "array", "items": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, "description": "Part numbers." } } } } } }, "responses": { "200": { "description": "Get more part URLs", "content": { "application/json": { "schema": { "type": "object", "required": [ "part_urls" ], "properties": { "part_urls": { "type": "array", "items": { "type": "string" } } } } } } }, "default": { "description": "An error: `no_drive`, `not_found`, `no_upload`, `upload_closed`, `bad_parts`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/usage": { "get": { "operationId": "getDriveUsage", "tags": [ "drive" ], "summary": "Get your Drive usage", "description": "What the plan counts (current versions of files not in the trash), and what earlier versions take apart from it.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "Get your Drive usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveUsage" } } } }, "default": { "description": "An error: `no_drive`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/e2e/devices": { "post": { "operationId": "postE2eDevices", "tags": [ "encryption" ], "summary": "Ask to become one of your encryption devices", "description": "The machine makes its own X-Wing key pair and sends the public half; the device waits (`pending`) until another of the person's devices approves it after both show the same six digits (`code`), or it unlocks itself with the recovery key. The person's other devices are told. A key asks as platform `cli` (422 `platform_cli` otherwise). At most five devices wait at once.", "security": [ { "apiKey": [ "encryption.devices" ] } ], "x-scope": "encryption.devices", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "platform", "public_key" ], "properties": { "label": { "minLength": 1, "maxLength": 80, "type": "string", "description": "What the person sees in Settings → Encryption (\"CLI on build-box\")." }, "platform": { "anyOf": [ { "const": "web", "type": "string" }, { "const": "desktop", "type": "string" }, { "const": "ios", "type": "string" }, { "const": "android", "type": "string" }, { "const": "cli", "type": "string" } ], "description": "`cli` for the SDK and the CLI." }, "public_key": { "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 2000, "type": "string", "description": "The device's X-Wing public key, base64url (1216 bytes)." } } } } } }, "responses": { "201": { "description": "Ask to become one of your encryption devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/E2eDevice" } } } }, "default": { "description": "An error: `no_keys`, `invalid_key`, `platform_cli`, `too_many_pending`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "getE2eDevices", "tags": [ "encryption" ], "summary": "List your encryption devices", "description": "Every device of the person, waiting, unlocked or removed — poll it to see when yours is approved.", "security": [ { "apiKey": [ "encryption.devices" ] } ], "x-scope": "encryption.devices", "responses": { "200": { "description": "List your encryption devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/E2eDevices" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/e2e/devices/{id}": { "delete": { "operationId": "deleteE2eDevicesById", "tags": [ "encryption" ], "summary": "Forget a device this key enrolled", "description": "Removes the device and its sealed copy. A key removes only a device it enrolled; revoking the key removes them too. A device that was unlocked kept a copy of the identity key, so rotating keys in the app afterwards is recommended (`rotate_recommended`).", "security": [ { "apiKey": [ "encryption.devices" ] } ], "x-scope": "encryption.devices", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The device's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Forget a device this key enrolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/E2eDeviceRemoved" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/e2e/devices/{id}/unlock": { "post": { "operationId": "postE2eDevicesByIdUnlock", "tags": [ "encryption" ], "summary": "Unlock a waiting device with the recovery key", "description": "The device opened the recovery seal (`GET /v1/e2e/seals?kind=recovery`) with the person's recovery key and sends the identity seed sealed to its own key. A key unlocks only a device it enrolled, and only with the recovery key (422 `recovery_only`; passkeys are for browsers).", "security": [ { "apiKey": [ "encryption.devices" ] } ], "x-scope": "encryption.devices", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The waiting device's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "via", "sealed" ], "properties": { "via": { "anyOf": [ { "const": "recovery", "type": "string" }, { "const": "passkey", "type": "string" } ], "description": "`recovery`." }, "credential": { "maxLength": 128, "type": "string", "description": "Unused for `recovery`." }, "sealed": { "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 2000, "type": "string", "description": "The current identity seed sealed to the device's own key (HPKE, `SEAL_INFO.identity`)." } } } } } }, "responses": { "200": { "description": "Unlock a waiting device with the recovery key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/E2eDevice" } } } }, "default": { "description": "An error: `not_found`, `invalid_seal`, `recovery_only`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/e2e/events": { "get": { "operationId": "getE2eEvents", "tags": [ "encryption" ], "summary": "Your key-event chain", "description": "Every change to the person's keys, oldest first, each hash covering the one before (SHA-256). Recompute it on the device to check nothing was changed or left out; the SDK's `verifyKeyChain` does.", "security": [ { "apiKey": [ "encryption.devices" ] } ], "x-scope": "encryption.devices", "responses": { "200": { "description": "Your key-event chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/E2eKeyEvents" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/e2e/keys": { "get": { "operationId": "getE2eKeys", "tags": [ "encryption" ], "summary": "Your encryption keys and devices", "description": "The person's identity key (null until they set up encryption in the app), their devices, whether a recovery key is set, the passkeys that unlock, and the head of the key-event chain.", "security": [ { "apiKey": [ "encryption.devices" ] } ], "x-scope": "encryption.devices", "responses": { "200": { "description": "Your encryption keys and devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/E2eKeys" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/e2e/seals": { "get": { "operationId": "getE2eSeals", "tags": [ "encryption" ], "summary": "The sealed copies a device needs", "description": "`?device=`: the identity seeds sealed to that unlocked device (a key reads only a device it enrolled), plus the history — each older version sealed to the next, so the newest seed opens every older one. `?kind=recovery`: the copy sealed to the recovery key, to unlock a waiting device. Opening them happens on the device.", "security": [ { "apiKey": [ "encryption.devices" ] } ], "x-scope": "encryption.devices", "parameters": [ { "name": "device", "in": "query", "required": false, "description": "An unlocked device's id.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "`recovery` (a key can't read passkey copies).", "schema": { "anyOf": [ { "const": "recovery", "type": "string" }, { "const": "passkey", "type": "string" } ] } }, { "name": "credential", "in": "query", "required": false, "description": "With `kind=passkey`, from a browser only.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The sealed copies a device needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/E2eSeals" } } } }, "default": { "description": "An error: `not_found`, `invalid_query`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/e2e/team-seals": { "get": { "operationId": "getE2eTeamSeals", "tags": [ "encryption" ], "summary": "The team keys sealed to you", "description": "Each team key the person holds (a team inbox's key, or the team's recovery key for its owner and admins), sealed to their identity key, with the key's public half — what a device needs to open a team inbox's encrypted files or a recovery copy. A key the person no longer holds has no copy.", "security": [ { "apiKey": [ "encryption.devices" ] } ], "x-scope": "encryption.devices", "responses": { "200": { "description": "The team keys sealed to you", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/E2eTeamSeals" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/events": { "get": { "operationId": "getEvents", "tags": [ "webhooks" ], "summary": "List events", "description": "Every event of the last 30 days, newest first, whether or not an endpoint received it: for polling (Zapier, Make, n8n), catching up after downtime, or a SIEM. Filter by `types` (comma-separated) and `since`; page with `cursor` (the previous page's `next`).", "security": [ { "apiKey": [ "webhooks.read" ] } ], "x-scope": "webhooks.read", "parameters": [ { "name": "types", "in": "query", "required": false, "description": "Event types, comma-separated.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "ISO time.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's `next`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1–100 (50).", "schema": { "minimum": 1, "maximum": 100, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100, "type": "integer" } ] } } ], "responses": { "200": { "description": "List events", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoredEvent" } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "description": "An error: `invalid_since`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/events/{id}": { "get": { "operationId": "getEventsById", "tags": [ "webhooks" ], "summary": "Read one event", "description": "One event of the last 30 days, as it was sent (its `data` is the webhook body's `data`).", "security": [ { "apiKey": [ "webhooks.read" ] } ], "x-scope": "webhooks.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An event's id (the webhook body's `id`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Read one event", "content": { "application/json": { "schema": { "description": "StoredEvent" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/file-requests": { "get": { "operationId": "getFileRequests", "tags": [ "file-requests" ], "summary": "List your file requests and upload pages", "description": "Newest first, 200 at most, every state, the personal upload link included. `limits` gives the plan's allowance of reception links (the personal link doesn't count).", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "responses": { "200": { "description": "List your file requests and upload pages", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "limits" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileRequest" } }, "limits": { "$ref": "#/components/schemas/FileRequestLimits" } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postFileRequests", "tags": [ "file-requests" ], "summary": "Create a file request or upload page", "description": "Creates an upload page at `/u/`. A key of your API & Agents workspace pays 1 credit per request, charged only once the request is created (402 `insufficient_credits` without a balance), and gets the paid features on any plan. Any other key follows its workspace's plan, as in the app (Verified and Only-them access, a custom retention, notification routing, a brand kit and a custom expiry are paid features), and costs no credits. Send an `Idempotency-Key` header (1 to 128 visible ASCII characters) to retry safely: within 24 hours the same key returns the request it created, marked `idempotent-replayed: true`, and is never charged twice. Returns `notify_webhook_secret` once when you set `notify.webhook_url`.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "description": "Your own label, never shown to uploaders (120 characters at most)." }, "prompt": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "The message shown to the uploader (2000 characters at most)." }, "kind": { "anyOf": [ { "const": "request", "type": "string" }, { "const": "reception", "type": "string" } ], "description": "`request` (the default; closes after `max_files`) or `reception` (stays open)." }, "max_files": { "minimum": 1, "maximum": 50, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 50, "type": "integer" } ], "description": "1–50 (1 by default); ignored for `reception`." }, "max_bytes_per_file": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A size limit per file, in bytes; null = none." }, "max_bytes_per_upload": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A size limit for the files someone sends together, in bytes; null = none. Every plan." }, "max_files_per_upload": { "anyOf": [ { "minimum": 1, "maximum": 1000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 1000, "type": "integer" } ] }, { "type": "null" } ], "description": "How many files someone can send together (1–1000); null = the plan's files per transfer." }, "max_total_bytes": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A size limit for everything the page receives, in bytes; null = none. Files the malware scan rejects don't count. When it is reached the page answers 410 `page_full`. Every plan." }, "max_total_uploads": { "anyOf": [ { "minimum": 1, "maximum": 1000000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 1000000, "type": "integer" } ] }, { "type": "null" } ], "description": "How many uploads the page accepts in all (1–1,000,000); null = no limit. Every plan." }, "max_bytes_per_person": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A size limit per verified uploader, in bytes; null = none. Paid plans (403 `paid_required`). Turns `access` to `tracked` on a public page (422 `verified_uploaders_required` if you also ask for `public`): a typed email proves nothing." }, "max_uploads_per_person": { "anyOf": [ { "minimum": 1, "maximum": 100000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100000, "type": "integer" } ] }, { "type": "null" } ], "description": "How many uploads one verified uploader can send (1–100,000); null = no limit. Paid plans; like `max_bytes_per_person`." }, "show_space_left": { "type": "boolean", "description": "Show uploaders how much room the page has left." }, "password": { "anyOf": [ { "minLength": 1, "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "An upload-page password; null = none." }, "notify": { "anyOf": [ { "type": "object", "properties": { "emails": { "maxItems": 5, "type": "array", "items": { "format": "email", "maxLength": 320, "type": "string" } }, "webhook_url": { "maxLength": 2048, "type": "string" } } }, { "type": "null" } ], "description": "Who's told about each upload: `{ emails?: up to 5 addresses, webhook_url?: an https URL that receives signed upload events }`." }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ], "description": "`public`, `tracked` (uploaders verify their email with a code) or `restricted` (verified and on `allowed_emails`)." }, "allowed_emails": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "maxLength": 320, "type": "string" } }, { "type": "null" } ], "description": "Required for `restricted` (100 at most)." }, "retention_days": { "anyOf": [ { "minimum": 1, "maximum": 3650, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 3650, "type": "integer" } ] }, { "type": "null" } ], "description": "How long received files are kept; null = the plan's default." }, "allowed_types": { "anyOf": [ { "maxItems": 40, "type": "array", "items": { "maxLength": 20, "type": "string" } }, { "type": "null" } ], "description": "File categories (image, video, document…) or extensions; empty = any type." }, "reject_flagged": { "type": "boolean", "description": "Delete uploads the malware scan blocks (true by default)." }, "brand_id": { "anyOf": [ { "maxLength": 24, "type": "string" }, { "type": "null" } ], "description": "A brand kit of this workspace; null = the default kit." }, "deliver_to_inbox_id": { "type": "string", "description": "An inbox that also receives the uploads." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the page stops accepting uploads; null = never." }, "questions": { "anyOf": [ { "maxItems": 20, "type": "array", "items": { "type": "object", "required": [ "label", "type" ], "properties": { "id": { "maxLength": 32, "type": "string" }, "label": { "maxLength": 120, "type": "string" }, "type": { "maxLength": 20, "type": "string" }, "required": { "type": "boolean" }, "options": { "maxItems": 40, "type": "array", "items": { "maxLength": 120, "type": "string" } }, "help": { "maxLength": 300, "type": "string" }, "settings": { "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } } } } }, { "type": "null" } ], "description": "Up to 10 questions asked with each upload: short_text, long_text (up to 5,000 characters), email, number, date, multiple_choice (one or several, with Other), opinion_scale, phone, yes_no or consent (always required), each with its `settings`. Questions are paid, except consent, which every plan may ask (403 `paid_required` names the other types on Free). The old names `text` and `select` are read as short_text and multiple_choice; the ids `v`, `name`, `email`, `from`, `from_email`, `password`, `slug`, `embed` and `sf_*` are refused (422 `invalid_questions`)." }, "require_contact": { "type": "boolean", "description": "Uploaders must give their name and email." }, "view_only": { "type": "boolean", "description": "Team seats only (403 `team_required`): received PDFs and images open as previews and the download is refused (403 `view_only`). A team protection policy can require it (403 `policy_locked` when turned off)." }, "member_mark": { "type": "boolean", "description": "Team Pro and Team Enterprise (403 `viewer_mark_plan`): each preview is the member's own copy with their email on it, one marked view each from the team's pool. Implies `view_only`." }, "view_only_other": { "anyOf": [ { "const": "download", "type": "string" }, { "const": "block", "type": "string" }, { "type": "null" } ], "description": "While `view_only`: `download` (the default) keeps other file types downloadable; `block` makes the page accept PDFs and images only (422 `no_viewable_types` when nothing viewable is left)." }, "team_visible": { "type": "boolean", "description": "Team seats only (403 `team_required`): the team's Owner and Admins see the files received through this page in the team's Received view (opening an original still takes a reason and is audited). Off by default." }, "embed_origins": { "anyOf": [ { "maxItems": 40, "type": "array", "items": { "maxLength": 200, "type": "string" } }, { "type": "null" } ], "description": "The sites allowed to frame the script widget: up to 20 origins (`https://example.com`, `https://*.example.com` for subdomains, `http://localhost:3000` while developing). Every widget response then carries `frame-ancestors` with this list, and the widget talks only to these sites. `null` or `[]` = any site. Pro, Team Pro and Team Enterprise (403 `plan_required`); clearing it never needs a plan." }, "widget_share_answers": { "type": "boolean", "description": "The script widget's `all_complete` event, sent to the host page, carries the uploader's answers. Off by default. Pro and up." }, "e2e": { "type": "boolean", "description": "Encrypt uploads end to end: the upload page seals each file and its name in the uploader's browser, and seals the file's key to the page's owner (or its team inbox) and the team's recovery key. SendFlo can't scan, preview or make view-only copies of what arrives. Pro, Team Pro and Team Enterprise (403 `plan_required`); turning it on needs those keys (409 `owner_no_keys`, `inbox_no_key`), and not with `view_only` (422 `e2e_view_only`)." }, "deliver_to": { "pattern": "^\\d{1,20}$", "type": "string", "description": "A team inbox's id: the page is made in that inbox and what arrives is the team's (signed-in members of the inbox only; a key gets 403 `user_credential_required`)." } } } } } }, "responses": { "201": { "description": "Create a file request or upload page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequestWithSecret" } } } }, "default": { "description": "An error: `insufficient_credits`, `paid_required`, `reception_link_limit`, `invalid_webhook`, `allowed_emails_required`, `retention_too_long`, `brand_not_found`, `brand_locked`, `invalid_questions`, `invalid_expiry`, `invalid_idempotency_key`, `idempotency_in_progress`, `team_required`, `viewer_mark_plan`, `policy_locked`, `no_viewable_types`, `invalid_embed_origins`, `plan_required`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/file-requests/{id}": { "get": { "operationId": "getFileRequestsById", "tags": [ "file-requests" ], "summary": "Get a file request", "description": "One file request or upload page of this workspace, with how many files it received.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file request's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a file request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "patchFileRequestsById", "tags": [ "file-requests" ], "summary": "Change a file request's settings", "description": "Changes only the fields you send; the address never changes. Only open requests can be changed (409 `not_open`). Paid features follow your plan, as when creating one (403 `paid_required`). `notify` replaces the whole routing; a new `webhook_url` returns a new `notify_webhook_secret` once.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file request's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "description": "Your own label, never shown to uploaders (120 characters at most)." }, "prompt": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "The message shown to the uploader (2000 characters at most)." }, "kind": { "anyOf": [ { "const": "request", "type": "string" }, { "const": "reception", "type": "string" } ], "description": "`request` (the default; closes after `max_files`) or `reception` (stays open)." }, "max_files": { "minimum": 1, "maximum": 50, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 50, "type": "integer" } ], "description": "1–50 (1 by default); ignored for `reception`." }, "max_bytes_per_file": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A size limit per file, in bytes; null = none." }, "max_bytes_per_upload": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A size limit for the files someone sends together, in bytes; null = none. Every plan." }, "max_files_per_upload": { "anyOf": [ { "minimum": 1, "maximum": 1000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 1000, "type": "integer" } ] }, { "type": "null" } ], "description": "How many files someone can send together (1–1000); null = the plan's files per transfer." }, "max_total_bytes": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A size limit for everything the page receives, in bytes; null = none. Files the malware scan rejects don't count. When it is reached the page answers 410 `page_full`. Every plan." }, "max_total_uploads": { "anyOf": [ { "minimum": 1, "maximum": 1000000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 1000000, "type": "integer" } ] }, { "type": "null" } ], "description": "How many uploads the page accepts in all (1–1,000,000); null = no limit. Every plan." }, "max_bytes_per_person": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A size limit per verified uploader, in bytes; null = none. Paid plans (403 `paid_required`). Turns `access` to `tracked` on a public page (422 `verified_uploaders_required` if you also ask for `public`): a typed email proves nothing." }, "max_uploads_per_person": { "anyOf": [ { "minimum": 1, "maximum": 100000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100000, "type": "integer" } ] }, { "type": "null" } ], "description": "How many uploads one verified uploader can send (1–100,000); null = no limit. Paid plans; like `max_bytes_per_person`." }, "show_space_left": { "type": "boolean", "description": "Show uploaders how much room the page has left." }, "password": { "anyOf": [ { "minLength": 1, "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "An upload-page password; null = none." }, "notify": { "anyOf": [ { "type": "object", "properties": { "emails": { "maxItems": 5, "type": "array", "items": { "format": "email", "maxLength": 320, "type": "string" } }, "webhook_url": { "maxLength": 2048, "type": "string" } } }, { "type": "null" } ], "description": "Who's told about each upload: `{ emails?: up to 5 addresses, webhook_url?: an https URL that receives signed upload events }`." }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ], "description": "`public`, `tracked` (uploaders verify their email with a code) or `restricted` (verified and on `allowed_emails`)." }, "allowed_emails": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "maxLength": 320, "type": "string" } }, { "type": "null" } ], "description": "Required for `restricted` (100 at most)." }, "retention_days": { "anyOf": [ { "minimum": 1, "maximum": 3650, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 3650, "type": "integer" } ] }, { "type": "null" } ], "description": "How long received files are kept; null = the plan's default." }, "allowed_types": { "anyOf": [ { "maxItems": 40, "type": "array", "items": { "maxLength": 20, "type": "string" } }, { "type": "null" } ], "description": "File categories (image, video, document…) or extensions; empty = any type." }, "reject_flagged": { "type": "boolean", "description": "Delete uploads the malware scan blocks (true by default)." }, "brand_id": { "anyOf": [ { "maxLength": 24, "type": "string" }, { "type": "null" } ], "description": "A brand kit of this workspace; null = the default kit." }, "deliver_to_inbox_id": { "type": "string", "description": "An inbox that also receives the uploads." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the page stops accepting uploads; null = never." }, "questions": { "anyOf": [ { "maxItems": 20, "type": "array", "items": { "type": "object", "required": [ "label", "type" ], "properties": { "id": { "maxLength": 32, "type": "string" }, "label": { "maxLength": 120, "type": "string" }, "type": { "maxLength": 20, "type": "string" }, "required": { "type": "boolean" }, "options": { "maxItems": 40, "type": "array", "items": { "maxLength": 120, "type": "string" } }, "help": { "maxLength": 300, "type": "string" }, "settings": { "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } } } } }, { "type": "null" } ], "description": "Up to 10 questions asked with each upload: short_text, long_text (up to 5,000 characters), email, number, date, multiple_choice (one or several, with Other), opinion_scale, phone, yes_no or consent (always required), each with its `settings`. Questions are paid, except consent, which every plan may ask (403 `paid_required` names the other types on Free). The old names `text` and `select` are read as short_text and multiple_choice; the ids `v`, `name`, `email`, `from`, `from_email`, `password`, `slug`, `embed` and `sf_*` are refused (422 `invalid_questions`)." }, "require_contact": { "type": "boolean", "description": "Uploaders must give their name and email." }, "view_only": { "type": "boolean", "description": "Team seats only (403 `team_required`): received PDFs and images open as previews and the download is refused (403 `view_only`). A team protection policy can require it (403 `policy_locked` when turned off)." }, "member_mark": { "type": "boolean", "description": "Team Pro and Team Enterprise (403 `viewer_mark_plan`): each preview is the member's own copy with their email on it, one marked view each from the team's pool. Implies `view_only`." }, "view_only_other": { "anyOf": [ { "const": "download", "type": "string" }, { "const": "block", "type": "string" }, { "type": "null" } ], "description": "While `view_only`: `download` (the default) keeps other file types downloadable; `block` makes the page accept PDFs and images only (422 `no_viewable_types` when nothing viewable is left)." }, "team_visible": { "type": "boolean", "description": "Team seats only (403 `team_required`): the team's Owner and Admins see the files received through this page in the team's Received view (opening an original still takes a reason and is audited). Off by default." }, "embed_origins": { "anyOf": [ { "maxItems": 40, "type": "array", "items": { "maxLength": 200, "type": "string" } }, { "type": "null" } ], "description": "The sites allowed to frame the script widget: up to 20 origins (`https://example.com`, `https://*.example.com` for subdomains, `http://localhost:3000` while developing). Every widget response then carries `frame-ancestors` with this list, and the widget talks only to these sites. `null` or `[]` = any site. Pro, Team Pro and Team Enterprise (403 `plan_required`); clearing it never needs a plan." }, "widget_share_answers": { "type": "boolean", "description": "The script widget's `all_complete` event, sent to the host page, carries the uploader's answers. Off by default. Pro and up." }, "e2e": { "type": "boolean", "description": "Encrypt uploads end to end: the upload page seals each file and its name in the uploader's browser, and seals the file's key to the page's owner (or its team inbox) and the team's recovery key. SendFlo can't scan, preview or make view-only copies of what arrives. Pro, Team Pro and Team Enterprise (403 `plan_required`); turning it on needs those keys (409 `owner_no_keys`, `inbox_no_key`), and not with `view_only` (422 `e2e_view_only`)." } } } } } }, "responses": { "200": { "description": "Change a file request's settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequestWithSecret" } } } }, "default": { "description": "An error: `not_found`, `not_open`, `paid_required`, `invalid_webhook`, `allowed_emails_required`, `retention_too_long`, `brand_not_found`, `brand_locked`, `invalid_questions`, `invalid_expiry`, `team_required`, `viewer_mark_plan`, `policy_locked`, `no_viewable_types`, `invalid_embed_origins`, `plan_required`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/file-requests/{id}/cancel": { "post": { "operationId": "postFileRequestsByIdCancel", "tags": [ "file-requests" ], "summary": "Stop a file request accepting uploads", "description": "Closes it (`cancelled`). Safe to repeat.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file request's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stop a file request accepting uploads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/file-requests/{id}/webhook/deliveries": { "get": { "operationId": "getFileRequestsByIdWebhookDeliveries", "tags": [ "file-requests" ], "summary": "List a link's webhook deliveries", "description": "The link's own webhook (`notify.webhook_url`): every attempt of the last 30 days, newest first — the status your server answered, how long it took, the start of its answer. `attempt` 0 is a Resend. 404 `no_webhook` when the link has none.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file request's id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many (1–200, 50 by default).", "schema": { "minimum": 1, "maximum": 200, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "type": "integer" } ] } } ], "responses": { "200": { "description": "List a link's webhook deliveries", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } }, "default": { "description": "An error: `not_found`, `no_webhook`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/file-requests/{id}/webhook/deliveries/{deliveryId}/resend": { "post": { "operationId": "postFileRequestsByIdWebhookDeliveriesByDeliveryIdResend", "tags": [ "file-requests" ], "summary": "Resend a link's webhook delivery", "description": "Sends the same body again, with the same `webhook-id` (so your server can tell it's the same event), to the link's current webhook address. Queued: answers 202.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file request's id.", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "A delivery from the log.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Resend a link's webhook delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResent" } } } }, "default": { "description": "An error: `not_found`, `no_webhook`, `body_not_kept`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/file-requests/{id}/webhook/resume": { "post": { "operationId": "postFileRequestsByIdWebhookResume", "tags": [ "file-requests" ], "summary": "Resume a link's paused webhook", "description": "A link's webhook pauses after 5 events in a row whose every attempt failed (`notify.webhook_paused_at`); you're told in the app and by email. Fix your server, then resume. Saving the link's `notify` resumes it too.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file request's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resume a link's paused webhook", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "webhook_paused_at", "webhook_failed_events" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "webhook_paused_at": { "type": "null" }, "webhook_failed_events": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "default": { "description": "An error: `not_found`, `no_webhook`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/file-requests/{id}/widget-secret": { "get": { "operationId": "getFileRequestsByIdWidgetSecret", "tags": [ "file-requests" ], "summary": "Show an upload page's widget secret", "description": "The secret your server signs \"verified by your site\" tokens with (the script widget, Pro, Team Pro and Team Enterprise; see /docs/widget). `null` until you issue one with POST.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file request's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Show an upload page's widget secret", "content": { "application/json": { "schema": { "type": "object", "required": [ "secret", "version" ], "properties": { "secret": { "anyOf": [ { "description": "`sfws_…`. Keep it on your server.", "type": "string" }, { "type": "null" } ] }, "version": { "description": "How many times one was issued.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "How many times one was issued.", "type": "integer" } ] } } } } } }, "default": { "description": "An error: `not_found`, `plan_required`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postFileRequestsByIdWidgetSecret", "tags": [ "file-requests" ], "summary": "Issue a new widget secret", "description": "Issues a new secret for \"verified by your site\" tokens; the previous one stops working at once. Pro, Team Pro and Team Enterprise.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file request's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Issue a new widget secret", "content": { "application/json": { "schema": { "type": "object", "required": [ "secret", "version" ], "properties": { "secret": { "type": "string" }, "version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "default": { "description": "An error: `not_found`, `plan_required`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/files": { "get": { "operationId": "getFiles", "tags": [ "files" ], "summary": "List your stored files", "description": "The workspace's newest 100 files, newest first.", "security": [ { "apiKey": [ "files.read" ] } ], "x-scope": "files.read", "responses": { "200": { "description": "List your stored files", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/files/{id}/send-again": { "get": { "operationId": "getFilesByIdSendAgain", "tags": [ "files" ], "summary": "Check how a file can be sent again", "description": "Whether the file can be sent again (and if not, why), its live links, whether a new link reuses the stored bytes (`mode: reuse`, free) or needs a copy billed like an upload (`mode: copy`), and the quota it would use.", "security": [ { "apiKey": [ "files.read" ] } ], "x-scope": "files.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The stored file's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Check how a file can be sent again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAgainPlan" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postFilesByIdSendAgain", "tags": [ "files" ], "summary": "Send a stored file again with a new link", "description": "A new link without uploading again, under the same rules as POST /v1/links (team approval included). `mode: reuse` links the stored bytes (free); `mode: copy` makes a copy billed like an upload (`charged_bytes`), finished in the background (`file.copying`). One at a time per file (409 `busy`). On Free with ads on, it needs an ad credit a key can't get (402 `ad_required`).", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The stored file's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "type": "object", "properties": { "slug": { "minLength": 4, "maxLength": 40, "type": "string" }, "password": { "minLength": 1, "type": "string" }, "expires_at": { "type": "string" }, "max_downloads": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, "note": { "maxLength": 2000, "type": "string" }, "subject": { "maxLength": 200, "type": "string" }, "sealed_meta": { "maxLength": 8192, "type": "string" }, "require_email": { "type": "boolean" }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "allowed_emails": { "maxItems": 50, "type": "array", "items": { "maxLength": 320, "type": "string" } }, "encrypted": { "type": "boolean" }, "e2e_half": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "e2e_half_derivation": { "const": 1, "type": "number" }, "e2e_recovery": { "type": "object", "required": [ "team_key_id", "sealed" ], "properties": { "team_key_id": { "pattern": "^\\d{1,20}$", "type": "string" }, "sealed": { "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 2000, "type": "string" } } }, "kind": { "anyOf": [ { "const": "file", "type": "string" }, { "const": "message", "type": "string" } ] }, "open_once": { "type": "boolean" }, "e2e_stamp": { "type": "boolean" }, "e2e_each": { "type": "boolean" }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "watermark_label": { "maxLength": 60, "type": "string" }, "viewer_mark": { "type": "boolean" }, "allow_guests": { "type": "boolean" }, "guest_downloads": { "type": "boolean" }, "viewers_invite": { "type": "boolean" }, "download_mark": { "type": "boolean" }, "mark_unsupported": { "anyOf": [ { "const": "block", "type": "string" }, { "const": "send", "type": "string" } ] }, "preview_variant": { "anyOf": [ { "const": "720p", "type": "string" }, { "const": "480p", "type": "string" }, { "const": "1080p", "type": "string" } ] }, "bundle": { "type": "boolean" }, "bundle_id": { "maxLength": 32, "type": "string" }, "available_at": { "type": "string" }, "notify_on_download": { "type": "boolean" }, "brand_id": { "maxLength": 24, "type": "string" }, "comments_mode": { "anyOf": [ { "const": "off", "type": "string" }, { "const": "open", "type": "string" }, { "const": "private", "type": "string" } ] }, "ratings_enabled": { "type": "boolean" }, "favorites_enabled": { "type": "boolean" }, "approvals_enabled": { "type": "boolean" }, "restore": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "duration_days": { "minimum": 1, "maximum": 3650, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 3650, "type": "integer" } ] } } } }, "description": "The link's options: any POST /v1/links field except `file_id` (`{}` for the defaults)." }, "target": { "anyOf": [ { "const": "same", "type": "string" }, { "const": "flexible", "type": "string" } ], "description": "A file on included storage: `same` (default) copies it on the same provider with a fixed download limit; `flexible` copies it to unlimited-download storage within the monthly copy allowance (409 `copy_quota_exhausted` past it), editable afterwards. Ignored on other files." }, "ad_nonce": { "maxLength": 64, "type": "string", "description": "For the signed-in app (a Free plan's ad credit)." }, "overage_ad": { "type": "boolean", "description": "For the signed-in app (an ad was watched to go over quota)." }, "overage_ad_nonce": { "maxLength": 64, "type": "string", "description": "For the signed-in app (that ad's credit)." } } } } } }, "responses": { "200": { "description": "Send a stored file again with a new link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAgainResult" } } } }, "default": { "description": "An error: `not_found`, `send_again_unavailable`, `ad_required`, `busy`, `overage_requires_ad`, `storage_quota_exceeded`, `no_flat_target`, `copy_quota_exhausted`, `approval_required`, `awaiting_approval`, `content_blocked`, `policy_forbidden`, `policy_password_required`, `policy_ttl_exceeded`, `free_tier_size`, `file_size_cap`, `transfer_size_cap`, `paid_required`, `delivery_conflict`, `e2e_view_unsupported`, `e2e_view_too_large`, `viewer_mark_not_on_e2e`, `not_found`, `plan_required`, `invalid_schedule`, `slug_invalid`, `slug_taken`, `allowed_emails_required`, `brand_not_found`, `brand_locked`, `file_budget_exceeded`, `viewer_mark_plan`, `viewer_mark_requires_watermark`, `viewer_mark_requires_verified_access`, `guests_require_viewer_mark`, `guests_require_tracked`, `guests_not_on_e2e`, `stamp_requires_encryption`, `stamp_unsupported`, `policy_locked`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/forwards": { "post": { "operationId": "postForwards", "tags": [ "links" ], "summary": "Forward a received link without downloading it", "description": "Copies the link's file into your workspace (billed like an upload; the copy finishes in the background, `file.copying`) and makes a new link to it with the same rules as POST /v1/links. The new link never gives more than the original: it keeps the original's delivery mode unless you ask for a narrower one (422 `delivery_not_allowed` otherwise), and a password-protected original keeps a password (yours in `link.password`, or the original's). On economy storage the forward uses one of the original link's downloads (`source.consumed_download`). The sender sees the forward; your account is named only on links that verify their recipients. On Free with ads on, it needs an ad credit a key can't get (402 `ad_required`); an API & Agents workspace out of credits gets 402 `insufficient_credits`.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "minLength": 4, "maxLength": 40, "type": "string", "description": "The received link's slug (the last part of its URL)." }, "password": { "type": "string", "description": "The link's password, when it has one." }, "email": { "maxLength": 320, "type": "string", "description": "The recipient email, on a link that asks for one." }, "viewer_token": { "maxLength": 200, "type": "string", "description": "A tracked or restricted link's proof of recipient (from its email verification)." }, "r": { "maxLength": 200, "type": "string", "description": "A per-recipient token from the link's URL (`?r=`)." }, "link": { "type": "object", "properties": { "slug": { "minLength": 4, "maxLength": 40, "type": "string" }, "password": { "minLength": 1, "type": "string" }, "expires_at": { "type": "string" }, "max_downloads": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, "note": { "maxLength": 2000, "type": "string" }, "subject": { "maxLength": 200, "type": "string" }, "sealed_meta": { "maxLength": 8192, "type": "string" }, "require_email": { "type": "boolean" }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "allowed_emails": { "maxItems": 50, "type": "array", "items": { "maxLength": 320, "type": "string" } }, "encrypted": { "type": "boolean" }, "e2e_half": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "e2e_half_derivation": { "const": 1, "type": "number" }, "e2e_recovery": { "type": "object", "required": [ "team_key_id", "sealed" ], "properties": { "team_key_id": { "pattern": "^\\d{1,20}$", "type": "string" }, "sealed": { "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 2000, "type": "string" } } }, "kind": { "anyOf": [ { "const": "file", "type": "string" }, { "const": "message", "type": "string" } ] }, "open_once": { "type": "boolean" }, "e2e_stamp": { "type": "boolean" }, "e2e_each": { "type": "boolean" }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "watermark_label": { "maxLength": 60, "type": "string" }, "viewer_mark": { "type": "boolean" }, "allow_guests": { "type": "boolean" }, "guest_downloads": { "type": "boolean" }, "viewers_invite": { "type": "boolean" }, "download_mark": { "type": "boolean" }, "mark_unsupported": { "anyOf": [ { "const": "block", "type": "string" }, { "const": "send", "type": "string" } ] }, "preview_variant": { "anyOf": [ { "const": "720p", "type": "string" }, { "const": "480p", "type": "string" }, { "const": "1080p", "type": "string" } ] }, "bundle": { "type": "boolean" }, "bundle_id": { "maxLength": 32, "type": "string" }, "available_at": { "type": "string" }, "notify_on_download": { "type": "boolean" }, "brand_id": { "maxLength": 24, "type": "string" }, "comments_mode": { "anyOf": [ { "const": "off", "type": "string" }, { "const": "open", "type": "string" }, { "const": "private", "type": "string" } ] }, "ratings_enabled": { "type": "boolean" }, "favorites_enabled": { "type": "boolean" }, "approvals_enabled": { "type": "boolean" }, "restore": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "duration_days": { "minimum": 1, "maximum": 3650, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 3650, "type": "integer" } ] } } } }, "description": "The new link's options: any POST /v1/links field except `file_id` and `encrypted` (`{}` for the defaults)." }, "ad_nonce": { "maxLength": 64, "type": "string", "description": "For the signed-in app (a Free plan's ad credit)." }, "overage_ad": { "type": "boolean", "description": "For the signed-in app (an ad was watched to go over quota)." }, "overage_ad_nonce": { "maxLength": 64, "type": "string", "description": "For the signed-in app (that ad's credit)." } } } } } }, "responses": { "200": { "description": "Forward a received link without downloading it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardResult" } } } }, "default": { "description": "An error: `password_required`, `download_disabled`, `expired`, `exhausted`, `scan_pending`, `content_blocked`, `own_file`, `encrypted`, `link_paused`, `account_under_review`, `forwarding_disabled`, `forwarding_unverified`, `delivery_not_allowed`, `forward_quota_exhausted`, `ad_required`, `overage_requires_ad`, `storage_quota_exceeded`, `insufficient_credits`, `approval_required`, `content_blocked`, `policy_forbidden`, `policy_password_required`, `policy_ttl_exceeded`, `free_tier_size`, `file_size_cap`, `transfer_size_cap`, `paid_required`, `delivery_conflict`, `e2e_view_unsupported`, `e2e_view_too_large`, `viewer_mark_not_on_e2e`, `not_found`, `plan_required`, `invalid_schedule`, `slug_invalid`, `slug_taken`, `allowed_emails_required`, `brand_not_found`, `brand_locked`, `file_budget_exceeded`, `viewer_mark_plan`, `viewer_mark_requires_watermark`, `viewer_mark_requires_verified_access`, `guests_require_viewer_mark`, `guests_require_tracked`, `guests_not_on_e2e`, `stamp_requires_encryption`, `stamp_unsupported`, `policy_locked`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/forwards/check": { "post": { "operationId": "postForwardsCheck", "tags": [ "links" ], "summary": "Check what forwarding a received link would do", "description": "Forwarding copies a link you received into your own storage and gives you a new link to it, without downloading it first. It passes the same checks as a download: password, recipient verification, expiry, download limit and safety scan. It is refused for preview-only and watermarked links, end-to-end encrypted links, your own files (use send again) and when the sender or their team turned forwarding off (403 `forwarding_disabled`). The answer says what it costs (the copy is billed to your workspace like an upload: plan storage, or credits on an API & Agents workspace), whether it uses one of the link's downloads (economy storage), and what the new link may be: never more than the original lets you.", "security": [ { "apiKey": [ "files.read" ] } ], "x-scope": "files.read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "minLength": 4, "maxLength": 40, "type": "string", "description": "The received link's slug (the last part of its URL)." }, "password": { "type": "string", "description": "The link's password, when it has one." }, "email": { "maxLength": 320, "type": "string", "description": "The recipient email, on a link that asks for one." }, "viewer_token": { "maxLength": 200, "type": "string", "description": "A tracked or restricted link's proof of recipient (from its email verification)." }, "r": { "maxLength": 200, "type": "string", "description": "A per-recipient token from the link's URL (`?r=`)." } } } } } }, "responses": { "200": { "description": "Check what forwarding a received link would do", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardCheck" } } } }, "default": { "description": "An error: `password_required`, `download_disabled`, `expired`, `exhausted`, `not_yet_available`, `scan_pending`, `content_blocked`, `own_file`, `encrypted`, `link_paused`, `account_under_review`, `forwarding_disabled`, `forwarding_unverified`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/inbox-items": { "get": { "operationId": "getInboxItems", "tags": [ "received" ], "summary": "List files people uploaded to you", "description": "Uploads through upload pages, file requests and inboxes, newest first. Rejected uploads stay listed (`scan_state: \"rejected\"`). Includes the uploader's answers and contact details. Without parameters: the newest 200. Narrow with `file_request_id`, `inbox_id`, `since` / `until` (ISO 8601) and `scan_state` (comma-separated: pending, clean, flagged, released, not_scannable, rejected); page with `limit` (1–200) and `cursor` (the previous answer's `next_cursor`). Where it came from: `source` (a helpdesk, like `zendesk`), `connection_id` and `ticket`; `q` searches the uploader's name and email, file names, the request and the reference, best first, 25 a page (`page` 1–8; see `search`); an API credential searches the reference only. A malformed value answers 422 `invalid_query`.", "security": [ { "apiKey": [ "inboxes.read" ] } ], "x-scope": "inboxes.read", "parameters": [ { "name": "file_request_id", "in": "query", "required": false, "description": "Only files that arrived through this file request.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "inbox_id", "in": "query", "required": false, "description": "Only files delivered into this inbox.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "Only files requested from this platform (its name: `zendesk`, `testdesk` …).", "schema": { "type": "string" } }, { "name": "connection_id", "in": "query", "required": false, "description": "Only files requested through this helpdesk connection.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "ticket", "in": "query", "required": false, "description": "Only files requested from this ticket (its number, with or without #).", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "A search: the uploader's name and email, file names, the request and the reference (2–100 characters).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "With `q`: the page of results, 1–8.", "schema": { "pattern": "^[0-9]{1,2}$", "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only files received at or after this moment.", "schema": { "format": "date-time", "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only files received before this moment.", "schema": { "format": "date-time", "type": "string" } }, { "name": "scan_state", "in": "query", "required": false, "description": "Comma-separated scan states.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many, 1–200 (default 200).", "schema": { "minimum": 1, "maximum": 200, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "type": "integer" } ] } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page.", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "List files people uploaded to you", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedFile" } }, "next_cursor": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "Pass as `cursor` for older files; null when nothing older matches.", "type": "string" }, { "type": "null" } ] }, "search": { "$ref": "#/components/schemas/SearchMeta" } } } } } }, "default": { "description": "An error: `invalid_query`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/inbox-items/{id}/download": { "post": { "operationId": "postInboxItemsByIdDownload", "tags": [ "received" ], "summary": "Get a download URL for a received file", "description": "A storage URL valid for 1 hour (the bytes never pass through the API). Files still being scanned are allowed; blocked ones are refused. Counts against the monthly download allowance (429 when it's used up).", "security": [ { "apiKey": [ "files.read" ] } ], "x-scope": "files.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The received item's id (from GET /v1/inbox-items).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a download URL for a received file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedDownload" } } } }, "default": { "description": "An error: `not_found`, `gone`, `content_blocked`, `egress_cap_exceeded`, `egress_anomaly`, `view_only`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/inbox-items/{id}/preview": { "post": { "operationId": "postInboxItemsByIdPreview", "tags": [ "received" ], "summary": "Get a preview URL for a received file", "description": "Images, video, audio and PDFs within a size limit (415 otherwise). Waits for the malware scan (425 `scan_pending`). HEIC and TIFF come back as a rendered copy from your preview allowance (425 `preparing` while it renders). Counts as a download. A `view_only` file comes from the protected plane, never the original (425 `preparing` while its copy is made): a PDF answers its first 5 pages in `page_urls` (the rest: POST …/preview/pages), and with `member_mark` each page is your own marked copy (`preview_paused` when the team's marked views are used up).", "security": [ { "apiKey": [ "files.read" ] } ], "x-scope": "files.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The received item's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a preview URL for a received file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedPreview" } } } }, "default": { "description": "An error: `not_found`, `rejected`, `gone`, `content_blocked`, `not_previewable`, `scan_pending`, `restoring`, `relocating`, `egress_cap_exceeded`, `egress_anomaly`, `preview_quota`, `render_failed`, `preparing`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/inbox-items/{id}/preview/pages": { "post": { "operationId": "postInboxItemsByIdPreviewPages", "tags": [ "received" ], "summary": "Get more pages of a view-only received PDF", "description": "After POST …/preview answered a view-only PDF's first pages: the next `count` (10 at most) from `from`, each from the protected plane (your own marked copy with `member_mark`; null once the team's marked views are used up, with `preview_paused`).", "security": [ { "apiKey": [ "files.read" ] } ], "x-scope": "files.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The received item's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from" ], "properties": { "from": { "minimum": 0, "maximum": 100000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 100000, "type": "integer" } ], "description": "The first page to return, counting from 0 (5 after the first screen)." }, "count": { "minimum": 1, "maximum": 50, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 50, "type": "integer" } ], "description": "How many pages (10 at most)." } } } } } }, "responses": { "200": { "description": "Get more pages of a view-only received PDF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedPreviewPages" } } } }, "default": { "description": "An error: `not_found`, `not_view_only`, `gone`, `preparing`, `render_failed`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/inboxes": { "get": { "operationId": "getInboxes", "tags": [ "inboxes" ], "summary": "List your inboxes", "description": "The workspace's inboxes, newest first (200 at most).", "security": [ { "apiKey": [ "inboxes.read" ] } ], "x-scope": "inboxes.read", "responses": { "200": { "description": "List your inboxes", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postInboxes", "tags": [ "inboxes" ], "summary": "Create an inbox", "description": "An inbox with a 12-character address. Items in it expire after `default_ttl_seconds` (7 days by default, 30 at most). Files reach it through a file request's `deliver_to_inbox_id`.", "security": [ { "apiKey": [ "inboxes.write" ] } ], "x-scope": "inboxes.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "maxLength": 120, "type": "string", "description": "Your label (120 characters at most)." }, "default_ttl_seconds": { "minimum": 60, "maximum": 2592000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 60, "maximum": 2592000, "type": "integer" } ], "description": "How long items are kept: 60 seconds to 30 days (7 days by default)." } } } } } }, "responses": { "201": { "description": "Create an inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxCreated" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/inboxes/{id}/items": { "get": { "operationId": "getInboxesByIdItems", "tags": [ "inboxes" ], "summary": "List an inbox's files", "description": "The 50 newest items. An unknown inbox gives an empty list. Check `file.scan_state` before you use a file.", "security": [ { "apiKey": [ "inboxes.read" ] } ], "x-scope": "inboxes.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The inbox's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List an inbox's files", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxItem" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/intakes": { "post": { "operationId": "postIntakes", "tags": [ "intakes" ], "summary": "Open a secure intake", "description": "A short-lived upload page for one person in one conversation, for a bot, an assistant or a helpdesk. It closes after one upload and expires in 24 hours by default (15 minutes to 7 days). With `send_to` SendFlo emails the person, and only they can upload; with `for_email` the page is bound to them and `upload_url` carries their one-time sign-in. `client_token` (single use, 15 minutes) opens the page in the widget's pop-up (`SendFlo.requestUpload`). Watch `intake.ready` (every file stored and scanned clean) or poll GET /v1/intakes/{id}. What an intake collects is content-blind to every API credential (API keys, apps' OAuth tokens, and so MCP and A2A): download, preview, links, send again and agent attachments answer 403 `intake_content_blind`, whatever the key's scopes, unless the intake was made with `agent_access: \"read\"` where the team allows it. An API & Agents workspace pays 1 credit, as for a file request.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "maxLength": 2000, "type": "string", "description": "What to upload, shown on the page." }, "name": { "maxLength": 120, "type": "string", "description": "Your label for it (never shown to the uploader)." }, "requested_by": { "maxLength": 80, "type": "string", "description": "Who is asking, as the page says it: \"Requested by Acme support in your chat\"." }, "send_to": { "format": "email", "maxLength": 320, "type": "string", "description": "SendFlo emails this person the link; only they can upload." }, "for_email": { "format": "email", "maxLength": 320, "type": "string", "description": "Bind the page to this person without emailing them." }, "expires_in_minutes": { "minimum": 15, "maximum": 10080, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 15, "maximum": 10080, "type": "integer" } ], "description": "15 to 10,080 (7 days); default 1,440." }, "max_files": { "minimum": 1, "maximum": 50, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 50, "type": "integer" } ], "description": "Files per upload (1–50; default 10)." }, "close_after_uploads": { "minimum": 1, "maximum": 100, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100, "type": "integer" } ], "description": "Uploads before it closes (default 1)." }, "allowed_types": { "maxItems": 40, "type": "array", "items": { "maxLength": 20, "type": "string" }, "description": "Accepted file types: category ids or extensions." }, "max_bytes_per_file": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ], "description": "A per-file size limit under the plan's." }, "questions": { "maxItems": 10, "type": "array", "items": { "type": "object", "required": [ "id", "label", "type" ], "properties": { "id": { "maxLength": 40, "type": "string" }, "label": { "maxLength": 200, "type": "string" }, "type": { "maxLength": 20, "type": "string" }, "required": { "type": "boolean" }, "options": { "maxItems": 50, "type": "array", "items": { "maxLength": 200, "type": "string" } } } }, "description": "Up to 10 questions for the uploader (the upload page's question types)." }, "locked_answers": { "type": "object", "patternProperties": { "^(.*)$": { "maxLength": 500, "type": "string" } }, "description": "Answers you set, by question id: shown to the uploader, never editable." }, "agent_fields": { "type": "object", "properties": { "answers": { "maxItems": 10, "type": "array", "items": { "maxLength": 40, "type": "string" } }, "names": { "type": "boolean" } }, "description": "What the bot sees beyond status, counts, types, sizes and the scan: `answers` (question ids) and `names` (file names; off by default)." }, "agent_access": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "read", "type": "string" } ], "description": "`none` (default) or `read`: whether API credentials may open what it collects, where the team allows it (403 `intake_read_not_allowed` otherwise)." }, "external_refs": { "type": "object", "required": [ "provider", "kind", "id" ], "properties": { "provider": { "maxLength": 40, "type": "string" }, "kind": { "maxLength": 40, "type": "string" }, "id": { "maxLength": 200, "type": "string" }, "url": { "maxLength": 2048, "type": "string" }, "label": { "maxLength": 200, "type": "string" } }, "description": "Where it came from: {provider, kind, id, url?, label?}, carried on every item and event." }, "handoff": { "type": "object", "required": [ "to" ], "properties": { "to": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "email": { "maxLength": 320, "type": "string" }, "user_id": { "pattern": "^\\d{1,20}$", "type": "string" }, "group_id": { "pattern": "^\\d{1,20}$", "type": "string" }, "permission": { "anyOf": [ { "const": "view", "type": "string" }, { "const": "manage", "type": "string" } ] } } } }, "expires_days": { "minimum": 1, "maximum": 365, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 365, "type": "integer" } ] } }, "description": "When it's ready, hand the files to these people or groups of the team: {to: [{email | user_id | group_id, permission}], expires_days}." }, "brand_id": { "maxLength": 24, "type": "string", "description": "A brand kit for the page." }, "widget_origin": { "maxLength": 300, "type": "string", "description": "The chat page's origin, for the widget's pop-up to answer to." } } } } } }, "responses": { "201": { "description": "Open a secure intake", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeCreated" } } } }, "default": { "description": "An error: `intake_read_not_allowed`, `unknown_question`, `handoff_needs_team`, `unknown_member`, `unknown_group`, `conflicting_person`, `insufficient_credits`, `plan_required`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "getIntakes", "tags": [ "intakes" ], "summary": "List your secure intakes", "description": "The workspace's 50 newest intakes, metadata only (a key with `file_requests.write` may read too).", "security": [ { "apiKey": [ "inboxes.read" ] } ], "x-scope": "inboxes.read", "responses": { "200": { "description": "List your secure intakes", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Intake" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/intakes/{id}": { "get": { "operationId": "getIntakesById", "tags": [ "intakes" ], "summary": "Read a secure intake", "description": "Its status (open → opened → submitted → ready, or rejected / expired / closed), how many files, each one's type, size and scan, whether the uploader proved their email, the answers it shares, and who it was handed to. Never the content, never a link that serves bytes. What an intake collects is content-blind to every API credential (API keys, apps' OAuth tokens, and so MCP and A2A): download, preview, links, send again and agent attachments answer 403 `intake_content_blind`, whatever the key's scopes, unless the intake was made with `agent_access: \"read\"` where the team allows it.", "security": [ { "apiKey": [ "inboxes.read" ] } ], "x-scope": "inboxes.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The intake's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Read a secure intake", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intake" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteIntakesById", "tags": [ "intakes" ], "summary": "Close a secure intake", "description": "No more uploads; what it collected stays, with its hand-offs.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The intake's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Close a secure intake", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intake" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/intakes/{id}/handoff": { "post": { "operationId": "postIntakesByIdHandoff", "tags": [ "intakes" ], "summary": "Hand an intake's files to someone", "description": "Give a team member (by email or id) or a group of the team view or manage access to every file the intake collected, and to any it collects later, with an optional end. They open them in SendFlo → Received → Handed to me; every open is in the workspace's audit log. A grant never gives the bot anything.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The intake's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "object", "properties": { "email": { "maxLength": 320, "type": "string" }, "user_id": { "pattern": "^\\d{1,20}$", "type": "string" }, "group_id": { "pattern": "^\\d{1,20}$", "type": "string" }, "permission": { "anyOf": [ { "const": "view", "type": "string" }, { "const": "manage", "type": "string" } ] } }, "description": "{email | user_id | group_id, permission: view | manage}." }, "expires_at": { "maxLength": 40, "type": "string", "description": "When the access ends (ISO time)." } } } } } }, "responses": { "200": { "description": "Hand an intake's files to someone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intake" } } } }, "default": { "description": "An error: `not_found`, `handoff_needs_team`, `unknown_member`, `unknown_group`, `invalid_expiry`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteIntakesByIdHandoff", "tags": [ "intakes" ], "summary": "Take a hand-off back", "description": "End a person's or group's access to the intake's files at once.", "security": [ { "apiKey": [ "file_requests.write" ] } ], "x-scope": "file_requests.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The intake's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "group", "type": "string" } ], "description": "user or group." }, "id": { "pattern": "^\\d{1,20}$", "type": "string", "description": "The person's or group's id (as in `handed_to`)." } } } } } }, "responses": { "200": { "description": "Take a hand-off back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Intake" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links": { "post": { "operationId": "postLinks", "tags": [ "links" ], "summary": "Create a share link", "description": "Creates a link for a stored file (`file_id` from completing an upload). The expiry is clamped to the plan; `expiry_capped` says why when yours was shortened. Team policy (no public links, a password required, a maximum lifetime) and approval before send apply. Retrying the same create within 2 minutes returns the first link with `replayed: true`.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_id" ], "properties": { "file_id": { "type": "string", "description": "The stored file." }, "slug": { "minLength": 4, "maxLength": 40, "type": "string", "description": "A custom link name (paid plans): 4–40 letters, digits, `_` or `-`." }, "password": { "minLength": 1, "type": "string", "description": "A download password." }, "expires_at": { "type": "string", "description": "When the link expires; clamped to the plan (Free: 48 hours by default, at most 7 days; paid: 30 days on monthly billing, a year on annual)." }, "max_downloads": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ], "description": "A download limit; leave it out for unlimited." }, "note": { "maxLength": 2000, "type": "string", "description": "A note shown to recipients (2000 characters at most)." }, "subject": { "maxLength": 200, "type": "string", "description": "The email and page subject (200 characters at most)." }, "sealed_meta": { "maxLength": 8192, "type": "string", "description": "With `encrypted`: the subject and note sealed on your side with the link key, instead of `subject` and `note` (422 `sealed_meta_with_plain` with either; 422 `sealed_meta_requires_e2e` without `encrypted`). The envelope is `sfm1..`: AES-256-GCM under HKDF-SHA256(link key, salt `sendflo/meta/v1`, info `sendflo link metadata`), additional data `meta`, over the JSON `{\"v\":1,\"subject\"?,\"note\"?}`. SendFlo can't read it; the link page opens it in the recipient's browser, and SendFlo's email says the message is sealed. The SDK and the CLI seal it for you." }, "require_email": { "type": "boolean", "description": "Older option: recipients type an email (not verified) before downloading." }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ], "description": "`public` (the default), `tracked` (recipients verify their email) or `restricted` (verified and on `allowed_emails`)." }, "allowed_emails": { "maxItems": 50, "type": "array", "items": { "maxLength": 320, "type": "string" }, "description": "Up to 50 addresses; required for `restricted`." }, "encrypted": { "type": "boolean", "description": "The file was encrypted end to end on the sender's device (paid plans)." }, "e2e_half": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string", "description": "With `encrypted`, a split key: the SERVER half (32 random bytes, base64url). The file is sealed with HKDF-SHA256(client half ‖ server half, salt `sendflo/e2e-split/v1`, info `sendflo link key`); the link you share carries only the client half, as `#k=2.`. SendFlo stores this half sealed, gives it to a recipient only after the link's gate (its password, their verified email), and deletes it when the link is revoked or expires. A split link can be emailed by SendFlo (`key_fragment` on the email calls); a whole-key link can't. 422 `e2e_half_without_encryption` without `encrypted`." }, "e2e_half_derivation": { "const": 1, "type": "number", "description": "The split key's derivation: `1` (the only one; the default)." }, "e2e_recovery": { "type": "object", "required": [ "team_key_id", "sealed" ], "properties": { "team_key_id": { "pattern": "^\\d{1,20}$", "type": "string" }, "sealed": { "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 2000, "type": "string" } }, "description": "With `encrypted`, on a team that keeps a recovery key (Team Pro, Team Enterprise): the link's key sealed on your side to the team's recovery key, `{team_key_id, sealed}` (HPKE with X-Wing, info `sendflo/link-recovery/v1/`). Without it the send answers 422 `recovery_copy_required`, whose body names the key (`recovery.team_key_id`, `recovery.public_key`): seal and send again. 422 `recovery_copy_stale` when the key changed." }, "kind": { "anyOf": [ { "const": "file", "type": "string" }, { "const": "message", "type": "string" } ], "description": "`file` (the default) or `message`: a secure message. Its file is the text, sealed on your side with SFE2 under a split key (`encrypted` and `e2e_half` required; 256 KB sealed at most, 413 `message_too_large`). It opens only on its page (every download, preview and feedback route answers 409 `message_link`), and takes a password, who can open it, an expiry and `open_once`; anything else answers 422 `message_options`." }, "open_once": { "type": "boolean", "description": "With `kind: \"message\"`: the message opens once. The first reveal deletes it (the link is revoked and its key half wiped), and the page then answers 410 `already_opened`. 422 `open_once_requires_message` on a file link." }, "e2e_stamp": { "type": "boolean", "description": "With `encrypted`: the sender's device stamped `watermark_label` into this file (PDFs and images) before encrypting it. Only a client that stamps sets it — the SendFlo apps, the SDK (`sendFile({ encrypt, stamp })`) and the CLI (`send --encrypt --stamp`) — so this needs their `X-SendFlo-Stamp: v1` header (422 `stamp_unsupported` otherwise; 422 `stamp_requires_encryption` without `encrypted`). A team that requires the sender's mark accepts an end-to-end link only stamped (403 `policy_locked`, `setting: e2e_stamp`)." }, "e2e_each": { "type": "boolean", "description": "Team Pro and Team Enterprise, with `e2e_stamp` on a `restricted` link of 1–50 people, the copies within the sender's storage (413 `e2e_each_storage`; 422 `e2e_each_requires_stamp`, `e2e_each_requires_restricted`, `e2e_each_recipients`; 403 `e2e_each_plan`): the sender's device stamps one copy per listed person with `watermark_label` and their email, seals each with the link's key and registers it (the SendFlo apps do this; the API has no public call for it). A confirmed person downloads their own copy. Someone added later needs `e2e_copies` on the change (409 `e2e_each_choice`): `make` (their copy is made on the sender's device; until it's registered their download answers 425 `copy_pending`) or `mark_only` (they get the link's file, which carries the sender's mark alone)." }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ], "description": "`preview_download` (the default), `download_only`, or the paid `preview_only` and `preview_watermark`. With `encrypted`, a preview mode is end-to-end view-only: images (JPEG, PNG, WebP, GIF, AVIF, BMP) and PDFs up to 200 MB that the recipient's page decrypts and shows, never a download (422 `e2e_view_unsupported`, 413 `e2e_view_too_large`)." }, "watermark_label": { "maxLength": 60, "type": "string", "description": "For `preview_watermark`: the mark baked into the previews; with `download_mark`: the mark on every downloaded copy (and preview). 60 characters at most." }, "viewer_mark": { "type": "boolean", "description": "Team Pro and Team Enterprise: each viewer's own copy of every image and PDF page carries the label AND their confirmed email; on a video the player draws that email over the picture (`overlay` in the preview answer). Needs `preview_watermark` or `download_mark`, and `tracked` or `restricted` access (422 `viewer_mark_requires_verified_access`). Each copy counts against the team's pool: a viewed page or image once, a downloaded image 1 per started 12 MP, a downloaded PDF or text 1 per started 30 MB. Never on `encrypted` links (422 `viewer_mark_not_on_e2e`)." }, "allow_guests": { "type": "boolean", "description": "With `viewer_mark` on a `tracked` link (422 `guests_require_viewer_mark`, `guests_require_tracked`; never `encrypted`, 422 `guests_not_on_e2e`): guests may also view without confirming an email. Each guest view is its own copy, marked \"Guest · · · view \", counted against the team's pool; guests view only unless `guest_downloads`. A guest on a VPN, proxy, Tor, a server, Apple Private Relay or an unknown network confirms an email instead. A team protection policy can forbid guests (403 `policy_locked`, setting `no_guests`)." }, "guest_downloads": { "type": "boolean", "description": "With `allow_guests` and `download_mark` (422 `guest_downloads_require_guests`, `guest_downloads_require_marked_downloads`): guests may also download — each download is their own marked copy with their guest mark, never the original. Off by default; guests view only." }, "viewers_invite": { "type": "boolean", "description": "On `tracked` or `restricted` links (422 `invites_require_verified_access`; never `encrypted`, 422 `invites_not_on_e2e`): a recipient who confirmed their email may invite people by email from the link's page — 5 per recipient, 50 per send. Each invited person is added to the send as if you had added them (a `restricted` send lists them; your plan's limits apply), confirms their own email to open it and gets their own copies and marks. Your activity shows who invited whom. Off by default; turning it off stops new invitations, and leaving `tracked` / `restricted` turns it off." }, "download_mark": { "type": "boolean", "description": "Paid plans, on `preview_download` or `download_only`: recipients download a MARKED copy, never the original — the label on every image and PDF page (text files arrive as marked PDFs, HEIC as JPEG), and, with `viewer_mark`, each recipient's confirmed email too. Previews are marked the same way. The sender's own downloads stay the original. Not with `encrypted` (422 `delivery_conflict`: the device stamps those, `e2e_stamp`)." }, "mark_unsupported": { "anyOf": [ { "const": "block", "type": "string" }, { "const": "send", "type": "string" } ], "description": "With `download_mark`: what happens to files that can't be marked (archives, password-protected documents…): `block` (the default — recipients can't download them) or `send` (downloaded unmarked)." }, "preview_variant": { "anyOf": [ { "const": "720p", "type": "string" }, { "const": "480p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "For preview-only video and audio: `720p` (the default), `480p` (half the video allowance) or, on Team Enterprise, `1080p` (twice the allowance; 403 `preview_1080p_plan` on other plans)." }, "bundle": { "type": "boolean", "description": "`true` starts a multi-file send with this file as its first link." }, "bundle_id": { "maxLength": 32, "type": "string", "description": "Add this file to the send whose first link has this id." }, "available_at": { "type": "string", "description": "Schedule the link to go live later (Plus and up)." }, "notify_on_download": { "type": "boolean", "description": "Email the sender on each download." }, "brand_id": { "maxLength": 24, "type": "string", "description": "The brand kit for the download page (paid plans); the default kit when left out." }, "comments_mode": { "anyOf": [ { "const": "off", "type": "string" }, { "const": "open", "type": "string" }, { "const": "private", "type": "string" } ], "description": "Recipient comments: `off` (the default), `open` or `private`." }, "ratings_enabled": { "type": "boolean", "description": "Let recipients rate files." }, "favorites_enabled": { "type": "boolean", "description": "Let recipients favourite files." }, "approvals_enabled": { "type": "boolean", "description": "Let recipients approve files or ask for changes." }, "restore": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "duration_days": { "minimum": 1, "maximum": 3650, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 3650, "type": "integer" } ] } }, "description": "File Restore: `{ enabled, duration_days }`; off on Free." } } } } } }, "responses": { "200": { "description": "Create a share link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCreated" } } } }, "default": { "description": "An error: `file_not_ready`, `awaiting_approval`, `approval_required`, `content_blocked`, `policy_forbidden`, `policy_password_required`, `policy_ttl_exceeded`, `free_tier_size`, `file_size_cap`, `transfer_size_cap`, `paid_required`, `delivery_conflict`, `e2e_view_unsupported`, `e2e_view_too_large`, `viewer_mark_not_on_e2e`, `not_found`, `plan_required`, `invalid_schedule`, `slug_invalid`, `slug_taken`, `allowed_emails_required`, `brand_not_found`, `brand_locked`, `file_budget_exceeded`, `viewer_mark_plan`, `viewer_mark_requires_watermark`, `viewer_mark_requires_verified_access`, `guests_require_viewer_mark`, `guests_require_tracked`, `guests_not_on_e2e`, `stamp_requires_encryption`, `stamp_unsupported`, `policy_locked`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "getLinks", "tags": [ "links" ], "summary": "List your share links", "description": "Every link in the workspace, revoked and expired ones included, newest first, 25 per page (up to 100 with `limit`). Pass `next_cursor` back as `cursor` for the next page. With `q`: the links whose note, subject, file names, recipients or slug match (typos forgiven), best first, 25 a page (`page` 1–8; see `search`). An end-to-end link is found by its file type, never its name.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Links per page, 1–100 (25 by default).", "schema": { "minimum": 1, "maximum": 100, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 100, "type": "integer" } ] } }, { "name": "q", "in": "query", "required": false, "description": "Search words (200 characters at most).", "schema": { "maxLength": 200, "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "With `q`: the page, 1–8.", "schema": { "pattern": "^[0-9]{1,2}$", "type": "string" } } ], "responses": { "200": { "description": "List your share links", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LinkListItem" } }, "next_cursor": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "search": { "$ref": "#/components/schemas/SearchMeta" } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/from-url": { "post": { "operationId": "postLinksFromUrl", "tags": [ "links" ], "summary": "Send a file from a link", "description": "SendFlo fetches the file at a public https address (resolved and checked first: never a private or local network; no redirects; up to 100 MB in 60 seconds), stores it in your workspace and makes a share link for it, as POST /v1/links does. The key also needs `transfers.write` (the upload). For automation apps (Zapier, Make, n8n) and scripts that have an address, not the file; A2A's `send_file` with a URL part does the same.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "maxLength": 2048, "type": "string", "description": "The file's https address." }, "name": { "maxLength": 255, "type": "string", "description": "The file's name (default: the address's last path segment)." }, "note": { "maxLength": 500, "type": "string", "description": "A note for the recipient." } } } } } }, "responses": { "200": { "description": "Send a file from a link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCreated" } } } }, "default": { "description": "An error: `invalid_url`, `file_unreachable`, `file_too_large`, `upload_failed`, `file_not_ready`, `awaiting_approval`, `approval_required`, `content_blocked`, `policy_forbidden`, `policy_password_required`, `policy_ttl_exceeded`, `free_tier_size`, `file_size_cap`, `transfer_size_cap`, `paid_required`, `delivery_conflict`, `e2e_view_unsupported`, `e2e_view_too_large`, `viewer_mark_not_on_e2e`, `not_found`, `plan_required`, `invalid_schedule`, `slug_invalid`, `slug_taken`, `allowed_emails_required`, `brand_not_found`, `brand_locked`, `file_budget_exceeded`, `viewer_mark_plan`, `viewer_mark_requires_watermark`, `viewer_mark_requires_verified_access`, `guests_require_viewer_mark`, `guests_require_tracked`, `guests_not_on_e2e`, `stamp_requires_encryption`, `stamp_unsupported`, `policy_locked`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}": { "patch": { "operationId": "patchLinksById", "tags": [ "links" ], "summary": "Change a link's settings", "description": "Changes only the fields you send. A file on included (pool) storage keeps its download limit from upload, and once it has been read its access, recipients and a shorter expiry are fixed too (409 `pool_locked`, with `field` and `why`; see `capabilities` on the link); a file on unlimited-download storage is open to every change within the plan's limits. The password, note, subject, delivery mode and download emails are never locked. Feedback settings apply to every file of the send.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The link's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A new password; null or \"\" removes it." }, "expires_at": { "type": "string", "description": "A new expiry (clamped to the plan)." }, "max_downloads": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ], "description": "A new download limit; null = unlimited." }, "note": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "The note; null clears it." }, "subject": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "The subject; null clears it." }, "sealed_meta": { "anyOf": [ { "maxLength": 8192, "type": "string" }, { "type": "null" } ], "description": "An end-to-end link's sealed subject and note (see POST /v1/links); null clears them. A link whose subject and note are sealed refuses a readable one (422 `meta_sealed`)." }, "replies_off": { "type": "boolean", "description": "Turn secure replies off (or on) for the whole send: verified recipients of a Tracked or Restricted send can reply on its page with a message and files (GET /v1/links/:id/replies)." }, "require_email": { "type": "boolean", "description": "Older option: recipients type an email first." }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ], "description": "`public`, `tracked` or `restricted`." }, "allowed_emails": { "maxItems": 50, "type": "array", "items": { "maxLength": 320, "type": "string" }, "description": "Replaces the restricted list (50 at most)." }, "base_allowed_emails": { "maxItems": 200, "type": "array", "items": { "maxLength": 320, "type": "string" }, "description": "Optional, with `allowed_emails`: the list as your editor showed it. Then only who you added or removed since is applied over the list as it is now, so someone added meanwhile (from People, another device or the API) keeps access." }, "e2e_copies": { "anyOf": [ { "const": "make", "type": "string" }, { "const": "mark_only", "type": "string" } ], "description": "On a Mark each recipient link (`e2e_each`), required when `allowed_emails` adds people (409 `e2e_each_choice`): `make` — their own copies are made on the sender's device (the SendFlo apps), their download waits (425 `copy_pending`) until then — or `mark_only`, the copy with the sender's mark alone." }, "notify_on_download": { "type": "boolean", "description": "Email the sender on each download." }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ], "description": "The delivery mode (the preview-only modes on paid plans)." }, "watermark_label": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ], "description": "The watermark; null = the default mark." }, "viewer_mark": { "type": "boolean", "description": "Add or remove each viewer's confirmed email in their own copies (Team Pro and Team Enterprise; tracked or restricted access)." }, "allow_guests": { "type": "boolean", "description": "Let guests view without an email (their IP, the time and a view id are printed instead), or stop letting them in. Needs `viewer_mark` and `tracked` access." }, "guest_downloads": { "type": "boolean", "description": "Let guests download their own marked copies (their guest mark on every image and PDF page), or keep them view-only. Needs `allow_guests` and `download_mark` (422 `guest_downloads_require_guests`, `guest_downloads_require_marked_downloads`). Turning guests or marked downloads off turns this off too." }, "viewers_invite": { "type": "boolean", "description": "Let recipients who confirmed their email invite people (5 each, 50 per send), or stop new invitations — people already invited keep their access. Needs `tracked` or `restricted` access (422 `invites_require_verified_access`); never `encrypted` (422 `invites_not_on_e2e`). Moving the link to `public` turns this off." }, "download_mark": { "type": "boolean", "description": "Download with watermark on or off (paid; a downloadable mode)." }, "mark_unsupported": { "anyOf": [ { "const": "block", "type": "string" }, { "const": "send", "type": "string" } ], "description": "`block` or `send`: files that can't be marked." }, "preview_variant": { "anyOf": [ { "const": "720p", "type": "string" }, { "const": "480p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "`720p`, `480p`, or `1080p` on Team Enterprise (403 `preview_1080p_plan`)." }, "comments_mode": { "anyOf": [ { "const": "off", "type": "string" }, { "const": "open", "type": "string" }, { "const": "private", "type": "string" } ], "description": "`off`, `open` or `private` (the whole send)." }, "ratings_enabled": { "type": "boolean", "description": "Ratings on or off (the whole send)." }, "favorites_enabled": { "type": "boolean", "description": "Favourites on or off (the whole send)." }, "approvals_enabled": { "type": "boolean", "description": "Approvals on or off (the whole send)." }, "rating_scale": { "anyOf": [ { "const": "stars5", "type": "string" }, { "const": "score10", "type": "string" } ], "description": "`stars5` or `score10`, only while the send has no ratings." } } } } } }, "responses": { "200": { "description": "Change a link's settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkUpdated" } } } }, "default": { "description": "An error: `not_found`, `pool_locked`, `policy_password_required`, `invalid_expiry`, `policy_ttl_exceeded`, `allowed_emails_required`, `paid_required`, `delivery_conflict`, `e2e_view_unsupported`, `e2e_view_too_large`, `viewer_mark_not_on_e2e`, `feedback_policy_off`, `rating_scale_locked`, `empty_patch`, `viewer_mark_plan`, `viewer_mark_requires_watermark`, `viewer_mark_requires_verified_access`, `guests_require_viewer_mark`, `guests_require_tracked`, `guests_not_on_e2e`, `policy_locked`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteLinksById", "tags": [ "links" ], "summary": "Revoke a share link", "description": "Revokes one link for good and frees the file's storage, unless another live link, an open restore window or a safety review still needs it. Answers 204, also for an unknown or already revoked link.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The link's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file sits on pooled storage that keeps it a while longer; it no longer counts against you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkRevokeRetained" } } } }, "204": { "description": "Revoke a share link" }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/events": { "get": { "operationId": "getLinksByIdEvents", "tags": [ "activity" ], "summary": "List one link's latest events", "description": "The newest 100 events of one link. For a whole send, with paging, use GET /v1/links/{id}/transfer/activity.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The link's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List one link's latest events", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LinkEvent" } } } } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/feedback": { "get": { "operationId": "getLinksByIdFeedback", "tags": [ "feedback" ], "summary": "Read a transfer's feedback summary", "description": "The whole transfer: its feedback settings, per-file totals (revoked and expired files too, with `live: false`) and the people who gave feedback, with their email and how they were identified (the 500 most recently active).", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Read a transfer's feedback summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkFeedback" } } } }, "default": { "description": "An error: `not_found`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/feedback/comments": { "get": { "operationId": "getLinksByIdFeedbackComments", "tags": [ "feedback" ], "summary": "List one file's comments", "description": "One file's comments as the owner sees them: hidden comments, blocked people and emails included. Oldest first, 50 per page, replies carry `parent_id`. Pass the previous page's `next` as `after`.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } }, { "name": "file", "in": "query", "required": true, "description": "The file's link id or slug (it must be in this transfer).", "schema": { "maxLength": 40, "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "The `next` of the previous page.", "schema": { "maxLength": 20, "type": "string" } } ], "responses": { "200": { "description": "List one file's comments", "content": { "application/json": { "schema": { "type": "object", "required": [ "comments", "next" ], "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackComment" } }, "next": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "description": "An error: `not_found`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/feedback/comments/{cid}": { "delete": { "operationId": "deleteLinksByIdFeedbackCommentsByCid", "tags": [ "feedback" ], "summary": "Delete a comment", "description": "Deletes any comment on the transfer. One that still has replies stays as a placeholder (`body: null`) so the replies keep their place.", "security": [ { "apiKey": [ "feedback.write" ] } ], "x-scope": "feedback.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } }, { "name": "cid", "in": "path", "required": true, "description": "The comment's id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Delete a comment" }, "default": { "description": "An error: `not_found`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/feedback/comments/{cid}/resolve": { "put": { "operationId": "putLinksByIdFeedbackCommentsByCidResolve", "tags": [ "feedback" ], "summary": "Resolve a comment thread", "description": "Marks a top-level comment resolved (replies answer 404). Safe to repeat.", "security": [ { "apiKey": [ "feedback.write" ] } ], "x-scope": "feedback.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } }, { "name": "cid", "in": "path", "required": true, "description": "The top-level comment's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolve a comment thread", "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "object", "required": [ "id", "resolved" ], "properties": { "id": { "type": "string" }, "resolved": { "type": "boolean" } } } } } } } }, "default": { "description": "An error: `not_found`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteLinksByIdFeedbackCommentsByCidResolve", "tags": [ "feedback" ], "summary": "Reopen a resolved comment thread", "description": "Clears the resolved mark of a top-level comment. Safe to repeat.", "security": [ { "apiKey": [ "feedback.write" ] } ], "x-scope": "feedback.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } }, { "name": "cid", "in": "path", "required": true, "description": "The top-level comment's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reopen a resolved comment thread", "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "object", "required": [ "id", "resolved" ], "properties": { "id": { "type": "string" }, "resolved": { "type": "boolean" } } } } } } } }, "default": { "description": "An error: `not_found`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/feedback/export": { "get": { "operationId": "getLinksByIdFeedbackExport", "tags": [ "feedback" ], "summary": "Export a transfer's feedback", "description": "Every comment, rating, favourite and approval, with names and emails, as a download. CSV by default (UTF-8 with a byte-order mark, formula-safe cells; columns `type,file,person,email,verified_by,value,comment,at,where,reply_to,resolved,hidden,date`), or JSON with `format=json`.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "`csv` (the default) or `json`.", "schema": { "anyOf": [ { "const": "csv", "type": "string" }, { "const": "json", "type": "string" } ] } } ], "responses": { "200": { "description": "Export a transfer's feedback", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackExport" } } } }, "default": { "description": "An error: `not_found`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/feedback/reviewers/{rid}/block": { "put": { "operationId": "putLinksByIdFeedbackReviewersByRidBlock", "tags": [ "feedback" ], "summary": "Block a person on this transfer", "description": "Hides all their comments from everyone else, signs them out and refuses anything more from them on this transfer. The sender can't be blocked (409).", "security": [ { "apiKey": [ "feedback.write" ] } ], "x-scope": "feedback.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } }, { "name": "rid", "in": "path", "required": true, "description": "The person's reviewer id (`author.id`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Block a person on this transfer", "content": { "application/json": { "schema": { "type": "object", "required": [ "reviewer" ], "properties": { "reviewer": { "$ref": "#/components/schemas/FeedbackReviewer" } } } } } }, "default": { "description": "An error: `not_found`, `cannot_block_sender`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteLinksByIdFeedbackReviewersByRidBlock", "tags": [ "feedback" ], "summary": "Unblock a person on this transfer", "description": "Lifts the block and shows again the comments the block hid (a Trust & Safety hold stays). Safe to repeat.", "security": [ { "apiKey": [ "feedback.write" ] } ], "x-scope": "feedback.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } }, { "name": "rid", "in": "path", "required": true, "description": "The person's reviewer id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unblock a person on this transfer", "content": { "application/json": { "schema": { "type": "object", "required": [ "reviewer" ], "properties": { "reviewer": { "$ref": "#/components/schemas/FeedbackReviewer" } } } } } }, "default": { "description": "An error: `not_found`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/replies": { "get": { "operationId": "getLinksByIdReplies", "tags": [ "feedback" ], "summary": "List a transfer's secure replies", "description": "Replies people sent back on the transfer's page (CA6c, docs/SECURE-REPLIES.md), newest first: who (a verified address), the message and the files that arrived (also in Received, scanned like any upload). On an end-to-end transfer the message (`sfm1.…`) and each file's name (`sealed_name`) are sealed with the link key: open them with the full link (packages/transfer `openName`; the message with additional data `reply`). Replies are on for Tracked and Restricted transfers unless the sender turned them off (`replies_off`). A reply to a secure message (CA16) is sealed with a key from the link's client half and its own `key_half`, given only to the signed-in sender (never to an API key): an open-once message's own half is wiped when it's read.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of any file (link) in the transfer.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List a transfer's secure replies", "content": { "application/json": { "schema": { "type": "object", "required": [ "replies", "replies_off", "replies_on" ], "properties": { "replies": { "$ref": "#/components/schemas/TransferReplies" }, "replies_off": { "description": "The sender turned replies off for this transfer.", "type": "boolean" }, "replies_on": { "description": "Recipients can reply now (Tracked or Restricted, not turned off).", "type": "boolean" } } } } } }, "default": { "description": "An error: `not_found`, `feedback_unavailable`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/transfer": { "get": { "operationId": "getLinksByIdTransfer", "tags": [ "links" ], "summary": "Get the whole send behind a link", "description": "The send as one unit: its state, counts and every file's link (revoked ones included).", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Any link of the send (its first link or any other); a single-file send is a send of one.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the whole send behind a link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferDetail" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/transfer/activity": { "get": { "operationId": "getLinksByIdTransferActivity", "tags": [ "activity" ], "summary": "See who opened and downloaded a send", "description": "Every file's events, newest first, 50 per page (up to 200 with `limit`); pass `next_cursor` back as `cursor`. The first page also lists the people (up to 200, `people_total` counts them all) with what they downloaded and the delivery proof; later pages answer `people: null`. On Team Pro and Team Enterprise each event also carries the IP address and its network, and each person their addresses; other plans see country and device only.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Any link of the send (its first link or any other); a single-file send is a send of one.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Events per page, 1–200 (50 by default).", "schema": { "minimum": 1, "maximum": 200, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "type": "integer" } ] } } ], "responses": { "200": { "description": "See who opened and downloaded a send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferActivity" } } } }, "default": { "description": "An error: `invalid_cursor`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/transfer/audit": { "get": { "operationId": "getLinksByIdTransferAudit", "tags": [ "activity" ], "summary": "Download a send's audit report", "description": "A download (`sendflo-audit--.csv` or `.json`) with the send, its files, the people, your actions and every event, oldest first (100,000 at most). CSV by default (UTF-8 with a byte-order mark, formula-safe cells; columns `section,time_utc,file,link_id,person,verified,action,country,device,transport,proof,detail,ip,network`, the last two filled on Team Pro and Team Enterprise); JSON with `format=json` (events carry `ip` and `network` on those plans). Proof older than 90 days is left empty, and a note says why.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Any link of the send (its first link or any other); a single-file send is a send of one.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "`csv` (the default) or `json`.", "schema": { "anyOf": [ { "const": "csv", "type": "string" }, { "const": "json", "type": "string" } ] } } ], "responses": { "200": { "description": "Download a send's audit report", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AuditReport" } } } }, "default": { "description": "An error: `invalid_format`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/transfer/pause": { "put": { "operationId": "putLinksByIdTransferPause", "tags": [ "links" ], "summary": "Pause every file of a send", "description": "Every file stops opening and downloading; recipients see \"Paused by the sender\". Safe to repeat. 409 `transfer_revoked` when every file is revoked.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Any link of the send (its first link or any other); a single-file send is a send of one.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pause every file of a send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferState" } } } }, "default": { "description": "An error: `not_found`, `transfer_revoked`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteLinksByIdTransferPause", "tags": [ "links" ], "summary": "Resume a paused send", "description": "Lifts your own pause; a Trust & Safety pause stays (`paused_by: \"trust\"`). Safe to repeat.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Any link of the send (its first link or any other); a single-file send is a send of one.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resume a paused send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferState" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/transfer/people": { "get": { "operationId": "getLinksByIdTransferPeople", "tags": [ "activity" ], "summary": "List who can open which file of a send", "description": "Everyone listed, verified or emailed, with each file's state for them. Public sends answer `manageable: false`: per-person control needs Verified or Only-them access.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Any link of the send (its first link or any other); a single-file send is a send of one.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List who can open which file of a send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferPeople" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/transfer/people/access": { "post": { "operationId": "postLinksByIdTransferPeopleAccess", "tags": [ "activity" ], "summary": "Set which files one person may open", "description": "Sets exactly the files `email` may open: `\"all\"`, or link ids of this send (the others are removed). It never widens access: a restore only gives back what you removed. Their emailed links stop working when they can open nothing. 409 `public_link` on a public send.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Any link of the send (its first link or any other); a single-file send is a send of one.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "files" ], "properties": { "email": { "minLength": 3, "maxLength": 320, "type": "string", "description": "The person's email." }, "files": { "anyOf": [ { "const": "all", "type": "string" }, { "maxItems": 500, "type": "array", "items": { "maxLength": 20, "type": "string" } } ], "description": "`\"all\"`, or link ids of this send." } } } } } }, "responses": { "200": { "description": "Set which files one person may open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonAccessResult" } } } }, "default": { "description": "An error: `not_found`, `public_link`, `invalid_email`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/transfer/revoke": { "post": { "operationId": "postLinksByIdTransferRevoke", "tags": [ "links" ], "summary": "Revoke every file of a send", "description": "Ends every file for good and frees storage (as revoking one link does). `storage` says what was freed, held on pooled storage, or kept (shared, under review, or in a restore window). Safe to repeat: `revoked_now` is 0 the second time.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Any link of the send (its first link or any other); a single-file send is a send of one.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoke every file of a send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRevoked" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/notification-channels": { "get": { "operationId": "getNotificationChannels", "tags": [ "notifications" ], "summary": "List your notification channels", "description": "The channels of the person who made the key (not your account's own email), oldest first, with masked targets, and this month's additions per kind. A key made before keys belonged to a person gets 403 `key_needs_reissue`.", "security": [ { "apiKey": [ "notifications.write" ] } ], "x-scope": "notifications.write", "responses": { "200": { "description": "List your notification channels", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "limits" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationChannel" } }, "limits": { "$ref": "#/components/schemas/NotificationChannelLimits" } } } } } }, "default": { "description": "An error: `key_needs_reissue`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postNotificationChannels", "tags": [ "notifications" ], "summary": "Add a notification channel", "description": "An email channel starts pending and gets a confirmation link. A webhook channel returns its signing `secret` once. Slack URLs must be on hooks.slack.com and Discord on discord.com; every URL must be https and public. Limited per month and by plan.", "security": [ { "apiKey": [ "notifications.write" ] } ], "x-scope": "notifications.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel", "name", "target" ], "properties": { "channel": { "maxLength": 12, "type": "string", "description": "`email`, `slack`, `discord`, `teams` or `webhook`." }, "name": { "minLength": 1, "maxLength": 120, "type": "string", "description": "Your label (120 characters at most)." }, "target": { "minLength": 3, "maxLength": 2048, "type": "string", "description": "An email address or an https webhook URL." } } } } } }, "responses": { "200": { "description": "Add a notification channel", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "secret": { "type": "string" }, "pending": { "const": true, "type": "boolean" } } } } } }, "default": { "description": "An error: `key_needs_reissue`, `invalid_request`, `monthly_limit`, `plan_limit`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/notification-channels/{id}": { "patch": { "operationId": "patchNotificationChannelsById", "tags": [ "notifications" ], "summary": "Rename, retarget or pause a channel", "description": "Changes the fields you send. A new email address gets a confirmation link and receives nothing until it's confirmed (`pending: true`). `active: true` turns a paused channel back on.", "security": [ { "apiKey": [ "notifications.write" ] } ], "x-scope": "notifications.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 120, "type": "string", "description": "Your label." }, "target": { "minLength": 3, "maxLength": 2048, "type": "string", "description": "A new address or URL." }, "active": { "type": "boolean", "description": "On or off." } } } } } }, "responses": { "200": { "description": "Rename, retarget or pause a channel", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "const": true, "type": "boolean" }, "pending": { "const": true, "type": "boolean" } } } } } }, "default": { "description": "An error: `key_needs_reissue`, `not_found`, `invalid_request`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteNotificationChannelsById", "tags": [ "notifications" ], "summary": "Remove a notification channel", "description": "Removes it for good. It still counts toward this month's additions.", "security": [ { "apiKey": [ "notifications.write" ] } ], "x-scope": "notifications.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Remove a notification channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "An error: `key_needs_reissue`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/notification-channels/{id}/test": { "post": { "operationId": "postNotificationChannelsByIdTest", "tags": [ "notifications" ], "summary": "Send a test notification", "description": "Sends a real test message. A pending email channel gets its confirmation link again instead (409 `unconfirmed`). A failed delivery answers 424 `delivery_failed`.", "security": [ { "apiKey": [ "notifications.write" ] } ], "x-scope": "notifications.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The channel's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Send a test notification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "An error: `key_needs_reissue`, `unconfirmed`, `delivery_failed`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/prepared-sends": { "post": { "operationId": "postPreparedSends", "tags": [ "links" ], "summary": "Ask the person to send files", "description": "For an assistant that can't reach the person's files (a hosted chat app): open `url` for the person — the MCP server does it with a URL elicitation. Signed in as the same account, they pick files and send them the way the Send page does; another account is refused. Poll GET /v1/prepared-sends/{id} for the links. Lasts an hour.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "maxLength": 500, "type": "string", "description": "What to send, shown to the person (500 characters)." }, "message": { "maxLength": 2000, "type": "string", "description": "The message for the recipients (2000 characters)." }, "emails": { "maxItems": 10, "type": "array", "items": { "format": "email", "maxLength": 320, "type": "string" }, "description": "Up to 10 recipients to email the links to." } } } } } }, "responses": { "201": { "description": "Ask the person to send files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedSend" } } } }, "default": { "description": "An error: `no_person`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/prepared-sends/{id}": { "get": { "operationId": "getPreparedSendsById", "tags": [ "links" ], "summary": "See whether the person sent the files", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The prepared send's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "See whether the person sent the files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedSend" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reports/transfers": { "get": { "operationId": "getReportsTransfers", "tags": [ "activity" ], "summary": "Report link activity over a period", "description": "Links created in the last `days` (1–90, 30 by default), the newest 200, with opens, views, downloads, sign-ups, bytes served and feedback over the same period.", "security": [ { "apiKey": [ "links.write" ] } ], "x-scope": "links.write", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "The period in days, 1–90 (30 by default).", "schema": { "minimum": 1, "maximum": 90, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 90, "type": "integer" } ] } } ], "responses": { "200": { "description": "Report link activity over a period", "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "totals", "data" ], "properties": { "period": { "type": "object", "required": [ "from", "to", "days" ], "properties": { "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" }, "days": { "type": "number" } } }, "totals": { "type": "object", "required": [ "links", "opens", "downloads", "views", "signups", "egress_bytes" ], "properties": { "links": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "opens": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "downloads": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "views": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "signups": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "egress_bytes": { "pattern": "^[0-9]+$", "type": "string" } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransferReportRow" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/search/indexing": { "get": { "operationId": "getSearchIndexing", "tags": [ "drive" ], "summary": "Search inside files: status and progress", "description": "For your own Drive and each team Drive you're on, when its plan searches inside files: the plan, a trial's cap, the documents searched inside now, and the latest backfill — the files already there when the plan started, read newest first. Backfills run first come, first served; `started_at` stays null while one waits its turn. A Drive without search inside files isn't listed.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "Search inside files: status and progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchIndexing" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/search/settings": { "get": { "operationId": "getSearchSettings", "tags": [ "drive" ], "summary": "Search settings of the Drives you manage", "description": "Your own Drive, and each team Drive whose team you own or administer, with its plan's search inside files: whether the plan offers **text in images** (OCR of photos, screenshots and scanned PDFs — the first 10 pages of each file, self-hosted) and whether it is on. A Drive without search inside files isn't listed.", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "responses": { "200": { "description": "Search settings of the Drives you manage", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SearchSettingsItem" } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "putSearchSettings", "tags": [ "drive" ], "summary": "Turn text in images on or off for a Drive", "description": "Opt-in, per Drive. On: the images and scanned PDFs already there are read newest first (the OCR backfill, first come first served, its progress in `GET /v1/search/indexing`), and new ones as they arrive; a trial reads 200 pages. Off: text read from images leaves search at once and is deleted after 30 days unless it's turned on again. Your own Drive by default; a team's Drive (`workspace` from `GET /v1/search/settings`) by its owner and admins. `403 plan_feature` when the plan doesn't offer it. Each change is on the audit log.", "security": [ { "apiKey": [ "drive.write" ] } ], "x-scope": "drive.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ocr" ], "properties": { "ocr": { "type": "boolean", "description": "On (true) or off (false)." }, "workspace": { "pattern": "^[0-9]{1,20}$", "type": "string", "description": "The Drive to change (from `GET /v1/search/settings`); default your own Drive." } } } } } }, "responses": { "200": { "description": "Turn text in images on or off for a Drive", "content": { "application/json": { "schema": { "type": "object", "required": [ "item", "changed", "backfill" ], "properties": { "item": { "$ref": "#/components/schemas/SearchSettingsItem" }, "changed": { "description": "False when it already was that way.", "type": "boolean" }, "backfill": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The OCR backfill reading what's already there (turned on).", "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/search/similar/{nodeId}": { "get": { "operationId": "getSearchSimilarByNodeId", "tags": [ "drive" ], "summary": "Find pictures that look like this one", "description": "Pictures in your Drive (and the team Drives and folders shared with you) that look like this one, compared by their image embeddings (SigLIP 2, made on our own servers; never a face or a person's identity, only how the whole picture looks). Only where the Drive's plan searches inside files (Drive 2 TB and up, every Team Drive plan). `similar` says what happened: `searched`; `not_a_picture` (a folder, or an end-to-end encrypted file: never read); `not_in_plan`; `no_vector` (this picture hasn't been processed yet); `unavailable` (search isn't answering: try again); `blocked_by_team` (an API key or app whose person's team doesn't let apps read file contents).", "security": [ { "apiKey": [ "drive.read" ] } ], "x-scope": "drive.read", "parameters": [ { "name": "nodeId", "in": "path", "required": true, "description": "The picture's id (a Drive file).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many, 1–24 (default 12).", "schema": { "pattern": "^[0-9]{1,2}$", "type": "string" } } ], "responses": { "200": { "description": "Find pictures that look like this one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarImages" } } } }, "default": { "description": "An error: `not_found`, `no_drive`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/team-inboxes/{ws}/members": { "get": { "operationId": "getTeamInboxesByWsMembers", "tags": [ "team-inboxes" ], "summary": "List a team inbox's members", "description": "Who is in a team inbox now (the people seated on its seats and groups, plus the team's owner and admins), and its access list: the seats and groups. The team's shared inbox has everyone.", "security": [ { "apiKey": [ "team_inboxes.write" ] } ], "x-scope": "team_inboxes.write", "parameters": [ { "name": "ws", "in": "path", "required": true, "description": "The inbox's id (GET /v1/plans/{id}/inboxes in the web app; the id in its address).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List a team inbox's members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInboxMembers" } } } }, "default": { "description": "An error: `forbidden`, `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "putTeamInboxesByWsMembers", "tags": [ "team-inboxes" ], "summary": "Replace who uses a team inbox", "description": "Replace a restricted inbox's access list with these seats, groups and people (an email names the seat its holder sits in, so access follows the seat when it changes hands). A list left out is left as it is. Members join or leave at once; anyone who leaves loses the inbox's sessions, and the files assigned to them go back to Unassigned. The shared inbox can't be changed (everyone is in it): 409 `shared_inbox`.", "security": [ { "apiKey": [ "team_inboxes.write" ] } ], "x-scope": "team_inboxes.write", "parameters": [ { "name": "ws", "in": "path", "required": true, "description": "The inbox's id (GET /v1/plans/{id}/inboxes in the web app; the id in its address).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seat_ids": { "maxItems": 1000, "type": "array", "items": { "pattern": "^\\d{1,20}$", "type": "string" }, "description": "Seats on the team." }, "group_ids": { "maxItems": 200, "type": "array", "items": { "pattern": "^\\d{1,20}$", "type": "string" }, "description": "The team's groups (Team settings → Groups): their seats as they are when someone opens the inbox." }, "emails": { "maxItems": 1000, "type": "array", "items": { "maxLength": 320, "type": "string" }, "description": "People seated on the team; one not seated is refused (422 `unknown_member`)." }, "base": { "type": "object", "properties": { "seat_ids": { "maxItems": 1000, "type": "array", "items": { "pattern": "^\\d{1,20}$", "type": "string" } }, "group_ids": { "maxItems": 200, "type": "array", "items": { "pattern": "^\\d{1,20}$", "type": "string" } } }, "description": "Optional: the access as your form showed it (`seat_ids`, `group_ids`). Then only who you added or removed since is applied over the access as it is now, so a seat or group someone else added meanwhile stays." } } } } } }, "responses": { "200": { "description": "Replace who uses a team inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInboxAccess" } } } }, "default": { "description": "An error: `forbidden`, `not_found`, `shared_inbox`, `unknown_member`, `unknown_seat`, `unknown_group`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/transfers": { "post": { "operationId": "postTransfers", "tags": [ "transfers" ], "summary": "Start an upload", "description": "Returns presigned multipart upload URLs: `PUT` each `part_size` slice of the file (the last one shorter) to `part_urls[n]`, then complete the upload within 24 hours. Refused before any URL is issued when the file, or the whole send (`transfer_total_bytes`), is over the plan's size cap, or when the workspace is out of storage. A paid plan over its storage quota answers 413 `overage_requires_ad`, which a key can't satisfy.", "security": [ { "apiKey": [ "transfers.write" ] } ], "x-scope": "transfers.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "size" ], "properties": { "name": { "maxLength": 255, "type": "string", "description": "The file name." }, "sealed_name": { "maxLength": 1024, "type": "string", "description": "End-to-end files: the real name sealed on your side with the link key (`sfm1..`, like `sealed_meta`, with additional data `name`). Send `name` as \"Encrypted file.\" (its extension alone): SendFlo stores that, keeping only the extension of whatever `name` says, and the link page shows the real name only in the recipient's browser. 422 `sealed_name_invalid`; such a file's link must be `encrypted` (422 `sealed_name_requires_e2e`)." }, "size": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ], "description": "The exact size in bytes; the finished upload must match." }, "expires_at": { "type": "string", "description": "The expiry you'll give its link (clamped to the plan); it picks the storage tier." }, "overage_ad": { "type": "boolean", "description": "For the signed-in app (an ad was watched to go over quota)." }, "overage_ad_nonce": { "maxLength": 64, "type": "string", "description": "For the signed-in app (the ad's credit)." }, "overage_ad_batch": { "maxLength": 64, "type": "string", "description": "For the signed-in app (one ad for a multi-file send)." }, "transfer_total_bytes": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ], "description": "The whole send's size, so an oversize send is refused before its first byte." }, "intent": { "type": "object", "properties": { "expires_at": { "type": "string" }, "max_downloads": { "anyOf": [ { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "type": "null" } ] }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "recipient_count": { "minimum": 0, "maximum": 1000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 1000, "type": "integer" } ] }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "preview_kind": { "anyOf": [ { "const": "image", "type": "string" }, { "const": "pdf", "type": "string" }, { "const": "video", "type": "string" }, { "const": "audio", "type": "string" }, { "type": "null" } ] }, "available_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "e2e": { "type": "boolean" } }, "description": "The link settings you'll use (expiry, downloads, access, recipients, delivery): they decide the storage tier." }, "origin": { "maxLength": 16, "type": "string", "description": "`watch` (a desktop watched folder), `agent` (files for an agent task) or `device` (the signed-in app: a device send kept for a device that's off, sealed); leave it out otherwise." }, "watch": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "minLength": 1, "maxLength": 64, "type": "string" }, "label": { "minLength": 1, "maxLength": 1024, "type": "string" }, "device_id": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ] }, "destination": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ] }, "delivery_id": { "anyOf": [ { "pattern": "^[0-9]{1,20}$", "type": "string" }, { "type": "null" } ] } }, "description": "For `origin: watch`: the folder `{ id, label, device_id?, destination? }`." }, "approval": { "type": "object", "required": [ "id", "entry_id" ], "properties": { "id": { "pattern": "^[0-9]{1,20}$", "type": "string" }, "entry_id": { "minLength": 1, "maxLength": 40, "type": "string" } }, "description": "For the signed-in app (an upload for an approval request)." }, "file_keys": { "maxItems": 8, "type": "array", "items": { "type": "object", "required": [ "kind", "id", "version", "sealed" ], "properties": { "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "team_key", "type": "string" } ] }, "id": { "pattern": "^[0-9]{1,20}$", "type": "string" }, "version": { "minimum": 0, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "type": "integer" } ] }, "sealed": { "maxLength": 2048, "type": "string" } } }, "description": "For the signed-in app (identity-sealed files: a watched folder to your own computers, or a device send kept for a device that's off): the file's SFE2 key sealed to each recipient's current identity key, `{ kind: \"user\", id, version, sealed }`; needs `sealed_name`. 422 `file_keys_*`, 409 `recipient_key_changed`." } } } } } }, "responses": { "200": { "description": "Start an upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferCreated" } } } }, "default": { "description": "An error: `file_size_cap`, `transfer_size_cap`, `approval_upload_refused`, `overage_requires_ad`, `storage_quota_exceeded`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/transfers/{id}/complete": { "post": { "operationId": "postTransfersByIdComplete", "tags": [ "transfers" ], "summary": "Complete an upload", "description": "Finishes the upload (the storage provider's own part list decides; send `parts: []`), stores the file and queues its malware scan. Use the returned `file_id` with POST /v1/links. A stored size that differs from the declared one aborts the upload (413 `size_mismatch`).", "security": [ { "apiKey": [ "transfers.write" ] } ], "x-scope": "transfers.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The upload's id from POST /v1/transfers.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parts" ], "properties": { "parts": { "type": "array", "items": { "type": "object", "required": [ "part_number", "etag" ], "properties": { "part_number": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, "etag": { "type": "string" } } }, "description": "Required but not read: send `[]`." }, "blake3": { "type": "string", "description": "The file's BLAKE3 hash, if you have it." }, "client_ref": { "minLength": 1, "maxLength": 64, "type": "string", "description": "Your own reference for this upload (64 characters at most)." } } } } } }, "responses": { "200": { "description": "Complete an upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferCompleted" } } } }, "default": { "description": "An error: `not_found`, `not_open`, `not_staged`, `size_mismatch`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/usage": { "get": { "operationId": "getUsage", "tags": [ "account" ], "summary": "Get this month's usage and plan limits", "description": "Usage for the current calendar month (UTC) and the plan's limits. Byte counts are decimal strings. Direct device-to-device transfers are free and not capped.", "security": [ { "apiKey": [ "usage.read" ] } ], "x-scope": "usage.read", "responses": { "200": { "description": "Get this month's usage and plan limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhook-deliveries/{id}": { "get": { "operationId": "getWebhookDeliveriesById", "tags": [ "webhooks" ], "summary": "Read one delivery", "description": "One attempt from the delivery log: the request body SendFlo sent and your server's answer (its headers and first 2 KB).", "security": [ { "apiKey": [ "webhooks.read" ] } ], "x-scope": "webhooks.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A delivery's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Read one delivery", "content": { "application/json": { "schema": { "description": "`{ id, endpoint_kind, endpoint_id, event_id, event_type, attempt, ok, status_code, error, duration_ms, request: { body }, response: { headers, body_excerpt }, created_at }`" } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks": { "get": { "operationId": "getWebhooks", "tags": [ "webhooks" ], "summary": "List your webhook endpoints", "description": "Every registered endpoint, newest first, without its secret, with its last 24 hours of deliveries (`deliveries_24h`, `success_rate_24h`). A key needs `webhooks.read` (or `webhooks.write`). When a workspace's plan stops including webhooks (below Plus), its endpoints keep running for 30 days (`plan_pause_at`), with a notice and a reminder, then pause (`plan_paused`) until an upgrade. Events during a pause are kept 30 days: replay them after upgrading. An endpoint pauses (`disabled: true`, `paused_at` set) after 5 events in a row whose every attempt failed — one bad event never pauses it — or at once when its address stops being public; you're told in the app and by email. Resume it with POST /v1/webhooks/:id/resume.", "security": [ { "apiKey": [ "webhooks.read" ] } ], "x-scope": "webhooks.read", "responses": { "200": { "description": "List your webhook endpoints", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "allowed" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "allowed": { "description": "This workspace's plan has webhooks (Plus, Pro, Enterprise, the API & Agents workspace).", "type": "boolean" } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "postWebhooks", "tags": [ "webhooks" ], "summary": "Register a webhook endpoint", "description": "The URL must be https and public (its name is resolved now; a private answer is refused). `events` are names from the event list below, a family such as `file.*`, or `*` for everything; an unknown name is refused (422 `unknown_event`). Deliveries are signed the Standard Webhooks way with `secret` (`whsec_…`), which is shown only now; see Webhooks above. The access events (`access.*`: opened, previewed, downloaded) are on Team Pro and Team Enterprise; with `team: true` the team's owner or an admin makes an endpoint that receives every member's.", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "maxLength": 2048, "type": "string", "description": "An https URL (2048 characters at most)." }, "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "maxLength": 64, "type": "string" }, "description": "The events to receive." }, "team": { "type": "boolean", "description": "Team Pro and Team Enterprise, the key's maker the team's owner or an admin: receive every member's events, not only this workspace's." }, "description": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "description": "What it's for (300 characters)." }, "filters": { "anyOf": [ { "type": "object", "properties": { "file_request_ids": { "maxItems": 50, "type": "array", "items": { "maxLength": 20, "type": "string" } }, "link_ids": { "maxItems": 50, "type": "array", "items": { "maxLength": 20, "type": "string" } }, "destination_ids": { "maxItems": 50, "type": "array", "items": { "maxLength": 20, "type": "string" } } } }, { "type": "null" } ], "description": "`{ file_request_ids?, link_ids?, destination_ids? }`: only events about these upload pages, links or destinations." }, "app": { "anyOf": [ { "const": "zapier", "type": "string" }, { "const": "make", "type": "string" }, { "const": "n8n", "type": "string" } ], "description": "The automation app subscribing it: zapier, make or n8n (shown on the Webhooks page)." } } } } } }, "responses": { "201": { "description": "Register a webhook endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "default": { "description": "An error: `invalid_url`, `unknown_event`, `plan_required`, `forbidden`, `webhooks_plan`, `webhook_limit`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/event-types": { "get": { "operationId": "getWebhooksEventTypes", "tags": [ "webhooks" ], "summary": "List the event types", "description": "Every event SendFlo sends: its family, payload version, what it means and when it is sent, and a sample of its `data` (exactly its schema; the same sample POST /v1/webhooks/:id/test sends). `team_only`: the access stream, Team Pro and Team Enterprise.", "security": [ { "apiKey": [ "webhooks.read" ] } ], "x-scope": "webhooks.read", "responses": { "200": { "description": "List the event types", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "family", "version", "summary", "when", "team_only", "sample" ], "properties": { "type": { "type": "string" }, "family": { "type": "string" }, "version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "summary": { "type": "string" }, "when": { "type": "string" }, "team_only": { "type": "boolean" }, "sample": { "description": "A sample of the event's data." } } } } } } } } }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}": { "patch": { "operationId": "patchWebhooksById", "tags": [ "webhooks" ], "summary": "Change a webhook endpoint", "description": "Change its address (checked like a new one), its events, a description, filters (`{ file_request_ids?, link_ids?, destination_ids? }`: only events about these), or `enabled` (true resumes a paused endpoint and clears its counts; false pauses it).", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "maxLength": 2048, "type": "string", "description": "An https, public URL." }, "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "maxLength": 64, "type": "string" }, "description": "The events to receive." }, "description": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "description": "What it's for (300 characters)." }, "filters": { "anyOf": [ { "type": "object", "properties": { "file_request_ids": { "maxItems": 50, "type": "array", "items": { "maxLength": 20, "type": "string" } }, "link_ids": { "maxItems": 50, "type": "array", "items": { "maxLength": 20, "type": "string" } }, "destination_ids": { "maxItems": 50, "type": "array", "items": { "maxLength": 20, "type": "string" } } } }, { "type": "null" } ], "description": "Only events about these upload pages, links or destinations; null clears them." }, "enabled": { "type": "boolean", "description": "On or off." } } } } } }, "responses": { "200": { "description": "Change a webhook endpoint", "content": { "application/json": { "schema": { "description": "The endpoint (WebhookEndpoint)." } } } }, "default": { "description": "An error: `not_found`, `invalid_url`, `unknown_event`, `nothing_to_change`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteWebhooksById", "tags": [ "webhooks" ], "summary": "Delete a webhook endpoint", "description": "Deliveries stop at once. Answers 204, also for an unknown id.", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Delete a webhook endpoint" }, "default": { "description": "An error `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "getWebhooksByIdDeliveries", "tags": [ "webhooks" ], "summary": "List an endpoint's deliveries", "description": "Every attempt of the last 30 days, newest first: the event, the status your server answered (or why none came: `timeout`, `dns`, `private_address`…), how long it took and the start of its answer. Each event is tried 6 times with growing waits; `attempt` 0 is a Resend.", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many (1–200, 50 by default).", "schema": { "minimum": 1, "maximum": 200, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "type": "integer" } ] } } ], "responses": { "200": { "description": "List an endpoint's deliveries", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/deliveries/{deliveryId}/resend": { "post": { "operationId": "postWebhooksByIdDeliveriesByDeliveryIdResend", "tags": [ "webhooks" ], "summary": "Resend a delivery", "description": "Sends the same body again with the same `webhook-id` (deduplicate on it), freshly signed. Queued: answers 202. 409 `body_not_kept` for a body too large to keep (over 64 KiB).", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's id.", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "A delivery from the log.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Resend a delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResent" } } } }, "default": { "description": "An error: `not_found`, `body_not_kept`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/replay": { "post": { "operationId": "postWebhooksByIdReplay", "tags": [ "webhooks" ], "summary": "Replay a window of events", "description": "Sends the endpoint again every event of a window (kept 30 days) it subscribes to, with the same event id and body, freshly signed: after an outage, or to catch up. `only_failed` skips events it already received. At most 1,000 events (422 `replay_too_large`). Queued: answers 202.", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "since" ], "properties": { "since": { "maxLength": 40, "type": "string", "description": "ISO time the window starts." }, "until": { "maxLength": 40, "type": "string", "description": "ISO time it ends (now by default)." }, "types": { "maxItems": 50, "type": "array", "items": { "maxLength": 64, "type": "string" }, "description": "Only these event types." }, "only_failed": { "type": "boolean", "description": "Only events this endpoint never received." } } } } } }, "responses": { "202": { "description": "Replay a window of events", "content": { "application/json": { "schema": { "type": "object", "required": [ "queued" ], "properties": { "queued": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "default": { "description": "An error: `not_found`, `invalid_window`, `replay_too_large`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/resume": { "post": { "operationId": "postWebhooksByIdResume", "tags": [ "webhooks" ], "summary": "Resume a paused endpoint", "description": "Turns a paused endpoint back on and clears its failure counts. Events from while it was paused aren't sent; Resend the ones you need from the delivery log.", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resume a paused endpoint", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "disabled", "paused_at", "failed_events" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "disabled": { "type": "boolean" }, "paused_at": { "type": "null" }, "failed_events": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "operationId": "postWebhooksByIdRotateSecret", "tags": [ "webhooks" ], "summary": "Rotate an endpoint's secret", "description": "A new `whsec_…` secret, shown only now. For 24 hours deliveries carry two signatures in `webhook-signature` (the new and the previous secret's), so you can switch your receiver without missing an event.", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate an endpoint's secret", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "secret", "previous_valid_until" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "secret": { "type": "string" }, "previous_valid_until": { "format": "date-time", "type": "string" } } } } } }, "default": { "description": "An error: `not_found`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/webhooks/{id}/test": { "post": { "operationId": "postWebhooksByIdTest", "tags": [ "webhooks" ], "summary": "Send a test event", "description": "Sends a sample of any event type (the documented example, exactly its schema; its id starts `evt_test_`) to the endpoint now, signed like any delivery and kept in its log. Queued: answers 202.", "security": [ { "apiKey": [ "webhooks.write" ] } ], "x-scope": "webhooks.write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "maxLength": 64, "type": "string", "description": "An event type (file_request.fulfilled by default)." } } } } } }, "responses": { "202": { "description": "Send a test event", "content": { "application/json": { "schema": { "type": "object", "required": [ "queued", "event_id", "type" ], "properties": { "queued": { "type": "boolean" }, "event_id": { "type": "string" }, "type": { "type": "string" } } } } } }, "default": { "description": "An error: `not_found`, `unknown_event`, or `unauthenticated` (401), `insufficient_scope` (403), `invalid_request` or `invalid_id` (422), `rate_limited` (429).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "webhooks": { "access.downloaded": { "post": { "operationId": "webhookAccessDownloaded", "tags": [ "webhooks" ], "summary": "A recipient downloaded a file", "description": "A download session ended — `details.complete` says whether every byte arrived. Team Pro and Team Enterprise only; a team-wide endpoint (`team: true`) receives every member's.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "access.downloaded" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/AccessEvent" } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "access.opened": { "post": { "operationId": "webhookAccessOpened", "tags": [ "webhooks" ], "summary": "A recipient opened a link", "description": "Someone opened a link's page (verified, emailed or anonymous). Team Pro and Team Enterprise only; a team-wide endpoint (`team: true`) receives every member's.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "access.opened" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/AccessEvent" } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "access.previewed": { "post": { "operationId": "webhookAccessPreviewed", "tags": [ "webhooks" ], "summary": "A recipient previewed a file", "description": "Someone viewed a file in the browser. Team Pro and Team Enterprise only; a team-wide endpoint (`team: true`) receives every member's.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "access.previewed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/AccessEvent" } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.canceled": { "post": { "operationId": "webhookAgentTaskCanceled", "tags": [ "webhooks" ], "summary": "A task was canceled", "description": "The task was canceled (`canceled`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.canceled" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task", "from", "actor" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "from": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "drive.item.added": { "post": { "operationId": "webhookDriveItemAdded", "tags": [ "webhooks" ], "summary": "A Drive file or folder was added", "description": "An upload finished or a folder was made in a space.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "drive.item.added" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "actor_user_id" ], "properties": { "item": { "$ref": "#/components/schemas/DriveItemV2" }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "drive.item.changed": { "post": { "operationId": "webhookDriveItemChanged", "tags": [ "webhooks" ], "summary": "A Drive file has a new version", "description": "Its content changed (an upload over it, a version restored).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "drive.item.changed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "actor_user_id" ], "properties": { "item": { "$ref": "#/components/schemas/DriveItemV2" }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "drive.item.renamed": { "post": { "operationId": "webhookDriveItemRenamed", "tags": [ "webhooks" ], "summary": "A Drive file or folder was renamed", "description": "Its name changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "drive.item.renamed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "actor_user_id" ], "properties": { "item": { "$ref": "#/components/schemas/DriveItemV2" }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "drive.item.moved": { "post": { "operationId": "webhookDriveItemMoved", "tags": [ "webhooks" ], "summary": "A Drive file or folder was moved", "description": "It went to another folder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "drive.item.moved" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "actor_user_id" ], "properties": { "item": { "$ref": "#/components/schemas/DriveItemV2" }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "drive.item.trashed": { "post": { "operationId": "webhookDriveItemTrashed", "tags": [ "webhooks" ], "summary": "A Drive file or folder went to the trash", "description": "Someone deleted it (it can be restored for the plan's days).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "drive.item.trashed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "actor_user_id" ], "properties": { "item": { "$ref": "#/components/schemas/DriveItemV2" }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "drive.item.restored": { "post": { "operationId": "webhookDriveItemRestored", "tags": [ "webhooks" ], "summary": "A Drive file or folder came back from the trash", "description": "Its owner restored it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "drive.item.restored" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "actor_user_id" ], "properties": { "item": { "$ref": "#/components/schemas/DriveItemV2" }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "drive.item.deleted": { "post": { "operationId": "webhookDriveItemDeleted", "tags": [ "webhooks" ], "summary": "A Drive file or folder was deleted for good", "description": "It left the trash for good (by hand, or its days ran out).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "drive.item.deleted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "actor_user_id" ], "properties": { "item": { "$ref": "#/components/schemas/DriveItemV2" }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "drive.shared": { "post": { "operationId": "webhookDriveShared", "tags": [ "webhooks" ], "summary": "A Drive file or folder was shared", "description": "Someone gave a person, an address, a group or the team access to it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "drive.shared" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "role", "grantee", "actor_user_id" ], "properties": { "item": { "$ref": "#/components/schemas/DriveItemV2" }, "role": { "type": "string" }, "grantee": { "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "email", "type": "string" }, { "const": "group", "type": "string" }, { "const": "team", "type": "string" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "actor_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "backup.device.added": { "post": { "operationId": "webhookBackupDeviceAdded", "tags": [ "webhooks" ], "summary": "A device started backing up", "description": "A computer, server, phone or external drive was added to a Backup plan.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "backup.device.added" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "device" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDeviceV2" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "backup.device.removed": { "post": { "operationId": "webhookBackupDeviceRemoved", "tags": [ "webhooks" ], "summary": "A device was removed from Backup", "description": "Its owner (or a team admin) removed it; its backups are kept until retention ends.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "backup.device.removed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "device" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDeviceV2" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "backup.snapshot.created": { "post": { "operationId": "webhookBackupSnapshotCreated", "tags": [ "webhooks" ], "summary": "A backup finished", "description": "A device's backup run made its snapshot.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "backup.snapshot.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "device", "snapshot" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDeviceV2" }, "snapshot": { "type": "object", "required": [ "id", "status", "trigger", "files", "bytes", "new_bytes", "started_at", "finished_at" ], "properties": { "id": { "type": "string" }, "status": { "anyOf": [ { "const": "complete", "type": "string" }, { "const": "partial", "type": "string" } ] }, "trigger": { "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "bytes": { "type": "string" }, "new_bytes": { "type": "string" }, "started_at": { "format": "date-time", "type": "string" }, "finished_at": { "format": "date-time", "type": "string" } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "backup.device.overdue": { "post": { "operationId": "webhookBackupDeviceOverdue", "tags": [ "webhooks" ], "summary": "A device stopped backing up", "description": "No backup for 72 hours (or three of its scheduled runs) — once per episode.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "backup.device.overdue" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "device", "error" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDeviceV2" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "backup.device.failing": { "post": { "operationId": "webhookBackupDeviceFailing", "tags": [ "webhooks" ], "summary": "A device's backup failed", "description": "Its last run stopped with an error — once per error.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "backup.device.failing" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "device", "error" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDeviceV2" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "backup.restore.ready": { "post": { "operationId": "webhookBackupRestoreReady", "tags": [ "webhooks" ], "summary": "A restore is ready", "description": "A ZIP of files from a backup was put together; it can be downloaded for 7 days.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "backup.restore.ready" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "restore" ], "properties": { "restore": { "type": "object", "required": [ "id", "device_id", "name", "files", "zip_bytes", "expires_at", "user_id" ], "properties": { "id": { "type": "string" }, "device_id": { "type": "string" }, "name": { "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "zip_bytes": { "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "user_id": { "type": "string" } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "backup.device.suspicious": { "post": { "operationId": "webhookBackupDeviceSuspicious", "tags": [ "webhooks" ], "summary": "A device's backup saw ransomware-like changes", "description": "Many files changed in an unusual way (rewritten unreadable, ransomware extensions or notes): nothing was uploaded and the device's backup paused until its owner resumes it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "backup.device.suspicious" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "device", "report" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDeviceV2" }, "report": { "type": "object", "required": [ "reason", "changed", "sample", "extensions" ], "properties": { "reason": { "type": "string" }, "changed": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "sample": { "type": "array", "items": { "type": "string" } }, "extensions": { "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.completed": { "post": { "operationId": "webhookAgentTaskCompleted", "tags": [ "webhooks" ], "summary": "A task completed", "description": "The task finished (`completed`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.completed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task", "from", "actor" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "from": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.created": { "post": { "operationId": "webhookAgentTaskCreated", "tags": [ "webhooks" ], "summary": "A task was sent to an agent", "description": "A task to an agent on a computer, or to a cloud agent, is created (not when one is run again).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.expired": { "post": { "operationId": "webhookAgentTaskExpired", "tags": [ "webhooks" ], "summary": "A task expired", "description": "Nobody took the task in time (`expired`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.expired" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task", "from", "actor" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "from": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.failed": { "post": { "operationId": "webhookAgentTaskFailed", "tags": [ "webhooks" ], "summary": "A task failed", "description": "The task failed (`failed`): the agent's error, a refused URL, or no progress.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task", "from", "actor" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "from": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.needs_approval": { "post": { "operationId": "webhookAgentTaskNeedsApproval", "tags": [ "webhooks" ], "summary": "A task waits for approval", "description": "The computer's owner must approve the task first (`awaiting_approval`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.needs_approval" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task", "from", "actor" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "from": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.needs_input": { "post": { "operationId": "webhookAgentTaskNeedsInput", "tags": [ "webhooks" ], "summary": "The agent asked a question", "description": "The task waits for an answer (`input_required`); `task.question` holds it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.needs_input" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task", "from", "actor" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "from": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.rejected": { "post": { "operationId": "webhookAgentTaskRejected", "tags": [ "webhooks" ], "summary": "A task was declined", "description": "The computer's owner declined the task, or its files (`rejected`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.rejected" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task", "from", "actor" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "from": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "agent_task.started": { "post": { "operationId": "webhookAgentTaskStarted", "tags": [ "webhooks" ], "summary": "The agent took a task", "description": "The task is handed to the agent (`handed_off`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "agent_task.started" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "task", "from", "actor" ], "properties": { "task": { "$ref": "#/components/schemas/AgentTask" }, "from": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "credits.low": { "post": { "operationId": "webhookCreditsLow", "tags": [ "webhooks" ], "summary": "The credit balance is low", "description": "A credit-billed workspace drops to 500 credits or less; once, until the balance goes back above 500.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "credits.low" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "balance", "threshold" ], "properties": { "balance": { "description": "Credits, as a decimal string (can be negative).", "type": "string" }, "threshold": { "type": "string" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "credits.topped_up": { "post": { "operationId": "webhookCreditsToppedUp", "tags": [ "webhooks" ], "summary": "Credits were added", "description": "A credit pack bought for the API & Agents workspace is paid.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "credits.topped_up" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "amount", "balance", "cents", "transaction_id" ], "properties": { "amount": { "description": "Credits added.", "type": "string" }, "balance": { "type": "string" }, "cents": { "description": "The pack's price in US cents, before tax.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "The pack's price in US cents, before tax.", "type": "integer" } ] }, "transaction_id": { "description": "Paddle's transaction id (it's on the receipt).", "type": "string" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "destination.delivered": { "post": { "operationId": "webhookDestinationDelivered", "tags": [ "webhooks" ], "summary": "A file arrived at a destination", "description": "A file is delivered to a team destination that notifies on arrival.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "destination.delivered" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "destination", "file_id", "file_name" ], "properties": { "destination": { "description": "The destination's slug.", "type": "string" }, "file_id": { "type": "string" }, "file_name": { "type": "string" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "feedback.approval.set": { "post": { "operationId": "webhookFeedbackApprovalSet", "tags": [ "webhooks" ], "summary": "A recipient approved a file or asked for changes", "description": "A recipient approves a file or asks for changes (withdrawing sends nothing).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "feedback.approval.set" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer", "file", "approval", "author" ], "properties": { "transfer": { "type": "object", "required": [ "id", "slug" ], "properties": { "id": { "description": "The send's first link.", "type": "string" }, "slug": { "type": "string" } } }, "file": { "type": "object", "required": [ "link_id", "slug", "name" ], "properties": { "link_id": { "type": "string" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "approval": { "anyOf": [ { "const": "approved", "type": "string" }, { "const": "changes", "type": "string" } ] }, "author": { "type": "object", "required": [ "name", "email", "proof" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "proof": { "anyOf": [ { "const": "account", "type": "string" }, { "const": "access", "type": "string" }, { "const": "email", "type": "string" } ] } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "feedback.comment.created": { "post": { "operationId": "webhookFeedbackCommentCreated", "tags": [ "webhooks" ], "summary": "A recipient commented", "description": "A recipient comments or replies on a send (not the sender's own comments).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "feedback.comment.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer", "file", "comment", "author" ], "properties": { "transfer": { "type": "object", "required": [ "id", "slug" ], "properties": { "id": { "description": "The send's first link.", "type": "string" }, "slug": { "type": "string" } } }, "file": { "type": "object", "required": [ "link_id", "slug", "name" ], "properties": { "link_id": { "type": "string" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "comment": { "type": "object", "required": [ "id", "parent_id", "body", "encrypted", "anchor", "created_at" ], "properties": { "id": { "type": "string" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "body": { "anyOf": [ { "description": "null on an end-to-end encrypted send.", "type": "string" }, { "type": "null" } ] }, "encrypted": { "type": "boolean" }, "anchor": { "anyOf": [ { "$ref": "#/components/schemas/FeedbackAnchor" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "author": { "type": "object", "required": [ "name", "email", "proof" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "proof": { "anyOf": [ { "const": "account", "type": "string" }, { "const": "access", "type": "string" }, { "const": "email", "type": "string" } ] } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "feedback.rating.set": { "post": { "operationId": "webhookFeedbackRatingSet", "tags": [ "webhooks" ], "summary": "A recipient rated a file", "description": "A recipient rates a file or changes the rating (clearing it sends nothing).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "feedback.rating.set" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer", "file", "rating", "author" ], "properties": { "transfer": { "type": "object", "required": [ "id", "slug" ], "properties": { "id": { "description": "The send's first link.", "type": "string" }, "slug": { "type": "string" } } }, "file": { "type": "object", "required": [ "link_id", "slug", "name" ], "properties": { "link_id": { "type": "string" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "rating": { "type": "object", "required": [ "value", "scale" ], "properties": { "value": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "scale": { "anyOf": [ { "const": "stars5", "type": "string" }, { "const": "score10", "type": "string" } ] } } }, "author": { "type": "object", "required": [ "name", "email", "proof" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "proof": { "anyOf": [ { "const": "account", "type": "string" }, { "const": "access", "type": "string" }, { "const": "email", "type": "string" } ] } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "feedback.transfer.approved": { "post": { "operationId": "webhookFeedbackTransferApproved", "tags": [ "webhooks" ], "summary": "Every file of a send is approved", "description": "An approval leaves every live file of the send approved with no change requests (sent again on each later approval while that holds).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "feedback.transfer.approved" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer", "files" ], "properties": { "transfer": { "type": "object", "required": [ "id", "slug" ], "properties": { "id": { "description": "The send's first link.", "type": "string" }, "slug": { "type": "string" } } }, "files": { "description": "The send's live files.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "The send's live files.", "type": "integer" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "file.flagged": { "post": { "operationId": "webhookFileFlagged", "tags": [ "webhooks" ], "summary": "The malware scan blocked a file", "description": "A file, a collection item or an agent task's result is blocked by the malware scan (on upload, the daily re-check or a rescan).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "file.flagged" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "file_id", "subject", "name", "severity", "signature", "whole_send_blocked" ], "properties": { "file_id": { "description": "The file's id (for `subject: agent`, the task's id).", "type": "string" }, "subject": { "anyOf": [ { "const": "file", "type": "string" }, { "const": "asset", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "drive", "type": "string" } ] }, "name": { "type": "string" }, "severity": { "anyOf": [ { "const": "low", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "high", "type": "string" }, { "const": "critical", "type": "string" } ] }, "signature": { "type": "string" }, "whole_send_blocked": { "type": "boolean" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "file.released": { "post": { "operationId": "webhookFileReleased", "tags": [ "webhooks" ], "summary": "A blocked file was marked safe", "description": "SendFlo staff, the owner or a team admin releases a blocked file.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "file.released" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "file_id", "subject", "name", "by", "reason" ], "properties": { "file_id": { "type": "string" }, "subject": { "anyOf": [ { "const": "file", "type": "string" }, { "const": "asset", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "drive", "type": "string" } ] }, "name": { "type": "string" }, "by": { "anyOf": [ { "const": "staff", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "team_admin", "type": "string" } ] }, "reason": { "type": "string" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "file_request.fulfilled": { "post": { "operationId": "webhookFileRequestFulfilled", "tags": [ "webhooks" ], "summary": "A file arrived on an upload page", "description": "Each file someone uploads through a file request or upload page, once its malware scan has finished (at most 2 minutes after it arrived; `scan` says which). Also sent to the page's own `notify.webhook_url`, and to a team's team-wide endpoints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "file_request.fulfilled" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "file_request_id", "slug", "link", "file", "inbox_item_id", "from", "from_email", "answers", "answers_v2", "contact", "submission_id", "retention_days", "expires_at", "ad_supported", "url", "scan" ], "properties": { "file_request_id": { "type": "string" }, "slug": { "type": "string" }, "link": { "type": "object", "required": [ "id", "name", "kind" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "request", "type": "string" }, { "const": "reception", "type": "string" } ] } } }, "file": { "type": "object", "required": [ "id", "name", "size" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "size": { "description": "Bytes, as a decimal string.", "type": "string" } } }, "inbox_item_id": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "from_email": { "anyOf": [ { "description": "The uploader's verified email on Verified and Only-them pages.", "type": "string" }, { "type": "null" } ] }, "answers": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } } } }, "answers_v2": { "description": "The same answers typed (DZ4). `answers` keeps them as text.", "type": "array", "items": { "type": "object", "required": [ "id", "label", "type", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "description": "short_text, long_text, email, number, date, multiple_choice, opinion_scale, phone, yes_no or consent.", "type": "string" }, "value": { "description": "The answer as its type: text, a number, a YYYY-MM-DD day, a list of choices (several answers), true/false (yes/no), or { agreed: true, at } (consent)." } } } }, "contact": { "anyOf": [ { "type": "object", "required": [ "name", "email", "email_verified" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" } } }, { "type": "null" } ] }, "submission_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retention_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "expires_at": { "format": "date-time", "type": "string" }, "ad_supported": { "type": "boolean" }, "url": { "description": "The received file in SendFlo.", "type": "string" }, "scan": { "description": "The file's scan when the event was sent. `pending`: still being checked after 2 minutes (a rejection after that comes as `file_request.rejected`).", "type": "object", "required": [ "state", "severity", "signature" ], "properties": { "state": { "anyOf": [ { "const": "clean", "type": "string" }, { "const": "flagged", "type": "string" }, { "const": "released", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "not_scannable", "type": "string" }, { "const": "pending", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "deleted", "type": "string" } ] }, "severity": { "anyOf": [ { "description": "low, medium, high or critical — for flagged and rejected files.", "type": "string" }, { "type": "null" } ] }, "signature": { "anyOf": [ { "description": "What the scanner found, for flagged and rejected files.", "type": "string" }, { "type": "null" } ] } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "file_request.rejected": { "post": { "operationId": "webhookFileRequestRejected", "tags": [ "webhooks" ], "summary": "A file uploaded to a page was rejected", "description": "Malware scanning flagged a file uploaded to a page set to reject such files: it was deleted and doesn't count toward the page's limits. Sent instead of `file_request.fulfilled`, or after it when the scan finished later. Also sent to the page's own webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "file_request.rejected" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "file_request_id", "slug", "link", "file", "inbox_item_id", "from", "from_email", "submission_id", "url", "scan" ], "properties": { "file_request_id": { "type": "string" }, "slug": { "type": "string" }, "link": { "type": "object", "required": [ "id", "name", "kind" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "request", "type": "string" }, { "const": "reception", "type": "string" } ] } } }, "file": { "type": "object", "required": [ "id", "name", "size" ], "properties": { "id": { "anyOf": [ { "description": "null: the file is deleted.", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "size": { "type": "string" } } }, "inbox_item_id": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "submission_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "scan": { "description": "The file's scan when the event was sent. `pending`: still being checked after 2 minutes (a rejection after that comes as `file_request.rejected`).", "type": "object", "required": [ "state", "severity", "signature" ], "properties": { "state": { "anyOf": [ { "const": "clean", "type": "string" }, { "const": "flagged", "type": "string" }, { "const": "released", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "not_scannable", "type": "string" }, { "const": "pending", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "deleted", "type": "string" } ] }, "severity": { "anyOf": [ { "description": "low, medium, high or critical — for flagged and rejected files.", "type": "string" }, { "type": "null" } ] }, "signature": { "anyOf": [ { "description": "What the scanner found, for flagged and rejected files.", "type": "string" }, { "type": "null" } ] } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "file_request.submission_completed": { "post": { "operationId": "webhookFileRequestSubmissionCompleted", "tags": [ "webhooks" ], "summary": "An upload to a page is complete", "description": "Once per upload (all the files someone sent together), after every file's `file_request.fulfilled` or `file_request.rejected`: when the last file arrived, or 10 minutes after the latest one if the rest never came. Also sent to the page's own webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "file_request.submission_completed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "submission_id", "file_request_id", "slug", "link", "from", "from_email", "contact", "answers", "answers_v2", "files", "counts", "url" ], "properties": { "submission_id": { "type": "string" }, "file_request_id": { "type": "string" }, "slug": { "type": "string" }, "link": { "type": "object", "required": [ "id", "name", "kind" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "request", "type": "string" }, { "const": "reception", "type": "string" } ] } } }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "required": [ "name", "email", "email_verified" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" } } }, { "type": "null" } ] }, "answers": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } } } }, "answers_v2": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": {} } } }, "files": { "type": "array", "items": { "type": "object", "required": [ "inbox_item_id", "file_id", "name", "size", "scan", "url" ], "properties": { "inbox_item_id": { "type": "string" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "size": { "type": "string" }, "scan": { "description": "The file's scan when the event was sent. `pending`: still being checked after 2 minutes (a rejection after that comes as `file_request.rejected`).", "type": "object", "required": [ "state", "severity", "signature" ], "properties": { "state": { "anyOf": [ { "const": "clean", "type": "string" }, { "const": "flagged", "type": "string" }, { "const": "released", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "not_scannable", "type": "string" }, { "const": "pending", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "deleted", "type": "string" } ] }, "severity": { "anyOf": [ { "description": "low, medium, high or critical — for flagged and rejected files.", "type": "string" }, { "type": "null" } ] }, "signature": { "anyOf": [ { "description": "What the scanner found, for flagged and rejected files.", "type": "string" }, { "type": "null" } ] } } }, "url": { "type": "string" } } } }, "counts": { "type": "object", "required": [ "files", "rejected", "checking" ], "properties": { "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "rejected": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "checking": { "description": "Files still being checked.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Files still being checked.", "type": "integer" } ] } } }, "url": { "type": "string" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "key.anomaly": { "post": { "operationId": "webhookKeyAnomaly", "tags": [ "webhooks" ], "summary": "An API key or an app behaved abnormally", "description": "A key or an app the person allowed spends over 5,000 credits in an hour (the key is suspended, the app's access revoked) or fails over half of 20+ requests in an hour; once per key or app, kind and hour.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "key.anomaly" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "api_key_id", "kind", "detail", "suspended", "subject", "app_name" ], "properties": { "api_key_id": { "description": "The key's id, or for an app its grant's (Connected apps).", "type": "string" }, "kind": { "anyOf": [ { "const": "spend_velocity", "type": "string" }, { "const": "error_rate", "type": "string" }, { "const": "content_probe", "type": "string" } ] }, "detail": { "type": "string" }, "suspended": { "type": "boolean" }, "subject": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "app", "type": "string" } ] }, "app_name": { "anyOf": [ { "description": "The app's name, for an app.", "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "transfer.created": { "post": { "operationId": "webhookTransferCreated", "tags": [ "webhooks" ], "summary": "A transfer was sent", "description": "The first link of a send exists (one file, or the first of a bundle).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "transfer.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer" ], "properties": { "transfer": { "$ref": "#/components/schemas/WebhookTransfer" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "transfer.completed": { "post": { "operationId": "webhookTransferCompleted", "tags": [ "webhooks" ], "summary": "A transfer is complete", "description": "Every file of the send is stored and its links exist: no new file joined the send for 30 seconds.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "transfer.completed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer" ], "properties": { "transfer": { "$ref": "#/components/schemas/WebhookTransfer" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "transfer.paused": { "post": { "operationId": "webhookTransferPaused", "tags": [ "webhooks" ], "summary": "A transfer was paused", "description": "The sender (or their team) paused the whole send.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "transfer.paused" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer" ], "properties": { "transfer": { "$ref": "#/components/schemas/WebhookTransfer" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "transfer.resumed": { "post": { "operationId": "webhookTransferResumed", "tags": [ "webhooks" ], "summary": "A paused transfer was resumed", "description": "The sender resumed it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "transfer.resumed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer" ], "properties": { "transfer": { "$ref": "#/components/schemas/WebhookTransfer" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "transfer.revoked": { "post": { "operationId": "webhookTransferRevoked", "tags": [ "webhooks" ], "summary": "A transfer was revoked", "description": "Every file of the send was revoked (by the sender, a takedown or a policy).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "transfer.revoked" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer" ], "properties": { "transfer": { "$ref": "#/components/schemas/WebhookTransfer" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "transfer.expired": { "post": { "operationId": "webhookTransferExpired", "tags": [ "webhooks" ], "summary": "A transfer expired", "description": "The send's last live link expired.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "transfer.expired" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer" ], "properties": { "transfer": { "$ref": "#/components/schemas/WebhookTransfer" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "link.created": { "post": { "operationId": "webhookLinkCreated", "tags": [ "webhooks" ], "summary": "A link was created", "description": "A link to a file exists (each file of a send has one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "link.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/WebhookLink" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "link.opened": { "post": { "operationId": "webhookLinkOpened", "tags": [ "webhooks" ], "summary": "A link's page was opened", "description": "Someone opened the link's page (on every plan; the team `access.*` stream stays the audit-grade feed).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "link.opened" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "link", "who" ], "properties": { "link": { "$ref": "#/components/schemas/WebhookLink" }, "who": { "$ref": "#/components/schemas/WebhookWho" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "link.downloaded": { "post": { "operationId": "webhookLinkDownloaded", "tags": [ "webhooks" ], "summary": "A file was downloaded", "description": "A download through the link ended; `complete` says whether every byte arrived.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "link.downloaded" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "link", "who", "bytes", "complete" ], "properties": { "link": { "$ref": "#/components/schemas/WebhookLink" }, "who": { "$ref": "#/components/schemas/WebhookWho" }, "bytes": { "type": "string" }, "complete": { "type": "boolean" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "link.download_limit_reached": { "post": { "operationId": "webhookLinkDownloadLimitReached", "tags": [ "webhooks" ], "summary": "A link reached its download limit", "description": "The last allowed download was counted; the link answers 410 from now on.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "link.download_limit_reached" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "link", "max_downloads" ], "properties": { "link": { "$ref": "#/components/schemas/WebhookLink" }, "max_downloads": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "link.revoked": { "post": { "operationId": "webhookLinkRevoked", "tags": [ "webhooks" ], "summary": "A link was revoked", "description": "The link was revoked (by the sender, a takedown, a policy or open-once).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "link.revoked" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/WebhookLink" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "link.expired": { "post": { "operationId": "webhookLinkExpired", "tags": [ "webhooks" ], "summary": "A link expired", "description": "The link passed its expiry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "link.expired" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/WebhookLink" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "recipient.added": { "post": { "operationId": "webhookRecipientAdded", "tags": [ "webhooks" ], "summary": "Someone was added to a transfer", "description": "The sender emailed more people or replaced one (Restricted sends list them).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "recipient.added" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer", "email", "replaced" ], "properties": { "transfer": { "$ref": "#/components/schemas/WebhookTransfer" }, "email": { "type": "string" }, "replaced": { "anyOf": [ { "description": "The address they replaced.", "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "recipient.removed": { "post": { "operationId": "webhookRecipientRemoved", "tags": [ "webhooks" ], "summary": "Someone's access was removed", "description": "The sender removed a person from some or all of a send's files.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "recipient.removed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transfer", "email", "link_ids" ], "properties": { "transfer": { "$ref": "#/components/schemas/WebhookTransfer" }, "email": { "type": "string" }, "link_ids": { "type": "array", "items": { "type": "string" } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "file_request.created": { "post": { "operationId": "webhookFileRequestCreated", "tags": [ "webhooks" ], "summary": "An upload page or request was created", "description": "A file request or reception link exists.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "file_request.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "file_request" ], "properties": { "file_request": { "$ref": "#/components/schemas/WebhookRequest" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "file_request.closed": { "post": { "operationId": "webhookFileRequestClosed", "tags": [ "webhooks" ], "summary": "A request was closed", "description": "A request got every file it asked for, or its owner closed it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "file_request.closed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "file_request", "reason" ], "properties": { "file_request": { "$ref": "#/components/schemas/WebhookRequest" }, "reason": { "anyOf": [ { "const": "fulfilled", "type": "string" }, { "const": "cancelled", "type": "string" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "file_request.expired": { "post": { "operationId": "webhookFileRequestExpired", "tags": [ "webhooks" ], "summary": "A request expired", "description": "A request or upload page passed its expiry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "file_request.expired" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "file_request" ], "properties": { "file_request": { "$ref": "#/components/schemas/WebhookRequest" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "inbox_item.received": { "post": { "operationId": "webhookInboxItemReceived", "tags": [ "webhooks" ], "summary": "A file was received", "description": "A file arrived in Received (an upload page, a request, a reply), before its scan settles.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "inbox_item.received" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/WebhookReceivedItem" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "inbox_item.ready": { "post": { "operationId": "webhookInboxItemReady", "tags": [ "webhooks" ], "summary": "A received file is ready", "description": "Its malware scan came back clean (or it can't be scanned: end-to-end).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "inbox_item.ready" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/WebhookReceivedItem" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "inbox_item.flagged": { "post": { "operationId": "webhookInboxItemFlagged", "tags": [ "webhooks" ], "summary": "A received file was flagged", "description": "Its malware scan flagged it; it can't be opened until released.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "inbox_item.flagged" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item", "severity", "signature" ], "properties": { "item": { "$ref": "#/components/schemas/WebhookReceivedItem" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "signature": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "inbox_item.released": { "post": { "operationId": "webhookInboxItemReleased", "tags": [ "webhooks" ], "summary": "A flagged file was released", "description": "Its owner (or a team admin) marked it safe.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "inbox_item.released" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/WebhookReceivedItem" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "inbox_item.viewed": { "post": { "operationId": "webhookInboxItemViewed", "tags": [ "webhooks" ], "summary": "A received file was previewed", "description": "Someone of the workspace previewed it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "inbox_item.viewed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/WebhookReceivedItem" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "inbox_item.downloaded": { "post": { "operationId": "webhookInboxItemDownloaded", "tags": [ "webhooks" ], "summary": "A received file was downloaded", "description": "Someone of the workspace downloaded it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "inbox_item.downloaded" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/WebhookReceivedItem" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "inbox_item.deleted": { "post": { "operationId": "webhookInboxItemDeleted", "tags": [ "webhooks" ], "summary": "A received file was deleted", "description": "Its owner deleted it, or it expired.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "inbox_item.deleted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/WebhookReceivedItem" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "intake.submitted": { "post": { "operationId": "webhookIntakeSubmitted", "tags": [ "webhooks" ], "summary": "Files arrived in a secure intake", "description": "An upload into the intake finished (its scan may still be running).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "intake.submitted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "intake" ], "properties": { "intake": { "$ref": "#/components/schemas/WebhookIntake" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "intake.ready": { "post": { "operationId": "webhookIntakeReady", "tags": [ "webhooks" ], "summary": "A secure intake is ready", "description": "Every file is stored and scanned clean, and no upload is still running: when bots and people should act.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "intake.ready" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "intake" ], "properties": { "intake": { "$ref": "#/components/schemas/WebhookIntake" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "intake.rejected": { "post": { "operationId": "webhookIntakeRejected", "tags": [ "webhooks" ], "summary": "A secure intake was rejected", "description": "The malware scan blocked a file it collected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "intake.rejected" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "intake", "reason" ], "properties": { "intake": { "$ref": "#/components/schemas/WebhookIntake" }, "reason": { "const": "scan", "type": "string" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "intake.expired": { "post": { "operationId": "webhookIntakeExpired", "tags": [ "webhooks" ], "summary": "A secure intake expired", "description": "It passed its expiry with nothing uploaded.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "intake.expired" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "intake" ], "properties": { "intake": { "$ref": "#/components/schemas/WebhookIntake" } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } }, "intake.handed_off": { "post": { "operationId": "webhookIntakeHandedOff", "tags": [ "webhooks" ], "summary": "A secure intake was handed to someone", "description": "A team member or group was given its files (when it became ready, or later).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "The event's id; the same on every retry (`sendflo-event-id`)." }, "type": { "type": "string", "const": "intake.handed_off" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "intake", "to" ], "properties": { "intake": { "$ref": "#/components/schemas/WebhookIntake" }, "to": { "type": "object", "required": [ "kind", "id", "permission" ], "properties": { "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "group", "type": "string" } ] }, "id": { "type": "string" }, "permission": { "anyOf": [ { "const": "view", "type": "string" }, { "const": "manage", "type": "string" } ] } } } } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer within 10 seconds, is retried (6 attempts with backoff)." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_…", "description": "An API key from Settings → Developer: `Authorization: Bearer sk_live_…`. Each key has scopes; an operation lists the one it needs." } }, "schemas": { "Problem": { "type": "object", "description": "An RFC 9457 problem document: the only error shape this API returns (`application/problem+json`).", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "description": "A stable URI for the error, ending in the `code`." }, "title": { "type": "string", "description": "A short, human-readable summary." }, "status": { "type": "integer", "description": "The HTTP status." }, "detail": { "type": "string", "description": "What happened and what to do, when there's more to say." }, "code": { "type": "string", "description": "The machine code: `not_found`, `insufficient_scope`, `rate_limited`…" } }, "additionalProperties": true }, "AccessEvent": { "type": "object", "required": [ "event_id", "occurred_at", "action", "outcome", "link_id", "file_id", "file_name", "sender_user_id", "recipient", "ip", "ip_source", "network", "country", "device", "session_id", "details" ], "properties": { "event_id": { "description": "The audit log's event id (UUIDv7) — the same row GET /v1/audit returns.", "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "action": { "anyOf": [ { "const": "LINK_OPENED", "type": "string" }, { "const": "FILE_PREVIEWED", "type": "string" }, { "const": "FILE_DOWNLOAD", "type": "string" } ] }, "outcome": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "denied", "type": "string" } ] }, "link_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sender_user_id": { "anyOf": [ { "description": "Who sent the link.", "type": "string" }, { "type": "null" } ] }, "recipient": { "type": "object", "required": [ "kind", "email", "verified", "user_id" ], "properties": { "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "recipient", "type": "string" }, { "const": "guest", "type": "string" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verified": { "description": "The address was proved with a code (or is a signed-in account's own).", "type": "boolean" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "ip": { "anyOf": [ { "description": "The client's address.", "type": "string" }, { "type": "null" } ] }, "ip_source": { "anyOf": [ { "anyOf": [ { "const": "cloudflare", "type": "string" }, { "const": "claimed", "type": "string" }, { "const": "direct", "type": "string" }, { "const": "internal", "type": "string" }, { "const": "none", "type": "string" } ] }, { "type": "null" } ] }, "network": { "anyOf": [ { "type": "object", "required": [ "asn", "org", "class" ], "properties": { "asn": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "org": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "class": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "country": { "anyOf": [ { "description": "ISO 3166-1 alpha-2.", "type": "string" }, { "type": "null" } ] }, "device": { "anyOf": [ { "description": "\"Safari · macOS\".", "type": "string" }, { "type": "null" } ] }, "session_id": { "anyOf": [ { "description": "The download session (downloads).", "type": "string" }, { "type": "null" } ] }, "details": { "description": "Bytes and whether the download completed, the preview kind, …", "type": "object", "patternProperties": { "^(.*)$": {} } } } }, "ActivityEvent": { "type": "object", "required": [ "id", "link_id", "file", "kind", "bytes", "recipient", "verified", "country", "transport", "device", "proof", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "file": { "type": "string" }, "kind": { "description": "open, view, download, restore, forward, comment, signup, access_off, access_on.", "type": "string" }, "bytes": { "pattern": "^[0-9]+$", "type": "string" }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verified": { "type": "boolean" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proof": { "anyOf": [ { "anyOf": [ { "const": "receipts", "type": "string" }, { "const": "handed_off", "type": "string" } ] }, { "type": "null" } ] }, "stamp_check": { "anyOf": [ { "const": "found", "type": "string" }, { "const": "missing", "type": "string" } ] }, "ip": { "anyOf": [ { "description": "Team Pro and Team Enterprise only: the client's address.", "type": "string" }, { "type": "null" } ] }, "network": { "anyOf": [ { "description": "Team Pro and Team Enterprise only: who owns the address's network, and its class.", "type": "object", "required": [ "org", "class" ], "properties": { "org": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "class": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "ActivityPerson": { "type": "object", "required": [ "key", "email", "label", "verified", "opened_at", "last_at", "files_total", "downloaded", "countries", "devices", "proof", "events" ], "properties": { "key": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "description": "The email, or \"Visitor N\" for someone who never gave one.", "type": "string" }, "verified": { "type": "boolean" }, "opened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "last_at": { "format": "date-time", "type": "string" }, "files_total": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "downloaded": { "type": "array", "items": { "type": "object", "required": [ "link_id", "name", "at", "proof" ], "properties": { "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "at": { "format": "date-time", "type": "string" }, "proof": { "anyOf": [ { "anyOf": [ { "const": "receipts", "type": "string" }, { "const": "handed_off", "type": "string" } ] }, { "type": "null" } ] } } } }, "countries": { "type": "array", "items": { "type": "string" } }, "devices": { "type": "array", "items": { "type": "string" } }, "proof": { "anyOf": [ { "anyOf": [ { "const": "receipts", "type": "string" }, { "const": "handed_off", "type": "string" } ] }, { "type": "null" } ] }, "events": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "ips": { "description": "Team Pro and Team Enterprise only: the addresses they came from.", "type": "array", "items": { "type": "string" } } } }, "AgentAccept": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" } }, "max_mb": { "type": "number" } } }, "AgentPreset": { "type": "object", "required": [ "id", "label", "instruction" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "instruction": { "type": "string" } } }, "AgentPublicKey": { "description": "The P-256 key a computer publishes; an end-to-end task's instruction is sealed to it.", "type": "object", "required": [ "kid", "jwk" ], "properties": { "kid": { "type": "string" }, "jwk": { "type": "object", "required": [ "kty", "crv", "x", "y" ], "properties": { "kty": { "const": "EC", "type": "string" }, "crv": { "const": "P-256", "type": "string" }, "x": { "type": "string" }, "y": { "type": "string" } } } } }, "AgentRoster": { "type": "object", "required": [ "device_id", "device_name", "platform", "online", "agents", "e2e", "public_key", "connector", "updated_at" ], "properties": { "device_id": { "pattern": "^[0-9]+$", "type": "string" }, "device_name": { "type": "string" }, "platform": { "type": "string" }, "online": { "type": "boolean" }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/RosterAgent" } }, "e2e": { "description": "The computer published a key, so instructions can be sealed to it.", "type": "boolean" }, "public_key": { "anyOf": [ { "$ref": "#/components/schemas/AgentPublicKey" }, { "type": "null" } ] }, "connector": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "string" }, "platform": { "type": "string" } } }, { "type": "null" } ] }, "updated_at": { "format": "date-time", "type": "string" } } }, "AgentTarget": { "anyOf": [ { "$ref": "#/components/schemas/ProjectAgentTarget" }, { "$ref": "#/components/schemas/CloudAgentTarget" } ] }, "AgentTask": { "description": "A task handed to an AI agent on a computer or in the cloud.", "type": "object", "required": [ "id", "state", "label", "target_kind", "agent", "device", "project_id", "cloud_agent_id", "session_ref", "from", "instruction", "instruction_encrypted", "preset", "voice_file", "files", "total_bytes", "reason", "detail", "question", "result", "policy", "device_transfer_id", "transfer_state", "cancel_requested", "retry_of", "role", "actions", "attempts", "created_at", "updated_at", "delivered_at", "started_at", "finished_at", "expires_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "state": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "canceled", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "expired", "type": "string" } ] }, "label": { "description": "The state in plain words (\"Done\", \"Needs your answer\"…).", "type": "string" }, "target_kind": { "anyOf": [ { "const": "device", "type": "string" }, { "const": "cloud", "type": "string" } ] }, "agent": { "type": "object", "required": [ "ref", "name", "runner" ], "properties": { "ref": { "type": "string" }, "name": { "type": "string" }, "runner": { "description": "folder, command, acp, channel, session, webhook, a2a, routine or pull.", "type": "string" } } }, "device": { "anyOf": [ { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "cloud_agent_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "session_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "from": { "type": "object", "required": [ "name", "user_id", "device_id" ], "properties": { "name": { "type": "string" }, "user_id": { "pattern": "^[0-9]+$", "type": "string" }, "device_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] } } }, "instruction": { "anyOf": [ { "description": "null when the instruction is sealed end to end, or the task uses only a preset or voice note.", "type": "string" }, { "type": "null" } ] }, "instruction_encrypted": { "type": "boolean" }, "preset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voice_file": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "name", "size" ], "properties": { "name": { "type": "string" }, "size": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "sha256": { "type": "string" }, "mime": { "type": "string" } } } }, "total_bytes": { "description": "Bytes, as a decimal string.", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "question": { "anyOf": [ { "$ref": "#/components/schemas/AgentTaskQuestion" }, { "type": "null" } ] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/AgentTaskResult" }, { "type": "null" } ] }, "policy": { "anyOf": [ { "type": "object", "properties": { "ask_first": { "type": "boolean" }, "direct_only": { "type": "boolean" }, "results": { "anyOf": [ { "const": "send", "type": "string" }, { "const": "keep", "type": "string" } ] } } }, { "type": "null" } ] }, "device_transfer_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "transfer_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancel_requested": { "type": "boolean" }, "retry_of": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "role": { "anyOf": [ { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "both", "type": "string" } ] }, { "type": "null" } ] }, "actions": { "description": "What you may do now.", "type": "array", "items": { "anyOf": [ { "const": "approve", "type": "string" }, { "const": "reject", "type": "string" }, { "const": "answer", "type": "string" }, { "const": "cancel", "type": "string" }, { "const": "retry", "type": "string" } ] } }, "attempts": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "delivered_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expires_at": { "format": "date-time", "type": "string" } } }, "AgentTaskEvent": { "type": "object", "required": [ "id", "at", "kind", "actor", "state", "message", "data" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "at": { "format": "date-time", "type": "string" }, "kind": { "anyOf": [ { "const": "state", "type": "string" }, { "const": "progress", "type": "string" }, { "const": "log", "type": "string" }, { "const": "question", "type": "string" }, { "const": "answer", "type": "string" }, { "const": "approval", "type": "string" }, { "const": "result", "type": "string" }, { "const": "error", "type": "string" }, { "const": "delivery", "type": "string" }, { "const": "control", "type": "string" } ] }, "actor": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" }, { "const": "server", "type": "string" }, { "const": "connector", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] }, "state": { "anyOf": [ { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "canceled", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "expired", "type": "string" } ] }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data": { "description": "Free-form JSON, or null." } } }, "AgentTaskQuestion": { "description": "The agent's open question (while the task waits for input or approval).", "type": "object", "required": [ "id", "kind", "text", "asked_at" ], "properties": { "id": { "type": "string" }, "kind": { "anyOf": [ { "const": "question", "type": "string" }, { "const": "permission", "type": "string" }, { "const": "approval", "type": "string" } ] }, "text": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" } } } }, "free_text": { "type": "boolean" }, "asked_at": { "format": "date-time", "type": "string" }, "answer": { "type": "object", "required": [ "by", "at" ], "properties": { "option_id": { "type": "string" }, "text": { "type": "string" }, "by": { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "owner", "type": "string" } ] }, "at": { "format": "date-time", "type": "string" } } } } }, "AgentTaskResult": { "type": "object", "required": [ "summary", "files", "kept_at", "expires_at" ], "properties": { "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "name", "size", "uploaded", "expired" ], "properties": { "name": { "type": "string" }, "size": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "uploaded": { "type": "boolean" }, "expired": { "description": "Deleted after the 7-day result window.", "type": "boolean" }, "url": { "description": "A 1-hour download URL (on a single task read), or the agent's own https link when `external`.", "type": "string" }, "external": { "const": true, "type": "boolean" }, "scan": { "type": "object", "required": [ "state", "labels" ], "properties": { "state": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } } } } } } }, "kept_at": { "anyOf": [ { "description": "Where results stay on the computer, when they aren't sent back.", "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "data": { "description": "Free-form JSON the agent returned." } } }, "AgentTaskRetryRef": { "type": "object", "required": [ "id", "state", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "state": { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "awaiting_approval", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "handed_off", "type": "string" }, { "const": "working", "type": "string" }, { "const": "input_required", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "canceled", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "expired", "type": "string" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "AuditEvent": { "type": "object", "required": [ "event_id", "occurred_at", "category", "action", "label", "outcome", "actor", "on_behalf_of", "ip", "ip_source", "network", "country", "target", "link_id", "file_id", "file_name", "owner_user_id", "device", "user_agent", "session_id", "api_key_id", "request_id", "workspace_id", "subscription_id", "details" ], "properties": { "event_id": { "description": "UUIDv7 — unique and time-ordered.", "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "category": { "type": "string" }, "action": { "description": "e.g. FILE_DOWNLOAD — see the catalogue.", "type": "string" }, "label": { "description": "The sentence a person reads after the actor's name: \"downloaded a file\".", "type": "string" }, "outcome": { "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" }, { "const": "denied", "type": "string" } ] }, "actor": { "type": "object", "required": [ "kind", "user_id", "email", "verified", "name" ], "properties": { "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "recipient", "type": "string" }, { "const": "guest", "type": "string" }, { "const": "api_key", "type": "string" }, { "const": "device", "type": "string" }, { "const": "staff", "type": "string" }, { "const": "system", "type": "string" } ] }, "user_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verified": { "description": "The address was proved (a code by email, or the account's own).", "type": "boolean" }, "name": { "anyOf": [ { "description": "\"SendFlo\" for the system, \"SendFlo staff\" for staff.", "type": "string" }, { "type": "null" } ] } } }, "on_behalf_of": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "ip": { "anyOf": [ { "description": "The client's address.", "type": "string" }, { "type": "null" } ] }, "ip_source": { "anyOf": [ { "anyOf": [ { "const": "cloudflare", "type": "string" }, { "const": "claimed", "type": "string" }, { "const": "direct", "type": "string" }, { "const": "internal", "type": "string" }, { "const": "none", "type": "string" } ] }, { "type": "null" } ] }, "network": { "anyOf": [ { "type": "object", "required": [ "asn", "org", "class" ], "properties": { "asn": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "org": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "class": { "anyOf": [ { "description": "residential, mobile, hosting, vpn, tor, proxy …", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "country": { "anyOf": [ { "description": "ISO 3166-1 alpha-2.", "type": "string" }, { "type": "null" } ] }, "target": { "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "link_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "file_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner_user_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "Who sent it (access events).", "type": "string" }, { "type": "null" } ] }, "device": { "type": "object", "required": [ "label", "id" ], "properties": { "label": { "anyOf": [ { "description": "\"Chrome · Windows\".", "type": "string" }, { "type": "null" } ] }, "id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] } } }, "user_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "api_key_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace_id": { "pattern": "^[0-9]+$", "type": "string" }, "subscription_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "details": { "description": "Bytes, reasons, the fields an edit changed …", "type": "object", "patternProperties": { "^(.*)$": {} } } } }, "AuditPage": { "type": "object", "required": [ "data", "next_cursor", "visibility" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visibility": { "anyOf": [ { "const": "own", "type": "string" }, { "const": "all", "type": "string" }, { "const": "staff", "type": "string" } ] } } }, "AuditReport": { "type": "object", "required": [ "transfer", "files", "people", "owner_actions", "events", "event_count", "notes" ], "properties": { "transfer": { "type": "object", "required": [ "id", "slug", "access", "created_at", "exported_at", "files", "allowed_emails" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "created_at": { "format": "date-time", "type": "string" }, "exported_at": { "format": "date-time", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowed_emails": { "type": "array", "items": { "type": "string" } } } }, "files": { "type": "array", "items": { "type": "object", "required": [ "link_id", "name", "slug", "created_at", "expires_at", "download_count", "max_downloads", "revoked_at", "paused_by", "paused_at" ], "properties": { "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "download_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "max_downloads": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paused_by": { "anyOf": [ { "anyOf": [ { "const": "sender", "type": "string" }, { "const": "safety review", "type": "string" } ] }, { "type": "null" } ] }, "paused_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } }, "people": { "type": "array", "items": { "type": "object", "required": [ "person", "email", "verified", "can_open", "downloaded", "first_opened_at", "last_at", "countries", "devices", "proof" ], "properties": { "person": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verified": { "type": "boolean" }, "can_open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "downloaded": { "type": "array", "items": { "type": "object", "required": [ "file", "at", "proof" ], "properties": { "file": { "type": "string" }, "at": { "format": "date-time", "type": "string" }, "proof": { "anyOf": [ { "anyOf": [ { "const": "receipts", "type": "string" }, { "const": "handed_off", "type": "string" } ] }, { "type": "null" } ] } } } }, "first_opened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "last_at": { "description": "ISO time, or \"\" for a listed person with no activity.", "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } }, "devices": { "type": "array", "items": { "type": "string" } }, "proof": { "anyOf": [ { "anyOf": [ { "const": "receipts", "type": "string" }, { "const": "handed_off", "type": "string" } ] }, { "type": "null" } ] } } } }, "owner_actions": { "type": "array", "items": { "type": "object", "required": [ "at", "file", "link_id", "action", "person" ], "properties": { "at": { "format": "date-time", "type": "string" }, "file": { "type": "string" }, "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "action": { "type": "string" }, "person": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "events": { "type": "array", "items": { "type": "object", "required": [ "at", "file", "link_id", "kind", "person", "verified", "bytes", "country", "device", "transport", "proof" ], "properties": { "at": { "format": "date-time", "type": "string" }, "file": { "type": "string" }, "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "kind": { "type": "string" }, "person": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verified": { "type": "boolean" }, "bytes": { "pattern": "^[0-9]+$", "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proof": { "anyOf": [ { "anyOf": [ { "const": "receipts", "type": "string" }, { "const": "handed_off", "type": "string" } ] }, { "type": "null" } ] } } } }, "event_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "notes": { "type": "array", "items": { "type": "string" } } } }, "BackupDevice": { "type": "object", "required": [ "id", "name", "kind", "os", "client", "client_version", "volume_serial", "status", "state", "progress", "paused", "key_mode", "suspicious", "changes_ok_until", "policy", "bytes", "files", "last_snapshot_id", "last_snapshot_at", "last_seen_at", "last_error", "last_error_at", "created_at", "mine", "user" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "kind": { "anyOf": [ { "const": "computer", "type": "string" }, { "const": "server", "type": "string" }, { "const": "phone", "type": "string" }, { "const": "volume", "type": "string" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "client": { "anyOf": [ { "const": "cli", "type": "string" }, { "const": "desktop", "type": "string" }, { "const": "phone", "type": "string" } ] }, "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "volume_serial": { "anyOf": [ { "description": "An external drive's volume serial (it reattaches by it).", "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "const": "ok", "type": "string" }, { "const": "running", "type": "string" }, { "const": "overdue", "type": "string" }, { "const": "failing", "type": "string" }, { "const": "paused", "type": "string" }, { "const": "pending", "type": "string" }, { "const": "suspicious", "type": "string" } ] }, "state": { "anyOf": [ { "const": "idle", "type": "string" }, { "const": "running", "type": "string" }, { "const": "error", "type": "string" } ] }, "progress": { "anyOf": [ { "description": "A run in progress, as the client reports it: phase, files_done, files_total, bytes_done, bytes_total.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "paused": { "type": "boolean" }, "key_mode": { "anyOf": [ { "const": "sendflo", "type": "string" }, { "const": "private", "type": "string" } ] }, "suspicious": { "anyOf": [ { "description": "Ransomware-like changes the client saw: the device is paused until its owner resumes it (It was me).", "type": "object", "required": [ "at" ], "properties": { "at": { "format": "date-time", "type": "string" }, "reason": { "type": "string" }, "changed": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "sample": { "type": "array", "items": { "type": "string" } } } }, { "type": "null" } ] }, "changes_ok_until": { "anyOf": [ { "format": "date-time", "description": "After It was me: the client backs up the changes without checking them again until this.", "type": "string" }, { "type": "null" } ] }, "policy": { "anyOf": [ { "description": "What the client backs up: paths, exclude, schedule_hours, max_file_bytes.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "bytes": { "pattern": "^[0-9]+$", "description": "What the last complete snapshot covers.", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "last_snapshot_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "last_snapshot_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "last_seen_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_error_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "mine": { "description": "It's the caller's own device (false: a team member's, seen by a team admin).", "type": "boolean" }, "user": { "type": "object", "required": [ "id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } } } }, "BackupDeviceRegistered": { "type": "object", "required": [ "device", "reattached", "plan" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDevice" }, "reattached": { "type": "boolean" }, "plan": { "$ref": "#/components/schemas/BackupPlan" } } }, "BackupDeviceRemoved": { "type": "object", "required": [ "removed", "kept_until" ], "properties": { "removed": { "const": true, "type": "boolean" }, "kept_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, "BackupDeviceResult": { "type": "object", "required": [ "device" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDevice" } } }, "BackupDeviceV2": { "type": "object", "required": [ "id", "name", "kind", "os", "user_id", "status", "last_snapshot_at", "bytes", "files" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "anyOf": [ { "const": "computer", "type": "string" }, { "const": "server", "type": "string" }, { "const": "phone", "type": "string" }, { "const": "volume", "type": "string" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "user_id": { "description": "Whose device it is.", "type": "string" }, "status": { "anyOf": [ { "description": "overdue or failing on those events.", "type": "string" }, { "type": "null" } ] }, "last_snapshot_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "bytes": { "description": "What its last backup covers.", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "BackupDeviceWithPlan": { "type": "object", "required": [ "device", "plan" ], "properties": { "device": { "$ref": "#/components/schemas/BackupDevice" }, "plan": { "$ref": "#/components/schemas/BackupPlan" }, "live_report_due": { "type": "boolean" } } }, "BackupFileChunks": { "type": "object", "required": [ "name", "size", "mtime", "chunks" ], "properties": { "name": { "type": "string" }, "size": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "mtime": { "format": "date-time", "type": "string" }, "chunks": { "type": "array", "items": { "type": "object", "required": [ "id", "url", "offset", "length", "compression" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "offset": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "length": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "compression": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "BackupFolder": { "type": "object", "required": [ "snapshot", "path", "entries" ], "properties": { "snapshot": { "$ref": "#/components/schemas/BackupSnapshot" }, "path": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "size", "mtime" ], "properties": { "name": { "type": "string" }, "type": { "anyOf": [ { "const": "file", "type": "string" }, { "const": "dir", "type": "string" }, { "const": "symlink", "type": "string" } ] }, "size": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "mtime": { "format": "date-time", "type": "string" }, "target": { "type": "string" } } } } } }, "BackupHave": { "type": "object", "required": [ "have" ], "properties": { "have": { "type": "array", "items": { "type": "string" } } } }, "BackupHeartbeat": { "type": "object", "required": [ "paused", "policy", "status" ], "properties": { "paused": { "type": "boolean" }, "policy": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "status": { "anyOf": [ { "const": "ok", "type": "string" }, { "const": "running", "type": "string" }, { "const": "overdue", "type": "string" }, { "const": "failing", "type": "string" }, { "const": "paused", "type": "string" }, { "const": "pending", "type": "string" }, { "const": "suspicious", "type": "string" } ] } } }, "BackupKeyPassphrase": { "type": "object", "required": [ "key_id", "created_at" ], "properties": { "key_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } }, "BackupKeys": { "type": "object", "required": [ "key_id", "keys" ], "properties": { "key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keys": { "type": "array", "items": { "type": "object", "required": [ "kind", "wrapped", "kdf", "key_id", "created_at" ], "properties": { "kind": { "anyOf": [ { "const": "passphrase", "type": "string" }, { "const": "recovery", "type": "string" } ] }, "wrapped": { "type": "string" }, "kdf": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "key_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "BackupKeysMade": { "type": "object", "required": [ "key_id", "keys" ], "properties": { "key_id": { "type": "string" }, "keys": { "type": "array", "items": { "type": "object", "required": [ "kind", "created_at" ], "properties": { "kind": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "BackupLiveReportBlobs": { "type": "object", "required": [ "added" ], "properties": { "added": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "BackupLiveReportDone": { "type": "object", "required": [ "report" ], "properties": { "report": { "type": "object", "required": [ "id", "state", "blobs" ], "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "blobs": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } }, "BackupLiveReportStart": { "type": "object", "required": [ "report", "snapshots" ], "properties": { "report": { "type": "object", "required": [ "id", "state" ], "properties": { "id": { "type": "string" }, "state": { "type": "string" } } }, "snapshots": { "type": "array", "items": { "type": "object", "required": [ "id", "root_tree" ], "properties": { "id": { "type": "string" }, "root_tree": { "type": "string" } } } } } }, "BackupLocate": { "type": "object", "required": [ "blobs" ], "properties": { "blobs": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "url", "offset", "length", "compression" ], "properties": { "id": { "type": "string" }, "kind": { "anyOf": [ { "const": "data", "type": "string" }, { "const": "tree", "type": "string" } ] }, "url": { "type": "string" }, "offset": { "pattern": "^[0-9]+$", "type": "string" }, "length": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "compression": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "BackupOverview": { "type": "object", "required": [ "plans", "devices" ], "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/BackupPlan" } }, "devices": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "kind", "os", "client", "client_version", "volume_serial", "status", "state", "progress", "paused", "key_mode", "suspicious", "changes_ok_until", "policy", "bytes", "files", "last_snapshot_id", "last_snapshot_at", "last_seen_at", "last_error", "last_error_at", "created_at", "mine", "user", "team_id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "kind": { "anyOf": [ { "const": "computer", "type": "string" }, { "const": "server", "type": "string" }, { "const": "phone", "type": "string" }, { "const": "volume", "type": "string" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "client": { "anyOf": [ { "const": "cli", "type": "string" }, { "const": "desktop", "type": "string" }, { "const": "phone", "type": "string" } ] }, "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "volume_serial": { "anyOf": [ { "description": "An external drive's volume serial (it reattaches by it).", "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "const": "ok", "type": "string" }, { "const": "running", "type": "string" }, { "const": "overdue", "type": "string" }, { "const": "failing", "type": "string" }, { "const": "paused", "type": "string" }, { "const": "pending", "type": "string" }, { "const": "suspicious", "type": "string" } ] }, "state": { "anyOf": [ { "const": "idle", "type": "string" }, { "const": "running", "type": "string" }, { "const": "error", "type": "string" } ] }, "progress": { "anyOf": [ { "description": "A run in progress, as the client reports it: phase, files_done, files_total, bytes_done, bytes_total.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "paused": { "type": "boolean" }, "key_mode": { "anyOf": [ { "const": "sendflo", "type": "string" }, { "const": "private", "type": "string" } ] }, "suspicious": { "anyOf": [ { "description": "Ransomware-like changes the client saw: the device is paused until its owner resumes it (It was me).", "type": "object", "required": [ "at" ], "properties": { "at": { "format": "date-time", "type": "string" }, "reason": { "type": "string" }, "changed": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "sample": { "type": "array", "items": { "type": "string" } } } }, { "type": "null" } ] }, "changes_ok_until": { "anyOf": [ { "format": "date-time", "description": "After It was me: the client backs up the changes without checking them again until this.", "type": "string" }, { "type": "null" } ] }, "policy": { "anyOf": [ { "description": "What the client backs up: paths, exclude, schedule_hours, max_file_bytes.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "bytes": { "pattern": "^[0-9]+$", "description": "What the last complete snapshot covers.", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "last_snapshot_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "last_snapshot_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "last_seen_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_error_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "mine": { "description": "It's the caller's own device (false: a team member's, seen by a team admin).", "type": "boolean" }, "user": { "type": "object", "required": [ "id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, "team_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] } } } } } }, "BackupPackCancelled": { "type": "object", "required": [ "cancelled" ], "properties": { "cancelled": { "const": true, "type": "boolean" } } }, "BackupPackDone": { "type": "object", "required": [ "pack_id", "size", "blobs" ], "properties": { "pack_id": { "pattern": "^[0-9]+$", "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "blobs": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "BackupPackParts": { "type": "object", "required": [ "part_urls" ], "properties": { "part_urls": { "type": "array", "items": { "type": "string" } } } }, "BackupPackStart": { "anyOf": [ { "type": "object", "required": [ "state", "pack_id" ], "properties": { "state": { "const": "done", "type": "string" }, "pack_id": { "pattern": "^[0-9]+$", "type": "string" } } }, { "type": "object", "required": [ "state", "upload_id", "part_size", "parts", "part_urls", "expires_at" ], "properties": { "state": { "const": "open", "type": "string" }, "upload_id": { "pattern": "^[0-9]+$", "type": "string" }, "part_size": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "parts": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "part_urls": { "description": "The first parts' URLs (64 at most).", "type": "array", "items": { "type": "string" } }, "expires_at": { "format": "date-time", "description": "Finish before this.", "type": "string" } } } ] }, "BackupPlan": { "type": "object", "required": [ "scope", "team_id", "team_name", "plan", "plan_name", "status", "writable", "bytes", "stored", "devices_limit", "devices_used", "version_days", "private_key", "manages", "team_policy" ], "properties": { "scope": { "anyOf": [ { "const": "personal", "type": "string" }, { "const": "team", "type": "string" } ] }, "team_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "team_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "plan": { "type": "string" }, "plan_name": { "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "trialing", "type": "string" }, { "const": "past_due", "type": "string" }, { "const": "read_only", "type": "string" } ] }, "writable": { "description": "False on a plan that ended: backups can be restored until deleted, nothing new is backed up.", "type": "boolean" }, "bytes": { "pattern": "^[0-9]+$", "description": "The room.", "type": "string" }, "stored": { "pattern": "^[0-9]+$", "description": "What the plan's packs take.", "type": "string" }, "devices_limit": { "anyOf": [ { "description": "Computers, servers and phones the plan covers (external drives don't count).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Computers, servers and phones the plan covers (external drives don't count).", "type": "integer" } ] }, { "type": "null" } ] }, "devices_used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "version_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "private_key": { "description": "The plan offers a private key (only you can read the backup).", "type": "boolean" }, "manages": { "description": "The caller sees and manages every device on the plan (a team's owner or admins).", "type": "boolean" }, "team_policy": { "anyOf": [ { "description": "A team's Backup policy (see GET /v1/backup/teams/:id/policy); null on a personal plan.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] } } }, "BackupRestore": { "type": "object", "required": [ "id", "device_id", "snapshot_id", "name", "state", "files", "bytes", "zip_bytes", "done_bytes", "paths", "error", "created_at", "finished_at", "expires_at", "downloaded_at", "user_id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "device_id": { "pattern": "^[0-9]+$", "type": "string" }, "snapshot_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "description": "The ZIP's name as downloaded.", "type": "string" }, "state": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "canceled", "type": "string" }, { "const": "expired", "type": "string" } ] }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "bytes": { "pattern": "^[0-9]+$", "description": "What the files hold.", "type": "string" }, "zip_bytes": { "pattern": "^[0-9]+$", "description": "The ZIP's exact size.", "type": "string" }, "done_bytes": { "pattern": "^[0-9]+$", "description": "How much of the ZIP is put together.", "type": "string" }, "paths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "A ready ZIP is deleted after this (7 days).", "type": "string" }, { "type": "null" } ] }, "downloaded_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "user_id": { "pattern": "^[0-9]+$", "description": "Who asked for it.", "type": "string" } } }, "BackupRestoreCanceled": { "type": "object", "required": [ "restore" ], "properties": { "restore": { "$ref": "#/components/schemas/BackupRestore" } } }, "BackupRestoreDownload": { "type": "object", "required": [ "url", "name", "size" ], "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" } } }, "BackupRestoreOne": { "type": "object", "required": [ "restore" ], "properties": { "restore": { "$ref": "#/components/schemas/BackupRestore" } } }, "BackupRestoreResult": { "type": "object", "required": [ "restore" ], "properties": { "restore": { "$ref": "#/components/schemas/BackupRestore" } } }, "BackupRestores": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "device_id", "snapshot_id", "name", "state", "files", "bytes", "zip_bytes", "done_bytes", "paths", "error", "created_at", "finished_at", "expires_at", "downloaded_at", "user_id", "device_name", "mine" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "device_id": { "pattern": "^[0-9]+$", "type": "string" }, "snapshot_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "description": "The ZIP's name as downloaded.", "type": "string" }, "state": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "canceled", "type": "string" }, { "const": "expired", "type": "string" } ] }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "bytes": { "pattern": "^[0-9]+$", "description": "What the files hold.", "type": "string" }, "zip_bytes": { "pattern": "^[0-9]+$", "description": "The ZIP's exact size.", "type": "string" }, "done_bytes": { "pattern": "^[0-9]+$", "description": "How much of the ZIP is put together.", "type": "string" }, "paths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "A ready ZIP is deleted after this (7 days).", "type": "string" }, { "type": "null" } ] }, "downloaded_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "user_id": { "pattern": "^[0-9]+$", "description": "Who asked for it.", "type": "string" }, "device_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mine": { "type": "boolean" } } } } } }, "BackupSnapshot": { "type": "object", "required": [ "id", "device_id", "root_tree", "status", "trigger", "started_at", "finished_at", "files", "dirs", "bytes", "new_bytes", "new_blobs", "paths", "skipped", "client_version" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "device_id": { "pattern": "^[0-9]+$", "type": "string" }, "root_tree": { "description": "The root tree blob's id: one entry per backed-up path, named by the full path.", "type": "string" }, "status": { "anyOf": [ { "const": "complete", "type": "string" }, { "const": "partial", "type": "string" } ] }, "trigger": { "anyOf": [ { "const": "first", "type": "string" }, { "const": "scheduled", "type": "string" }, { "const": "manual", "type": "string" } ] }, "started_at": { "format": "date-time", "type": "string" }, "finished_at": { "format": "date-time", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "dirs": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "bytes": { "pattern": "^[0-9]+$", "description": "Everything the snapshot covers.", "type": "string" }, "new_bytes": { "pattern": "^[0-9]+$", "description": "What this run newly stored.", "type": "string" }, "new_blobs": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "paths": { "type": "array", "items": { "type": "string" } }, "skipped": { "description": "Files the client couldn't read (path and reason).", "type": "array", "items": {} }, "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "BackupSnapshotResult": { "type": "object", "required": [ "snapshot" ], "properties": { "snapshot": { "$ref": "#/components/schemas/BackupSnapshot" } } }, "BackupSnapshots": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackupSnapshot" } } } }, "Brand": { "description": "A brand kit: what your download and upload pages show.", "type": "object", "required": [ "id", "name", "is_default", "logo_key", "wallpaper_key", "accent", "heading_color", "page_text", "link_url", "link_label", "thank_you_text", "appearance", "receipt", "sender_name", "reply_to", "reply_to_verified", "redirect_url", "favicon_key", "tab_title", "og_image_key", "og_title", "og_description", "font", "extra_wallpaper_keys", "video_key", "language", "texts", "logo_url", "wallpaper_url", "previews", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "logo_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "wallpaper_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "heading_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thank_you_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "appearance": { "anyOf": [ { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "light", "type": "string" }, { "const": "dark", "type": "string" } ] }, { "type": "null" } ] }, "receipt": { "type": "boolean" }, "sender_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reply_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reply_to_verified": { "description": "Replies go to `reply_to` only once it was confirmed with the code mailed to it.", "type": "boolean" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "favicon_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tab_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "og_image_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "og_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "og_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "font": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "extra_wallpaper_keys": { "type": "array", "items": { "type": "string" } }, "video_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "texts": { "anyOf": [ { "type": "object", "properties": { "heading": { "type": "string" }, "intro": { "type": "string" }, "button": { "type": "string" } } }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "description": "A preview URL, valid for 1 hour.", "type": "string" }, { "type": "null" } ] }, "wallpaper_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previews": { "type": "object", "required": [ "favicon_url", "og_image_url", "video_url", "extra_wallpaper_urls" ], "properties": { "favicon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "og_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "extra_wallpaper_urls": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } }, "Branding": { "description": "The default brand kit (the single-brand view).", "type": "object", "required": [ "brand_id", "logo_key", "wallpaper_key", "accent", "heading_color", "page_text", "link_url", "link_label", "logo_url", "wallpaper_url" ], "properties": { "brand_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logo_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "wallpaper_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "heading_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "wallpaper_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "CloudAgent": { "description": "A cloud agent (never its secret).", "type": "object", "required": [ "id", "name", "kind", "enabled", "config", "has_secret", "presets", "accept", "status", "created_at", "updated_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "kind": { "anyOf": [ { "const": "webhook", "type": "string" }, { "const": "a2a", "type": "string" }, { "const": "routine", "type": "string" }, { "const": "pull", "type": "string" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "required": [ "url", "endpoint", "protocol_version", "routine_id", "max_minutes" ], "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endpoint": { "anyOf": [ { "description": "A2A agents: resolved from the agent card.", "type": "string" }, { "type": "null" } ] }, "protocol_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routine_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "max_minutes": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] } } }, "has_secret": { "type": "boolean" }, "presets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPreset" } }, "accept": { "anyOf": [ { "$ref": "#/components/schemas/AgentAccept" }, { "type": "null" } ] }, "status": { "anyOf": [ { "$ref": "#/components/schemas/CloudAgentHealth" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } }, "CloudAgentHealth": { "description": "The agent's last health check.", "type": "object", "required": [ "ok", "at" ], "properties": { "ok": { "type": "boolean" }, "at": { "format": "date-time", "type": "string" }, "error": { "type": "string" }, "http": { "description": "Webhook agents: the HTTP status the test got.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Webhook agents: the HTTP status the test got.", "type": "integer" } ] }, "endpoint": { "description": "A2A agents: the endpoint from the agent card.", "type": "string" }, "protocol_version": { "anyOf": [ { "const": "1.0", "type": "string" }, { "const": "0.3", "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "push": { "type": "boolean" }, "skills": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "note": { "type": "string" } } }, "CloudAgentTarget": { "description": "One of the workspace's cloud agents.", "type": "object", "required": [ "kind", "id", "project_id", "cloud_agent_id", "name", "destination", "device", "agent", "binding", "available", "unavailable", "public_key", "health" ], "properties": { "kind": { "const": "cloud", "type": "string" }, "id": { "description": "cloud:", "type": "string" }, "project_id": { "type": "null" }, "cloud_agent_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "destination": { "type": "null" }, "device": { "type": "null" }, "agent": { "type": "object", "required": [ "ref", "name", "runner", "product", "status", "presets", "sessions", "accept", "policy" ], "properties": { "ref": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "runner": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "const": "ready", "type": "string" }, { "const": "busy", "type": "string" }, { "const": "paused", "type": "string" } ] }, { "type": "null" } ] }, "presets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPreset" } }, "sessions": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "live": { "type": "boolean" }, "last_active": { "format": "date-time", "type": "string" }, "source": { "type": "string" } } } }, "accept": { "anyOf": [ { "$ref": "#/components/schemas/AgentAccept" }, { "type": "null" } ] }, "policy": { "anyOf": [ { "type": "object", "properties": { "ask_first": { "type": "boolean" }, "permissions": { "anyOf": [ { "const": "ask", "type": "string" }, { "const": "allow", "type": "string" }, { "const": "deny", "type": "string" } ] }, "max_minutes": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "senders": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "team", "type": "string" } ] } } }, { "type": "null" } ] } } }, "binding": { "type": "null" }, "available": { "type": "boolean" }, "unavailable": { "anyOf": [ { "const": "agent_paused", "type": "string" }, { "type": "null" } ] }, "public_key": { "type": "null" }, "health": { "anyOf": [ { "$ref": "#/components/schemas/CloudAgentHealth" }, { "type": "null" } ] } } }, "CloudTaskClaim": { "type": "object", "required": [ "type", "api", "task", "callback", "task_state" ], "properties": { "type": { "const": "agent_task", "type": "string" }, "api": { "const": 1, "type": "number" }, "task": { "type": "object", "required": [ "id", "instruction", "preset", "files", "from", "created_at", "expires_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "instruction": { "type": "string" }, "preset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "name", "size", "mime", "url" ], "properties": { "name": { "type": "string" }, "size": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "description": "A download URL valid for 7 days.", "type": "string" } } } }, "from": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" } } }, "callback": { "type": "object", "required": [ "base", "token", "task", "events", "results", "complete" ], "properties": { "base": { "type": "string" }, "token": { "type": "string" }, "task": { "type": "string" }, "events": { "type": "string" }, "results": { "type": "string" }, "complete": { "type": "string" } } }, "task_state": { "anyOf": [ { "const": "handed_off", "type": "string" }, { "const": "queued", "type": "string" } ] } } }, "Credits": { "type": "object", "required": [ "balance", "prices" ], "properties": { "balance": { "pattern": "^-?[0-9]+$", "type": "string" }, "prices": { "type": "object", "required": [ "egressPerGb", "storagePerGbMonth", "relayPerGb", "turnPerGb", "fileRequest", "webhookDelivery" ], "properties": { "egressPerGb": { "type": "string" }, "storagePerGbMonth": { "type": "string" }, "relayPerGb": { "type": "string" }, "turnPerGb": { "type": "string" }, "fileRequest": { "type": "string" }, "webhookDelivery": { "type": "string" } } } } }, "DeviceLocation": { "type": "object", "required": [ "on", "share_team", "since", "mine", "team", "last", "history" ], "properties": { "on": { "type": "boolean" }, "share_team": { "type": "boolean" }, "since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "mine": { "type": "boolean" }, "team": { "anyOf": [ { "type": "object", "required": [ "id", "name", "shows" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shows": { "type": "boolean" } } }, { "type": "null" } ] }, "last": { "anyOf": [ { "type": "object", "required": [ "at", "lat", "lon", "accuracy_km", "city", "region", "country", "source" ], "properties": { "at": { "format": "date-time", "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "accuracy_km": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "const": "ip", "type": "string" }, { "const": "country", "type": "string" } ] } } }, { "type": "null" } ] }, "history": { "type": "array", "items": { "type": "object", "required": [ "at", "lat", "lon", "accuracy_km", "city", "region", "country", "source" ], "properties": { "at": { "format": "date-time", "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "accuracy_km": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "const": "ip", "type": "string" }, { "const": "country", "type": "string" } ] } } } } } }, "DeviceLocationSet": { "type": "object", "required": [ "on", "share_team", "since" ], "properties": { "on": { "type": "boolean" }, "share_team": { "type": "boolean" }, "since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, "DriveAutomation": { "type": "object", "required": [ "id", "folder_id", "name", "trigger", "subfolders", "conditions", "actions", "enabled", "created_by", "runs", "last_run_at", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "folder_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "trigger": { "anyOf": [ { "const": "added", "type": "string" }, { "const": "changed", "type": "string" }, { "const": "labeled", "type": "string" } ] }, "subfolders": { "type": "boolean" }, "conditions": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "actions": { "type": "array", "items": { "type": "object", "patternProperties": { "^(.*)$": {} } } }, "enabled": { "type": "boolean" }, "created_by": { "pattern": "^[0-9]+$", "type": "string" }, "runs": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "last_run_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "DriveChanges": { "type": "object", "required": [ "space_id", "cursor", "more", "changes" ], "properties": { "space_id": { "pattern": "^[0-9]+$", "type": "string" }, "cursor": { "type": "string" }, "more": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "required": [ "seq", "op", "node_id", "parent_id", "kind", "name", "version_id", "at", "meta" ], "properties": { "seq": { "type": "string" }, "op": { "anyOf": [ { "const": "create", "type": "string" }, { "const": "update", "type": "string" }, { "const": "rename", "type": "string" }, { "const": "move", "type": "string" }, { "const": "trash", "type": "string" }, { "const": "restore", "type": "string" }, { "const": "delete", "type": "string" } ] }, "node_id": { "pattern": "^[0-9]+$", "type": "string" }, "parent_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "folder", "type": "string" }, { "const": "file", "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "at": { "format": "date-time", "type": "string" }, "meta": {} } } } } }, "DriveComments": { "type": "object", "required": [ "comments", "can_task" ], "properties": { "comments": { "type": "array", "items": {} }, "can_task": { "type": "boolean" } } }, "DriveConflict": { "type": "object", "required": [ "id", "space_id", "space_name", "file", "copy", "path", "by", "client_name", "state", "resolution", "created_at", "resolved_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "space_id": { "pattern": "^[0-9]+$", "type": "string" }, "space_name": { "type": "string" }, "file": { "anyOf": [ { "description": "The file (a DriveNode), as it is now." }, { "type": "null" } ] }, "copy": { "anyOf": [ { "description": "The conflict copy (a DriveNode)." }, { "type": "null" } ] }, "path": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } } }, "by": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } }, "client_name": { "anyOf": [ { "description": "The computer whose save became the copy.", "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "resolved", "type": "string" } ] }, "resolution": { "anyOf": [ { "anyOf": [ { "const": "kept_file", "type": "string" }, { "const": "kept_copy", "type": "string" }, { "const": "kept_both", "type": "string" } ] }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, "DriveConflicts": { "type": "object", "required": [ "conflicts" ], "properties": { "conflicts": { "type": "array", "items": { "$ref": "#/components/schemas/DriveConflict" } } } }, "DriveDownload": { "type": "object", "required": [ "url", "name", "size", "mime", "version_id" ], "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version_id": { "pattern": "^[0-9]+$", "type": "string" } } }, "DriveFolder": { "type": "object", "required": [ "folder", "path", "items", "space", "plan", "role", "shared", "access", "team" ], "properties": { "folder": { "$ref": "#/components/schemas/DriveNode" }, "path": { "description": "From the top folder down to this one.", "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DriveNode" } }, "space": { "$ref": "#/components/schemas/DriveSpace" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/DrivePlan" }, { "type": "null" } ] }, "role": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "shared": { "anyOf": [ { "description": "Set when it's shared with you (null: it's yours).", "type": "object", "required": [ "role", "top_id", "owner" ], "properties": { "role": { "anyOf": [ { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "top_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The folder or file shared with you — the path starts there.", "type": "string" }, { "type": "null" } ] }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/DriveOwner" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "access": { "anyOf": [ { "type": "object", "required": [ "shares", "team" ], "properties": { "shares": { "description": "Shares that reach it (its own and from folders above).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Shares that reach it (its own and from folders above).", "type": "integer" } ] }, "team": { "type": "boolean" } } }, { "type": "null" } ] }, "team": { "anyOf": [ { "description": "A team space: its team and pool (P4d).", "type": "object", "required": [ "id", "name", "pool_used", "pool_bytes", "manages" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "pool_used": { "pattern": "^[0-9]+$", "description": "What every space of the team holds.", "type": "string" }, "pool_bytes": { "pattern": "^[0-9]+$", "description": "The team's pool.", "type": "string" }, "manages": { "type": "boolean" } } }, { "type": "null" } ] } } }, "DriveItemV2": { "type": "object", "required": [ "id", "kind", "name", "parent_id", "version_id", "space", "seq" ], "properties": { "id": { "type": "string" }, "kind": { "anyOf": [ { "const": "file", "type": "string" }, { "const": "folder", "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version_id": { "anyOf": [ { "description": "A file's version the change made (added / changed).", "type": "string" }, { "type": "null" } ] }, "space": { "type": "object", "required": [ "id", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "anyOf": [ { "const": "personal", "type": "string" }, { "const": "team", "type": "string" } ] } } }, "seq": { "description": "The change's place in the space's journal (GET /v1/drive/changes).", "type": "string" } } }, "DriveLink": { "type": "object", "required": [ "id", "node_id", "slug", "url", "mode", "version_id", "audience", "emails", "password", "delivery", "expires_at", "download_limit", "downloads", "share_id", "last_opened_at", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "node_id": { "pattern": "^[0-9]+$", "description": "The file or folder it opens.", "type": "string" }, "slug": { "type": "string" }, "url": { "description": "The page anyone it lets in opens: https://sendflo.app/d/.", "type": "string" }, "mode": { "anyOf": [ { "const": "latest", "type": "string" }, { "const": "version", "type": "string" } ] }, "version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "mode version: the version it serves.", "type": "string" }, { "type": "null" } ] }, "audience": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "emails": { "description": "restricted: the addresses that may open it (each confirms with a code).", "type": "array", "items": { "type": "string" } }, "password": { "type": "boolean" }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "download_limit": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "downloads": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "share_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "Set on the link made for an outside person's share (it goes with the share).", "type": "string" }, { "type": "null" } ] }, "last_opened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "DriveLinkResult": { "type": "object", "required": [ "link" ], "properties": { "link": { "$ref": "#/components/schemas/DriveLink" } } }, "DriveLinks": { "type": "object", "required": [ "links" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/DriveLink" } } } }, "DriveListing": { "type": "object", "required": [ "items", "plan", "space" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DriveNode" } }, "plan": { "$ref": "#/components/schemas/DrivePlan" }, "space": { "$ref": "#/components/schemas/DriveSpace" } } }, "DriveLockResult": { "type": "object", "required": [ "lock" ], "properties": { "lock": { "type": "object", "required": [ "user_id", "until", "mine" ], "properties": { "user_id": { "pattern": "^[0-9]+$", "type": "string" }, "until": { "format": "date-time", "type": "string" }, "mine": { "const": true, "type": "boolean" } } } } }, "DriveNode": { "type": "object", "required": [ "id", "parent_id", "kind", "name", "size", "mime", "content_hash", "versions", "modified_at", "updated_at", "created_at", "trashed_at", "purge_after", "seq", "version_id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "parent_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The folder it is in (null: the top folder itself).", "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "folder", "type": "string" }, { "const": "file", "type": "string" } ] }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "description": "The current version's size (0 for a folder).", "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_hash": { "anyOf": [ { "description": "BLAKE3 (hex) of the current version, as SendFlo computed it — null until it has been checked (seconds after an upload).", "type": "string" }, { "type": "null" } ] }, "versions": { "description": "Versions kept (the current one included).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Versions kept (the current one included).", "type": "integer" } ] }, "modified_at": { "format": "date-time", "description": "When the content last changed.", "type": "string" }, "updated_at": { "format": "date-time", "description": "When anything last changed (a rename, a move…).", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "trashed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "purge_after": { "anyOf": [ { "format": "date-time", "description": "In the trash: when it is deleted for good.", "type": "string" }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "seq": { "description": "The change that last touched it (see GET /v1/drive/changes).", "type": "string" }, "thumb_url": { "anyOf": [ { "description": "A thumbnail for images.", "type": "string" }, { "type": "null" } ] }, "inside": { "description": "Trash: how many items a trashed folder holds.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Trash: how many items a trashed folder holds.", "type": "integer" } ] }, "scan_state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "clean", "type": "string" }, { "const": "flagged", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "released", "type": "string" }, { "const": "not_scannable", "type": "string" }, { "const": "error", "type": "string" } ] }, "version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The current version (files): a sync client sends it back as `base_version_id` when it saves.", "type": "string" }, { "type": "null" } ] }, "lock": { "description": "Locked for editing: others' saves are refused until then (P6).", "type": "object", "required": [ "user_id", "name", "until", "mine" ], "properties": { "user_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "until": { "format": "date-time", "type": "string" }, "mine": { "type": "boolean" } } }, "conflict": { "description": "This file is a sync conflict's copy of `file_id` (P6).", "type": "object", "required": [ "id", "file_id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" } } } } }, "DriveNodeResult": { "type": "object", "required": [ "node" ], "properties": { "node": { "$ref": "#/components/schemas/DriveNode" } } }, "DriveNodeWithPath": { "type": "object", "required": [ "node", "path", "role", "shared", "access" ], "properties": { "node": { "$ref": "#/components/schemas/DriveNode" }, "path": { "description": "From the top folder down to this one.", "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } } }, "role": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "shared": { "anyOf": [ { "description": "Set when it's shared with you (null: it's yours).", "type": "object", "required": [ "role", "top_id", "owner" ], "properties": { "role": { "anyOf": [ { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "top_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The folder or file shared with you — the path starts there.", "type": "string" }, { "type": "null" } ] }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/DriveOwner" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "access": { "anyOf": [ { "type": "object", "required": [ "shares", "team" ], "properties": { "shares": { "description": "Shares that reach it (its own and from folders above).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Shares that reach it (its own and from folders above).", "type": "integer" } ] }, "team": { "type": "boolean" } } }, { "type": "null" } ] } } }, "DriveNote": { "type": "object", "required": [ "id", "name", "parent_id", "size", "version_id", "modified_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "parent_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "modified_at": { "format": "date-time", "type": "string" } } }, "DriveNotePresence": { "type": "object", "required": [ "client", "user_id", "name", "colour", "anchor", "head", "at" ], "properties": { "client": { "type": "string" }, "user_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "colour": { "type": "string" }, "anchor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "head": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "at": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "DriveOwner": { "type": "object", "required": [ "id", "name", "avatar_url" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "DriveParts": { "type": "object", "required": [ "version_id", "size", "part_size", "hashes" ], "properties": { "version_id": { "pattern": "^[0-9]+$", "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "part_size": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "hashes": { "type": "array", "items": { "description": "BLAKE3, hex.", "type": "string" } } } }, "DrivePeers": { "type": "object", "required": [ "peers" ], "properties": { "hash": { "description": "The version's BLAKE3.", "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "version_id": { "pattern": "^[0-9]+$", "type": "string" }, "off": { "const": true, "type": "boolean" }, "peers": { "type": "array", "items": { "type": "object", "required": [ "client_id", "addr", "port", "exp", "key" ], "properties": { "client_id": { "pattern": "^[0-9]+$", "type": "string" }, "addr": { "type": "string" }, "port": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "exp": { "description": "Unix seconds.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Unix seconds.", "type": "integer" } ] }, "key": { "description": "Hex, 32 bytes.", "type": "string" } } } } } }, "DrivePeople": { "type": "object", "required": [ "people" ], "properties": { "people": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "email", "avatar_url", "me" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "me": { "type": "boolean" } } } } } }, "DrivePlan": { "type": "object", "required": [ "plan", "name", "status", "writable", "bytes", "version_days" ], "properties": { "plan": { "type": "string" }, "name": { "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "trialing", "type": "string" }, { "const": "past_due", "type": "string" }, { "const": "read_only", "type": "string" } ] }, "writable": { "description": "False on a plan that ended: files can be read and downloaded until deleted, nothing new added.", "type": "boolean" }, "bytes": { "pattern": "^[0-9]+$", "description": "The room.", "type": "string" }, "version_days": { "description": "How long earlier versions and trashed items are kept.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "How long earlier versions and trashed items are kept.", "type": "integer" } ] } } }, "DriveRestored": { "type": "object", "required": [ "node", "path" ], "properties": { "node": { "$ref": "#/components/schemas/DriveNode" }, "path": { "description": "From the top folder down to this one.", "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } } } } }, "DriveSearch": { "type": "object", "required": [ "items", "search" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "parent_id", "kind", "name", "size", "mime", "content_hash", "versions", "modified_at", "updated_at", "created_at", "trashed_at", "purge_after", "seq", "version_id", "path", "space", "shared" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "parent_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The folder it is in (null: the top folder itself).", "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "folder", "type": "string" }, { "const": "file", "type": "string" } ] }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "description": "The current version's size (0 for a folder).", "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_hash": { "anyOf": [ { "description": "BLAKE3 (hex) of the current version, as SendFlo computed it — null until it has been checked (seconds after an upload).", "type": "string" }, { "type": "null" } ] }, "versions": { "description": "Versions kept (the current one included).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Versions kept (the current one included).", "type": "integer" } ] }, "modified_at": { "format": "date-time", "description": "When the content last changed.", "type": "string" }, "updated_at": { "format": "date-time", "description": "When anything last changed (a rename, a move…).", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "trashed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "purge_after": { "anyOf": [ { "format": "date-time", "description": "In the trash: when it is deleted for good.", "type": "string" }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "seq": { "description": "The change that last touched it (see GET /v1/drive/changes).", "type": "string" }, "thumb_url": { "anyOf": [ { "description": "A thumbnail for images.", "type": "string" }, { "type": "null" } ] }, "inside": { "description": "Trash: how many items a trashed folder holds.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Trash: how many items a trashed folder holds.", "type": "integer" } ] }, "scan_state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "clean", "type": "string" }, { "const": "flagged", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "released", "type": "string" }, { "const": "not_scannable", "type": "string" }, { "const": "error", "type": "string" } ] }, "version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The current version (files): a sync client sends it back as `base_version_id` when it saves.", "type": "string" }, { "type": "null" } ] }, "lock": { "description": "Locked for editing: others' saves are refused until then (P6).", "type": "object", "required": [ "user_id", "name", "until", "mine" ], "properties": { "user_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "until": { "format": "date-time", "type": "string" }, "mine": { "type": "boolean" } } }, "conflict": { "description": "This file is a sync conflict's copy of `file_id` (P6).", "type": "object", "required": [ "id", "file_id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" } } }, "path": { "description": "From the top folder down to this one.", "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } } }, "space": { "$ref": "#/components/schemas/DriveSpace" }, "shared": { "anyOf": [ { "description": "Set when it's shared with you (null: it's yours).", "type": "object", "required": [ "role", "top_id", "owner" ], "properties": { "role": { "anyOf": [ { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "top_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The folder or file shared with you — the path starts there.", "type": "string" }, { "type": "null" } ] }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/DriveOwner" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "match": { "description": "With `contents=1`: how it was found — its name, or the words inside it (its best match).", "anyOf": [ { "const": "name", "type": "string" }, { "const": "contents", "type": "string" } ] }, "snippet": { "description": "The words around the match inside the file, as plain text (with `contents=1`, when its text matched).", "type": "string" }, "marks": { "description": "Where the matched words are in `snippet`: [start, end) string indices in UTF-16 code units, in order, never overlapping.", "type": "array", "items": { "type": "array", "items": false, "minItems": 2, "maxItems": 2, "prefixItems": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } ] } } } } }, "search": { "$ref": "#/components/schemas/SearchMeta" }, "contents": { "description": "With `contents=1` (not for the trash or folders): `searched`; `not_in_plan` — no Drive you can search includes search inside files; `unavailable` — it isn't answering right now, these are name matches; `blocked_by_team` — an API key or app whose person's team doesn't let apps read file contents: these are name matches only.", "anyOf": [ { "const": "searched", "type": "string" }, { "const": "not_in_plan", "type": "string" }, { "const": "unavailable", "type": "string" }, { "const": "blocked_by_team", "type": "string" } ] } } }, "DriveShare": { "type": "object", "required": [ "id", "node_id", "kind", "user_id", "email", "group_id", "team_id", "name", "role", "expires_at", "accepted", "created_at", "inherited_from" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "node_id": { "pattern": "^[0-9]+$", "description": "The file or folder the share is on (a folder above, when inherited).", "type": "string" }, "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "email", "type": "string" }, { "const": "group", "type": "string" }, { "const": "team", "type": "string" } ] }, "user_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "group_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "team_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "name": { "description": "The person, the address, the group or \"Everyone at \".", "type": "string" }, "role": { "anyOf": [ { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "description": "When it ends (null: never).", "type": "string" }, { "type": "null" } ] }, "accepted": { "description": "False for an address that hasn't opened it signed in yet.", "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "inherited_from": { "anyOf": [ { "description": "Set when the share sits on a folder above.", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } }, { "type": "null" } ] } } }, "DriveShareList": { "type": "object", "required": [ "shares" ], "properties": { "shares": { "type": "array", "items": { "$ref": "#/components/schemas/DriveShare" } } } }, "DriveShareTargets": { "type": "object", "required": [ "teams" ], "properties": { "teams": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "seats", "groups" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "seats": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "groups": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "members" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "members": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } } } } }, "DriveSharedWithMe": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "parent_id", "kind", "name", "size", "mime", "content_hash", "versions", "modified_at", "updated_at", "created_at", "trashed_at", "purge_after", "seq", "version_id", "share_id", "role", "shared_at", "expires_at", "via", "owner", "can_leave" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "parent_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The folder it is in (null: the top folder itself).", "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "folder", "type": "string" }, { "const": "file", "type": "string" } ] }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "description": "The current version's size (0 for a folder).", "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_hash": { "anyOf": [ { "description": "BLAKE3 (hex) of the current version, as SendFlo computed it — null until it has been checked (seconds after an upload).", "type": "string" }, { "type": "null" } ] }, "versions": { "description": "Versions kept (the current one included).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Versions kept (the current one included).", "type": "integer" } ] }, "modified_at": { "format": "date-time", "description": "When the content last changed.", "type": "string" }, "updated_at": { "format": "date-time", "description": "When anything last changed (a rename, a move…).", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "trashed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "purge_after": { "anyOf": [ { "format": "date-time", "description": "In the trash: when it is deleted for good.", "type": "string" }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "seq": { "description": "The change that last touched it (see GET /v1/drive/changes).", "type": "string" }, "thumb_url": { "anyOf": [ { "description": "A thumbnail for images.", "type": "string" }, { "type": "null" } ] }, "scan_state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "clean", "type": "string" }, { "const": "flagged", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "released", "type": "string" }, { "const": "not_scannable", "type": "string" }, { "const": "error", "type": "string" } ] }, "version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The current version (files): a sync client sends it back as `base_version_id` when it saves.", "type": "string" }, { "type": "null" } ] }, "lock": { "description": "Locked for editing: others' saves are refused until then (P6).", "type": "object", "required": [ "user_id", "name", "until", "mine" ], "properties": { "user_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "until": { "format": "date-time", "type": "string" }, "mine": { "type": "boolean" } } }, "conflict": { "description": "This file is a sync conflict's copy of `file_id` (P6).", "type": "object", "required": [ "id", "file_id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" } } }, "share_id": { "pattern": "^[0-9]+$", "type": "string" }, "role": { "anyOf": [ { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "shared_at": { "format": "date-time", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "via": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "email", "type": "string" }, { "const": "group", "type": "string" }, { "const": "team", "type": "string" } ] }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/DriveOwner" }, { "type": "null" } ] }, "can_leave": { "description": "It names you (not a group or team): you may leave it.", "type": "boolean" } } } } } }, "DriveShares": { "type": "object", "required": [ "owner", "role", "can_share", "shares", "roles" ], "properties": { "owner": { "anyOf": [ { "$ref": "#/components/schemas/DriveOwner" }, { "type": "null" } ] }, "role": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "can_share": { "type": "boolean" }, "shares": { "type": "array", "items": { "$ref": "#/components/schemas/DriveShare" } }, "roles": { "type": "array", "items": { "type": "object", "required": [ "role", "label", "text" ], "properties": { "role": { "anyOf": [ { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "label": { "type": "string" }, "text": { "type": "string" } } } } } }, "DriveSnapshot": { "type": "object", "required": [ "space_id", "seq", "nodes", "next" ], "properties": { "space_id": { "pattern": "^[0-9]+$", "type": "string" }, "seq": { "type": "string" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/DriveNode" } }, "next": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] } } }, "DriveSpace": { "type": "object", "required": [ "id", "kind", "name", "root_id", "seq", "bytes_used", "files", "e2e" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "kind": { "anyOf": [ { "const": "personal", "type": "string" }, { "const": "team", "type": "string" } ] }, "name": { "type": "string" }, "root_id": { "pattern": "^[0-9]+$", "description": "The top folder.", "type": "string" }, "seq": { "description": "The last change.", "type": "string" }, "bytes_used": { "pattern": "^[0-9]+$", "description": "What the plan counts: current versions of files not in the trash.", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "e2e": { "type": "boolean" } } }, "DriveSpaceChanges": { "type": "object", "required": [ "space_id", "cursor", "more", "changes" ], "properties": { "space_id": { "pattern": "^[0-9]+$", "type": "string" }, "cursor": { "type": "string" }, "more": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "object", "required": [ "seq", "op", "node_id", "node" ], "properties": { "seq": { "type": "string" }, "op": { "anyOf": [ { "const": "create", "type": "string" }, { "const": "update", "type": "string" }, { "const": "rename", "type": "string" }, { "const": "move", "type": "string" }, { "const": "trash", "type": "string" }, { "const": "restore", "type": "string" }, { "const": "delete", "type": "string" } ] }, "node_id": { "pattern": "^[0-9]+$", "type": "string" }, "node": { "anyOf": [ { "$ref": "#/components/schemas/DriveNode" }, { "type": "null" } ] } } } } } }, "DriveSpaceResult": { "type": "object", "required": [ "space" ], "properties": { "space": { "$ref": "#/components/schemas/DriveSpace" } } }, "DriveSummary": { "type": "object", "required": [ "space", "plan" ], "properties": { "space": { "anyOf": [ { "$ref": "#/components/schemas/DriveSpace" }, { "type": "null" } ] }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/DrivePlan" }, { "type": "null" } ] }, "folders": { "description": "An app allowed only some folders: those folders.", "type": "array", "items": { "$ref": "#/components/schemas/DriveNode" } } } }, "DriveSyncClient": { "type": "object", "required": [ "id", "name", "os", "client_version", "root_kind", "state", "problems", "problem_reasons", "pending", "cache_bytes", "cache_budget", "hidden", "spaces", "managed", "last_seen_at", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "root_kind": { "anyOf": [ { "const": "cfapi", "type": "string" }, { "const": "fileprovider", "type": "string" }, { "const": "fuse", "type": "string" }, { "const": "folder", "type": "string" } ] }, "state": { "anyOf": [ { "const": "ok", "type": "string" }, { "const": "syncing", "type": "string" }, { "const": "paused", "type": "string" }, { "const": "problems", "type": "string" }, { "const": "offline", "type": "string" } ] }, "problems": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "problem_reasons": { "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "pending": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "cache_bytes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cache_budget": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hidden": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "spaces": { "type": "array", "items": { "type": "object", "required": [ "space_id", "cursor" ], "properties": { "space_id": { "pattern": "^[0-9]+$", "type": "string" }, "cursor": { "type": "string" } } } }, "managed": { "anyOf": [ { "description": "What an organisation's device management set on this computer: the keys (TeamId, SsoDomain, DriveOn, DriveFolder, DriveCacheGB, BackupFolders) and its team. null when nothing is set.", "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "string" } }, "team": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "peer_in_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "peer_out_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "last_seen_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "DriveSyncClientResult": { "type": "object", "required": [ "client" ], "properties": { "client": { "$ref": "#/components/schemas/DriveSyncClient" } } }, "DriveSyncClients": { "type": "object", "required": [ "clients" ], "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/DriveSyncClient" } } } }, "DriveSyncRoots": { "type": "object", "required": [ "roots" ], "properties": { "roots": { "type": "array", "items": { "type": "object", "required": [ "space_id", "kind", "name", "team", "root_id", "role", "read_only", "seq" ], "properties": { "space_id": { "pattern": "^[0-9]+$", "type": "string" }, "kind": { "anyOf": [ { "const": "personal", "type": "string" }, { "const": "team", "type": "string" } ] }, "name": { "type": "string" }, "team": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "root_id": { "pattern": "^[0-9]+$", "type": "string" }, "role": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "read_only": { "type": "boolean" }, "seq": { "type": "string" } } } } } }, "DriveTask": { "type": "object", "required": [ "task" ], "properties": { "task": { "type": "object", "required": [ "id", "status", "due_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "done", "type": "string" } ] }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } }, "DriveTasks": { "type": "object", "required": [ "tasks" ], "properties": { "tasks": { "type": "array", "items": {} } } }, "DriveTeamPolicy": { "type": "object", "required": [ "policy", "outside_controls" ], "properties": { "policy": { "type": "object", "required": [ "create", "outside", "peers" ], "properties": { "create": { "anyOf": [ { "const": "admins", "type": "string" }, { "const": "managers", "type": "string" }, { "const": "members", "type": "string" } ] }, "outside": { "anyOf": [ { "const": "allow", "type": "string" }, { "const": "off", "type": "string" } ] }, "peers": { "anyOf": [ { "const": "on", "type": "string" }, { "const": "off", "type": "string" } ] } } }, "outside_controls": { "type": "boolean" } } }, "DriveTeamSpaces": { "type": "object", "required": [ "spaces", "teams" ], "properties": { "spaces": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "name", "root_id", "seq", "bytes_used", "files", "e2e", "team", "role", "members" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "kind": { "anyOf": [ { "const": "personal", "type": "string" }, { "const": "team", "type": "string" } ] }, "name": { "type": "string" }, "root_id": { "pattern": "^[0-9]+$", "description": "The top folder.", "type": "string" }, "seq": { "description": "The last change.", "type": "string" }, "bytes_used": { "pattern": "^[0-9]+$", "description": "What the plan counts: current versions of files not in the trash.", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "e2e": { "type": "boolean" }, "team": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } }, "role": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "co_owner", "type": "string" }, { "const": "editor", "type": "string" }, { "const": "uploader", "type": "string" }, { "const": "viewer", "type": "string" }, { "const": "previewer", "type": "string" } ] }, "members": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } }, "teams": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "can_create", "manages" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "can_create": { "type": "boolean" }, "manages": { "type": "boolean" } } } } } }, "DriveTextInImage": { "type": "object", "required": [ "text_in_image" ], "properties": { "text_in_image": { "anyOf": [ { "type": "object", "required": [ "state", "label", "detail" ], "properties": { "state": { "anyOf": [ { "const": "read", "type": "string" }, { "const": "partly_read", "type": "string" }, { "const": "unreadable", "type": "string" }, { "const": "damaged", "type": "string" }, { "const": "no_text", "type": "string" }, { "const": "not_read_yet", "type": "string" }, { "const": "off", "type": "string" } ] }, "label": { "description": "The words to show, e.g. \"Partly read\".", "type": "string" }, "detail": { "anyOf": [ { "description": "A quieter part after the label, e.g. \"some words may be missing\".", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, "DriveTrash": { "type": "object", "required": [ "items", "version_days", "plan", "space" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DriveNode" } }, "version_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "plan": { "$ref": "#/components/schemas/DrivePlan" }, "space": { "$ref": "#/components/schemas/DriveSpace" } } }, "DriveTrashed": { "type": "object", "required": [ "trashed", "id", "count", "bytes", "purge_after" ], "properties": { "trashed": { "const": true, "type": "boolean" }, "id": { "pattern": "^[0-9]+$", "type": "string" }, "count": { "description": "Items moved (the folder and everything in it).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Items moved (the folder and everything in it).", "type": "integer" } ] }, "bytes": { "pattern": "^[0-9]+$", "type": "string" }, "purge_after": { "format": "date-time", "type": "string" } } }, "DriveUploadDone": { "type": "object", "required": [ "node" ], "properties": { "node": { "$ref": "#/components/schemas/DriveNode" }, "conflict_of": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The file this save became a conflict copy of.", "type": "string" }, { "type": "null" } ] } } }, "DriveUploadStart": { "anyOf": [ { "type": "object", "required": [ "state", "deduplicated", "node" ], "properties": { "state": { "const": "done", "type": "string" }, "deduplicated": { "const": true, "type": "boolean" }, "node": { "$ref": "#/components/schemas/DriveNode" }, "conflict_of": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The file this save became a conflict copy of.", "type": "string" }, { "type": "null" } ] } } }, { "type": "object", "required": [ "state", "upload_id", "part_size", "parts", "part_urls", "expires_at" ], "properties": { "state": { "const": "open", "type": "string" }, "upload_id": { "pattern": "^[0-9]+$", "type": "string" }, "part_size": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "parts": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "copied_parts": { "description": "With `parts`: the parts SendFlo copied from the base version — don't send them.", "type": "array", "items": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } }, "upload_parts": { "description": "With `parts`: the parts to send; `part_urls` are theirs, in this order.", "type": "array", "items": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } }, "part_urls": { "description": "The first parts' URLs (64 at most).", "type": "array", "items": { "type": "string" } }, "expires_at": { "format": "date-time", "description": "Finish before this.", "type": "string" } } } ] }, "DriveUsage": { "type": "object", "required": [ "bytes_used", "files", "bytes", "history_bytes", "plan" ], "properties": { "bytes_used": { "pattern": "^[0-9]+$", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "bytes": { "pattern": "^[0-9]+$", "description": "The plan's room.", "type": "string" }, "history_bytes": { "pattern": "^[0-9]+$", "description": "Earlier versions and the trash (not counted).", "type": "string" }, "plan": { "$ref": "#/components/schemas/DrivePlan" } } }, "DriveVersions": { "type": "object", "required": [ "current_version_id", "version_days", "versions" ], "properties": { "current_version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "version_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "versions": { "type": "array", "items": { "type": "object", "required": [ "id", "size", "content_hash", "source", "created_at", "created_by", "purge_after", "current" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "const": "web", "type": "string" }, { "const": "desktop", "type": "string" }, { "const": "phone", "type": "string" }, { "const": "api", "type": "string" }, { "const": "restore", "type": "string" }, { "const": "copy", "type": "string" } ] }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "purge_after": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "current": { "type": "boolean" }, "editors": { "description": "A note version (DW4): everyone who edited it together, by name.", "type": "array", "items": { "type": "string" } } } } } } }, "E2eDevice": { "type": "object", "required": [ "id", "label", "platform", "status", "public_key", "fingerprint", "code", "unlocked_via", "approved_by", "created_at", "approved_at", "revoked_at", "enrolled_by_key" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "label": { "type": "string" }, "platform": { "anyOf": [ { "const": "web", "type": "string" }, { "const": "desktop", "type": "string" }, { "const": "ios", "type": "string" }, { "const": "android", "type": "string" }, { "const": "cli", "type": "string" } ] }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "active", "type": "string" }, { "const": "revoked", "type": "string" } ] }, "public_key": { "description": "base64url", "type": "string" }, "fingerprint": { "type": "string" }, "code": { "description": "The six digits the person compares on the device that approves this one.", "type": "string" }, "unlocked_via": { "anyOf": [ { "anyOf": [ { "const": "setup", "type": "string" }, { "const": "device", "type": "string" }, { "const": "recovery", "type": "string" }, { "const": "passkey", "type": "string" } ] }, { "type": "null" } ] }, "approved_by": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "enrolled_by_key": { "description": "An API key or an app asked for it (the SDK or the CLI).", "type": "boolean" } } }, "E2eDeviceRemoved": { "type": "object", "required": [ "ok", "rotate_recommended" ], "properties": { "ok": { "const": true, "type": "boolean" }, "rotate_recommended": { "type": "boolean" } } }, "E2eDevices": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/E2eDevice" } } } }, "E2eIdentity": { "type": "object", "required": [ "version", "suite", "public_key", "fingerprint", "created_at" ], "properties": { "version": { "minimum": 1, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "type": "integer" } ] }, "suite": { "description": "`xwing-hpke1`: X-Wing (X25519 + ML-KEM-768) with HPKE (RFC 9180).", "type": "string" }, "public_key": { "description": "base64url", "type": "string" }, "fingerprint": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } }, "E2eKeyEvents": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "seq", "kind", "payload", "device_id", "at", "prev_hash", "hash" ], "properties": { "seq": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "kind": { "type": "string" }, "payload": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "device_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "at": { "format": "date-time", "type": "string" }, "prev_hash": { "type": "string" }, "hash": { "type": "string" } } } } } }, "E2eKeys": { "type": "object", "required": [ "suite", "user_id", "identity", "devices", "recovery", "passkeys", "chain" ], "properties": { "suite": { "type": "string" }, "user_id": { "pattern": "^[0-9]+$", "description": "The person the keys belong to (the key's maker).", "type": "string" }, "identity": { "anyOf": [ { "$ref": "#/components/schemas/E2eIdentity" }, { "type": "null" } ] }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/E2eDevice" } }, "recovery": { "type": "boolean" }, "passkeys": { "type": "array", "items": { "type": "string" } }, "chain": { "anyOf": [ { "type": "object", "required": [ "seq", "hash" ], "properties": { "seq": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "hash": { "type": "string" } } }, { "type": "null" } ] } } }, "E2eSeals": { "type": "object", "required": [ "identities", "seals", "history" ], "properties": { "identities": { "type": "array", "items": { "$ref": "#/components/schemas/E2eIdentity" } }, "seals": { "type": "array", "items": { "type": "object", "required": [ "version", "kind", "target", "sealed" ], "properties": { "version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "kind": { "type": "string" }, "target": { "type": "string" }, "sealed": { "description": "base64url: HPKE enc ‖ ciphertext of a 32-byte seed.", "type": "string" } } } }, "history": { "type": "array", "items": { "type": "object", "required": [ "version", "kind", "target", "sealed" ], "properties": { "version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "kind": { "type": "string" }, "target": { "type": "string" }, "sealed": { "description": "base64url: HPKE enc ‖ ciphertext of a 32-byte seed.", "type": "string" } } } } } }, "E2eTeamSeals": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "team_key_id", "plan_id", "kind", "ref_id", "version", "public_key", "fingerprint", "identity_version", "sealed" ], "properties": { "team_key_id": { "pattern": "^[0-9]+$", "type": "string" }, "plan_id": { "pattern": "^[0-9]+$", "type": "string" }, "kind": { "anyOf": [ { "const": "recovery", "type": "string" }, { "const": "inbox", "type": "string" } ] }, "ref_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The inbox's id, for an inbox key.", "type": "string" }, { "type": "null" } ] }, "version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "public_key": { "type": "string" }, "fingerprint": { "type": "string" }, "identity_version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "sealed": { "type": "string" } } } } } }, "ExpiryCapped": { "description": "Present when the plan shortened the expiry you asked for.", "type": "object", "required": [ "reason", "billing_cycle", "max_days", "expires_at", "message" ], "properties": { "reason": { "const": "billing_cycle", "type": "string" }, "billing_cycle": { "anyOf": [ { "const": "monthly", "type": "string" }, { "const": "annual", "type": "string" } ] }, "max_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "expires_at": { "format": "date-time", "type": "string" }, "message": { "type": "string" } } }, "FeedbackAnchor": { "description": "Where a comment points: {t, t_end?} seconds into video or audio; {page} a PDF page; {x, y, w?, h?, page?} a pin or box, 0–1 of the original.", "anyOf": [ { "type": "object", "required": [ "t" ], "properties": { "t": { "type": "number" }, "t_end": { "type": "number" } } }, { "type": "object", "required": [ "page" ], "properties": { "page": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" }, "page": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } ] }, "FeedbackComment": { "description": "A comment as the transfer's owner sees it.", "type": "object", "required": [ "id", "file", "parent_id", "body", "anchor", "created_at", "edited", "resolved", "mine", "hidden", "author" ], "properties": { "id": { "type": "string" }, "file": { "description": "The file's link slug.", "type": "string" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "body": { "anyOf": [ { "description": "null: a deleted comment kept because it has replies. On an encrypted transfer: the sealed envelope.", "type": "string" }, { "type": "null" } ] }, "encrypted": { "const": true, "type": "boolean" }, "anchor": { "anyOf": [ { "$ref": "#/components/schemas/FeedbackAnchor" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "edited": { "type": "boolean" }, "resolved": { "type": "boolean" }, "mine": { "type": "boolean" }, "hidden": { "description": "Hidden from recipients (a block, or Trust & Safety).", "type": "boolean" }, "author": { "type": "object", "required": [ "name", "verified", "proof", "sender", "email", "id", "blocked" ], "properties": { "name": { "type": "string" }, "verified": { "const": true, "type": "boolean" }, "proof": { "anyOf": [ { "const": "account", "type": "string" }, { "const": "access", "type": "string" }, { "const": "email", "type": "string" } ] }, "sender": { "type": "boolean" }, "email": { "type": "string" }, "id": { "description": "The person's reviewer id (for block and unblock).", "type": "string" }, "blocked": { "type": "boolean" } } } } }, "FeedbackExport": { "description": "Everything about a transfer's feedback.", "type": "object", "required": [ "transfer", "comments", "ratings", "favorites", "approvals" ], "properties": { "transfer": { "type": "object", "required": [ "root_id", "slug", "settings", "rating_max", "exported_at" ], "properties": { "root_id": { "type": "string" }, "slug": { "type": "string" }, "settings": { "$ref": "#/components/schemas/FeedbackSettings" }, "rating_max": { "anyOf": [ { "const": 5, "type": "number" }, { "const": 10, "type": "number" } ] }, "exported_at": { "format": "date-time", "type": "string" } } }, "comments": { "type": "array", "items": { "type": "object", "required": [ "id", "file", "file_name", "parent_id", "author", "body", "encrypted", "anchor", "created_at", "edited", "resolved", "hidden" ], "properties": { "id": { "type": "string" }, "file": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_name": { "type": "string" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "type": "object", "required": [ "name", "email", "proof", "sender" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "proof": { "anyOf": [ { "const": "account", "type": "string" }, { "const": "access", "type": "string" }, { "const": "email", "type": "string" } ] }, "sender": { "type": "boolean" } } }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "encrypted": { "type": "boolean" }, "anchor": { "anyOf": [ { "$ref": "#/components/schemas/FeedbackAnchor" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "edited": { "type": "boolean" }, "resolved": { "type": "boolean" }, "hidden": { "type": "boolean" } } } }, "ratings": { "type": "array", "items": { "type": "object", "required": [ "file", "file_name", "person", "email", "value", "scale", "rated_at" ], "properties": { "file": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_name": { "type": "string" }, "person": { "type": "string" }, "email": { "type": "string" }, "value": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "scale": { "anyOf": [ { "const": "stars5", "type": "string" }, { "const": "score10", "type": "string" } ] }, "rated_at": { "format": "date-time", "type": "string" } } } }, "favorites": { "type": "array", "items": { "type": "object", "required": [ "file", "file_name", "person", "email", "favorited_at" ], "properties": { "file": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_name": { "type": "string" }, "person": { "type": "string" }, "email": { "type": "string" }, "favorited_at": { "format": "date-time", "type": "string" } } } }, "approvals": { "type": "array", "items": { "type": "object", "required": [ "file", "file_name", "person", "email", "state", "at" ], "properties": { "file": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_name": { "type": "string" }, "person": { "type": "string" }, "email": { "type": "string" }, "state": { "anyOf": [ { "const": "approved", "type": "string" }, { "const": "changes", "type": "string" } ] }, "at": { "format": "date-time", "type": "string" } } } } } }, "FeedbackFileSummary": { "type": "object", "required": [ "link_id", "slug", "name", "live", "comments", "hidden", "favorites", "rating", "approvals" ], "properties": { "link_id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "live": { "description": "Not revoked, not expired, already available.", "type": "boolean" }, "comments": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "hidden": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "favorites": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "rating": { "type": "object", "required": [ "count", "average", "distribution" ], "properties": { "count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "average": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "distribution": { "description": "Rating value → how many gave it.", "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } }, "approvals": { "type": "object", "required": [ "approved", "changes" ], "properties": { "approved": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "changes": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } }, "FeedbackReviewer": { "description": "A person giving feedback on one transfer.", "type": "object", "required": [ "id", "name", "email", "proof", "sender", "blocked", "created_at", "last_active_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "proof": { "anyOf": [ { "const": "account", "type": "string" }, { "const": "access", "type": "string" }, { "const": "email", "type": "string" } ] }, "sender": { "type": "boolean" }, "blocked": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "last_active_at": { "format": "date-time", "type": "string" } } }, "FeedbackReviewerSummary": { "type": "object", "required": [ "id", "name", "email", "proof", "sender", "blocked", "created_at", "last_active_at", "comments", "ratings", "favorites", "approvals" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "proof": { "anyOf": [ { "const": "account", "type": "string" }, { "const": "access", "type": "string" }, { "const": "email", "type": "string" } ] }, "sender": { "type": "boolean" }, "blocked": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "last_active_at": { "format": "date-time", "type": "string" }, "comments": { "description": "Their comments (deleted ones with replies included).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Their comments (deleted ones with replies included).", "type": "integer" } ] }, "ratings": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "favorites": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "approvals": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "FeedbackSettings": { "description": "The transfer's feedback settings.", "type": "object", "required": [ "comments", "ratings", "favorites", "approvals", "rating_scale", "encrypted" ], "properties": { "comments": { "anyOf": [ { "const": "off", "type": "string" }, { "const": "open", "type": "string" }, { "const": "private", "type": "string" } ] }, "ratings": { "type": "boolean" }, "favorites": { "type": "boolean" }, "approvals": { "type": "boolean" }, "rating_scale": { "anyOf": [ { "const": "stars5", "type": "string" }, { "const": "score10", "type": "string" } ] }, "encrypted": { "description": "An end-to-end encrypted transfer: comment bodies are sealed envelopes (sfx1..).", "type": "boolean" } } }, "File": { "description": "A stored file.", "type": "object", "required": [ "id", "name", "size", "content_type", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "FileRequest": { "description": "A file request (a one-off ask) or a reception link (an upload page that stays open).", "type": "object", "required": [ "id", "slug", "url", "state", "kind", "personal", "name", "prompt", "max_files", "max_bytes_per_file", "max_bytes_per_upload", "max_files_per_upload", "max_total_bytes", "max_total_uploads", "max_bytes_per_person", "max_uploads_per_person", "show_space_left", "usage", "files_received", "has_password", "notify", "access", "allowed_emails", "retention_days", "effective_retention_days", "allowed_types", "reject_flagged", "brand_id", "questions", "require_contact", "view_only", "member_mark", "view_only_other", "team_visible", "embed_origins", "widget_share_answers", "widget", "e2e", "e2e_available", "expires_at", "created_at", "updated_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "url": { "description": "The upload page, https://sendflo.app/u/{slug}.", "type": "string" }, "state": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "fulfilled", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "expired", "type": "string" } ] }, "kind": { "anyOf": [ { "const": "request", "type": "string" }, { "const": "reception", "type": "string" } ] }, "personal": { "description": "The account's personal upload link.", "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "max_files": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "max_bytes_per_file": { "anyOf": [ { "description": "Bytes, as a decimal string.", "type": "string" }, { "type": "null" } ] }, "max_bytes_per_upload": { "anyOf": [ { "description": "Bytes, as a decimal string: the files sent together.", "type": "string" }, { "type": "null" } ] }, "max_files_per_upload": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "max_total_bytes": { "anyOf": [ { "description": "Bytes, as a decimal string: everything the page receives.", "type": "string" }, { "type": "null" } ] }, "max_total_uploads": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "max_bytes_per_person": { "anyOf": [ { "description": "Bytes, as a decimal string, per verified uploader.", "type": "string" }, { "type": "null" } ] }, "max_uploads_per_person": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "show_space_left": { "description": "The page shows uploaders how much room is left.", "type": "boolean" }, "usage": { "anyOf": [ { "description": "What the page received; files rejected by the malware scan don't count.", "type": "object", "required": [ "received_bytes", "received_files", "uploads", "reserved_bytes" ], "properties": { "received_bytes": { "description": "Bytes, as a decimal string.", "type": "string" }, "received_files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "uploads": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "reserved_bytes": { "description": "Bytes held for uploads still landing.", "type": "string" } } }, { "type": "null" } ] }, "files_received": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "has_password": { "type": "boolean" }, "notify": { "anyOf": [ { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": "string" } } }, { "type": "null" } ] }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "allowed_emails": { "type": "array", "items": { "type": "string" } }, "retention_days": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "effective_retention_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowed_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "reject_flagged": { "type": "boolean" }, "brand_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/UploadQuestion" } }, "require_contact": { "type": "boolean" }, "view_only": { "description": "Received PDFs and images are view-only (team seats).", "type": "boolean" }, "member_mark": { "description": "Each preview is the member's own copy with their email on it.", "type": "boolean" }, "view_only_other": { "anyOf": [ { "const": "download", "type": "string" }, { "const": "block", "type": "string" } ] }, "team_visible": { "description": "The team's Owner and Admins see what arrives through this page (team seats).", "type": "boolean" }, "embed_origins": { "description": "The sites allowed to frame the script widget (Pro, Team Pro, Team Enterprise): exact origins, `https://*.example.com` for subdomains. Empty = any site.", "type": "array", "items": { "type": "string" } }, "widget_share_answers": { "description": "The host page's `all_complete` widget event carries the uploader's answers.", "type": "boolean" }, "widget": { "description": "The script widget for this page.", "type": "object", "required": [ "allowed", "needs", "secret_issued" ], "properties": { "allowed": { "description": "The plan has the script widget (Pro, Team Pro, Team Enterprise). The plain iframe works on every plan.", "type": "boolean" }, "needs": { "description": "The plan the script widget needs.", "type": "string" }, "secret_issued": { "description": "A widget secret was issued (GET /v1/file-requests/:id/widget-secret).", "type": "boolean" } } }, "e2e": { "description": "Uploads are encrypted end to end in the uploader's browser; SendFlo stores ciphertext and each file's key sealed to the page's recipients.", "type": "boolean" }, "e2e_available": { "description": "The plan has encrypted uploads (Pro, Team Pro, Team Enterprise).", "type": "boolean" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } }, "FileRequestLimits": { "type": "object", "required": [ "plan_class", "reception_links", "retention_default_days", "retention_max_days", "request_expiry_free_days", "paid", "max_transfer_bytes" ], "properties": { "plan_class": { "anyOf": [ { "const": "free", "type": "string" }, { "const": "starter", "type": "string" }, { "const": "plus", "type": "string" }, { "const": "pro", "type": "string" }, { "const": "enterprise", "type": "string" } ] }, "reception_links": { "type": "object", "required": [ "used", "max" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "max": { "description": "0 = unlimited.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "0 = unlimited.", "type": "integer" } ] } } }, "retention_default_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "retention_max_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "request_expiry_free_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "paid": { "type": "boolean" }, "max_transfer_bytes": { "description": "The plan's size per transfer, in bytes as a decimal string: the most one file or one upload can be.", "type": "string" } } }, "FileRequestWithSecret": { "type": "object", "required": [ "id", "slug", "url", "state", "kind", "personal", "name", "prompt", "max_files", "max_bytes_per_file", "max_bytes_per_upload", "max_files_per_upload", "max_total_bytes", "max_total_uploads", "max_bytes_per_person", "max_uploads_per_person", "show_space_left", "usage", "files_received", "has_password", "notify", "access", "allowed_emails", "retention_days", "effective_retention_days", "allowed_types", "reject_flagged", "brand_id", "questions", "require_contact", "view_only", "member_mark", "view_only_other", "team_visible", "embed_origins", "widget_share_answers", "widget", "e2e", "e2e_available", "expires_at", "created_at", "updated_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "url": { "description": "The upload page, https://sendflo.app/u/{slug}.", "type": "string" }, "state": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "fulfilled", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "expired", "type": "string" } ] }, "kind": { "anyOf": [ { "const": "request", "type": "string" }, { "const": "reception", "type": "string" } ] }, "personal": { "description": "The account's personal upload link.", "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "max_files": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "max_bytes_per_file": { "anyOf": [ { "description": "Bytes, as a decimal string.", "type": "string" }, { "type": "null" } ] }, "max_bytes_per_upload": { "anyOf": [ { "description": "Bytes, as a decimal string: the files sent together.", "type": "string" }, { "type": "null" } ] }, "max_files_per_upload": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "max_total_bytes": { "anyOf": [ { "description": "Bytes, as a decimal string: everything the page receives.", "type": "string" }, { "type": "null" } ] }, "max_total_uploads": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "max_bytes_per_person": { "anyOf": [ { "description": "Bytes, as a decimal string, per verified uploader.", "type": "string" }, { "type": "null" } ] }, "max_uploads_per_person": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "show_space_left": { "description": "The page shows uploaders how much room is left.", "type": "boolean" }, "usage": { "anyOf": [ { "description": "What the page received; files rejected by the malware scan don't count.", "type": "object", "required": [ "received_bytes", "received_files", "uploads", "reserved_bytes" ], "properties": { "received_bytes": { "description": "Bytes, as a decimal string.", "type": "string" }, "received_files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "uploads": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "reserved_bytes": { "description": "Bytes held for uploads still landing.", "type": "string" } } }, { "type": "null" } ] }, "files_received": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "has_password": { "type": "boolean" }, "notify": { "anyOf": [ { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": "string" } } }, { "type": "null" } ] }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "allowed_emails": { "type": "array", "items": { "type": "string" } }, "retention_days": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "effective_retention_days": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowed_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "reject_flagged": { "type": "boolean" }, "brand_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/UploadQuestion" } }, "require_contact": { "type": "boolean" }, "view_only": { "description": "Received PDFs and images are view-only (team seats).", "type": "boolean" }, "member_mark": { "description": "Each preview is the member's own copy with their email on it.", "type": "boolean" }, "view_only_other": { "anyOf": [ { "const": "download", "type": "string" }, { "const": "block", "type": "string" } ] }, "team_visible": { "description": "The team's Owner and Admins see what arrives through this page (team seats).", "type": "boolean" }, "embed_origins": { "description": "The sites allowed to frame the script widget (Pro, Team Pro, Team Enterprise): exact origins, `https://*.example.com` for subdomains. Empty = any site.", "type": "array", "items": { "type": "string" } }, "widget_share_answers": { "description": "The host page's `all_complete` widget event carries the uploader's answers.", "type": "boolean" }, "widget": { "description": "The script widget for this page.", "type": "object", "required": [ "allowed", "needs", "secret_issued" ], "properties": { "allowed": { "description": "The plan has the script widget (Pro, Team Pro, Team Enterprise). The plain iframe works on every plan.", "type": "boolean" }, "needs": { "description": "The plan the script widget needs.", "type": "string" }, "secret_issued": { "description": "A widget secret was issued (GET /v1/file-requests/:id/widget-secret).", "type": "boolean" } } }, "e2e": { "description": "Uploads are encrypted end to end in the uploader's browser; SendFlo stores ciphertext and each file's key sealed to the page's recipients.", "type": "boolean" }, "e2e_available": { "description": "The plan has encrypted uploads (Pro, Team Pro, Team Enterprise).", "type": "boolean" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "notify_webhook_secret": { "description": "The webhook's signing secret, shown once when `notify.webhook_url` is new.", "type": "string" } } }, "ForwardCheck": { "type": "object", "required": [ "allowed", "allowance", "source", "consumes_download", "downloads_left", "can_download_after", "charge_bytes", "quota", "ad_required", "delivery", "password" ], "properties": { "allowed": { "type": "boolean" }, "allowance": { "description": "Forwards of files on included storage are tracked; when the platform caps them, your monthly allowance is checked (409 `forward_quota_exhausted` past it).", "type": "object", "required": [ "tracked", "capped", "needs_bytes", "remaining_bytes", "period_end" ], "properties": { "tracked": { "type": "boolean" }, "capped": { "type": "boolean" }, "needs_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "remaining_bytes": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, "source": { "type": "object", "required": [ "name", "size", "tier", "delivery", "has_password" ], "properties": { "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "tier": { "anyOf": [ { "const": "pool", "type": "string" }, { "const": "flat", "type": "string" } ] }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "has_password": { "type": "boolean" } } }, "consumes_download": { "description": "Economy (pool) storage: the forward uses one of the link's downloads.", "type": "boolean" }, "downloads_left": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "can_download_after": { "description": "False when the forward uses the link's last download.", "type": "boolean" }, "charge_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "quota": { "type": "object", "required": [ "used", "limit", "after", "allowed" ], "properties": { "used": { "pattern": "^[0-9]+$", "type": "string" }, "limit": { "pattern": "^[0-9]+$", "type": "string" }, "after": { "pattern": "^[0-9]+$", "type": "string" }, "allowed": { "type": "boolean" }, "code": { "type": "string" } } }, "ad_required": { "type": "boolean" }, "delivery": { "description": "The new link's mode: the original's by default; only these (the same or narrower) are accepted.", "type": "object", "required": [ "default", "allowed" ], "properties": { "default": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "allowed": { "type": "array", "items": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] } } } }, "password": { "type": "object", "required": [ "required" ], "properties": { "required": { "description": "The original has a password, so the new link keeps one: yours, or the original's when you set none.", "type": "boolean" } } } } }, "ForwardResult": { "type": "object", "required": [ "link", "file", "charged_bytes", "source", "delivery", "password" ], "properties": { "link": { "$ref": "#/components/schemas/LinkCreated" }, "file": { "type": "object", "required": [ "id", "copying" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "copying": { "type": "boolean" } } }, "charged_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "source": { "type": "object", "required": [ "consumed_download", "downloads_left", "can_download_after" ], "properties": { "consumed_download": { "type": "boolean" }, "downloads_left": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "can_download_after": { "type": "boolean" } } }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "password": { "anyOf": [ { "const": "inherited", "type": "string" }, { "const": "own", "type": "string" }, { "const": "none", "type": "string" } ] } } }, "Inbox": { "type": "object", "required": [ "id", "name", "address", "default_ttl_seconds", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "type": "string" }, "default_ttl_seconds": { "description": "How long received items are kept.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "How long received items are kept.", "type": "integer" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "InboxCreated": { "type": "object", "required": [ "id", "address", "url" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "address": { "type": "string" }, "url": { "type": "string" } } }, "InboxItem": { "type": "object", "required": [ "id", "file", "from", "metadata", "received_at", "expires_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "file": { "type": "object", "required": [ "id", "name", "size", "content_type", "scan_state" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "size": { "type": "string" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scan_state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "clean", "type": "string" }, { "const": "flagged", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "released", "type": "string" }, { "const": "not_scannable", "type": "string" } ] } } }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "description": "The uploader's answers and contact, when the page asked for them.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "received_at": { "format": "date-time", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, "Intake": { "type": "object", "required": [ "id", "status", "external_refs", "count", "files", "uploader_verified", "answers", "handed_to", "expires_at", "submitted_at", "ready_at", "url" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "opened", "type": "string" }, { "const": "submitted", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "closed", "type": "string" } ] }, "external_refs": { "anyOf": [ { "description": "Where it came from: {provider, kind, id, url?, label?}.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "count": { "description": "How many files arrived.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "How many files arrived.", "type": "integer" } ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "item_id", "type", "size", "scan", "name" ], "properties": { "item_id": { "pattern": "^[0-9]+$", "type": "string" }, "type": { "anyOf": [ { "description": "The content type.", "type": "string" }, { "type": "null" } ] }, "size": { "description": "Bytes, as a decimal string.", "type": "string" }, "scan": { "description": "pending, clean, flagged, released, not_scannable or rejected.", "type": "string" }, "name": { "description": "\"Collected file.\" unless the intake shares names (agent_fields.names).", "type": "string" } } } }, "uploader_verified": { "description": "The uploader proved their email (never the address itself).", "type": "boolean" }, "answers": { "description": "Only the answers the intake shares with the bot.", "type": "array", "items": { "type": "object", "required": [ "id", "label", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } } } }, "handed_to": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "grantee_id", "email", "permission", "expires_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "group", "type": "string" } ] }, "grantee_id": { "pattern": "^[0-9]+$", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "permission": { "anyOf": [ { "const": "view", "type": "string" }, { "const": "manage", "type": "string" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "ready_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "url": { "description": "The intake's files in SendFlo, for the people they're handed to (sign-in needed).", "type": "string" } } }, "IntakeCreated": { "type": "object", "required": [ "id", "status", "external_refs", "count", "files", "uploader_verified", "answers", "handed_to", "expires_at", "submitted_at", "ready_at", "url", "upload_url", "emailed", "client_token", "client_token_expires_at", "agent_access" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "opened", "type": "string" }, { "const": "submitted", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "closed", "type": "string" } ] }, "external_refs": { "anyOf": [ { "description": "Where it came from: {provider, kind, id, url?, label?}.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "count": { "description": "How many files arrived.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "How many files arrived.", "type": "integer" } ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "item_id", "type", "size", "scan", "name" ], "properties": { "item_id": { "pattern": "^[0-9]+$", "type": "string" }, "type": { "anyOf": [ { "description": "The content type.", "type": "string" }, { "type": "null" } ] }, "size": { "description": "Bytes, as a decimal string.", "type": "string" }, "scan": { "description": "pending, clean, flagged, released, not_scannable or rejected.", "type": "string" }, "name": { "description": "\"Collected file.\" unless the intake shares names (agent_fields.names).", "type": "string" } } } }, "uploader_verified": { "description": "The uploader proved their email (never the address itself).", "type": "boolean" }, "answers": { "description": "Only the answers the intake shares with the bot.", "type": "array", "items": { "type": "object", "required": [ "id", "label", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } } } }, "handed_to": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "grantee_id", "email", "permission", "expires_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "group", "type": "string" } ] }, "grantee_id": { "pattern": "^[0-9]+$", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "permission": { "anyOf": [ { "const": "view", "type": "string" }, { "const": "manage", "type": "string" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "ready_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "url": { "description": "The intake's files in SendFlo, for the people they're handed to (sign-in needed).", "type": "string" }, "upload_url": { "description": "The page the person uploads on.", "type": "string" }, "emailed": { "type": "boolean" }, "client_token": { "description": "For SendFlo.requestUpload: single use, 15 minutes.", "type": "string" }, "client_token_expires_at": { "format": "date-time", "type": "string" }, "agent_access": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "read", "type": "string" } ] } } }, "LinkCapabilities": { "description": "What the sender may still change on this link, from the file's storage tier and whether it was read. Files on included (pool) storage keep a fixed download limit; after the first read their access and recipients are fixed too, and people are added through the monthly bonus. Files on unlimited-download (flat) storage are open. Null when the API has no routing.", "type": "object", "required": [ "tier", "read", "download_limit", "access", "recipients", "bonus", "send_again", "permissions" ], "properties": { "tier": { "anyOf": [ { "const": "flat", "type": "string" }, { "const": "pool", "type": "string" } ] }, "read": { "description": "The file has been read (downloaded, previewed from the original, or copied).", "type": "boolean" }, "download_limit": { "type": "object", "required": [ "editable", "reason" ], "properties": { "editable": { "type": "boolean" }, "reason": { "anyOf": [ { "const": "pool_locked", "type": "string" }, { "type": "null" } ] } } }, "access": { "type": "object", "required": [ "editable", "reason" ], "properties": { "editable": { "type": "boolean" }, "reason": { "anyOf": [ { "const": "pool_read", "type": "string" }, { "type": "null" } ] } } }, "recipients": { "type": "object", "required": [ "add", "replace" ], "properties": { "add": { "anyOf": [ { "const": "free", "type": "string" }, { "const": "bonus", "type": "string" }, { "const": "none", "type": "string" } ] }, "replace": { "type": "boolean" } } }, "bonus": { "anyOf": [ { "type": "object", "required": [ "remaining_bytes", "needs_bytes", "period_end" ], "properties": { "remaining_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "needs_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "send_again": { "type": "object", "required": [ "same", "flexible", "copy_remaining_bytes" ], "properties": { "same": { "type": "boolean" }, "flexible": { "type": "boolean" }, "copy_remaining_bytes": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] } } }, "permissions": { "type": "object", "required": [ "editable", "preview_charge_bytes" ], "properties": { "editable": { "const": true, "type": "boolean" }, "preview_charge_bytes": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] } } } } }, "LinkCreated": { "description": "A new link (or, for a retried create, the earlier one with `replayed: true`).", "type": "object", "required": [ "id", "slug", "url", "file_id", "has_password", "expires_at", "max_downloads", "download_count", "note", "subject", "require_email", "access", "allowed_emails", "encrypted", "e2e_stamp", "e2e_each", "delivery", "watermark_label", "viewer_mark", "allow_guests", "guest_downloads", "viewers_invite", "download_mark", "mark_unsupported", "bundle_id", "available_at", "notify_on_download", "feedback", "created_at", "restore_until", "revoked_at", "paused_by", "placement" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "url": { "description": "The download page, https://sendflo.app/l/{slug}.", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" }, "has_password": { "type": "boolean" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "max_downloads": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "download_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "require_email": { "type": "boolean" }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "allowed_emails": { "type": "array", "items": { "type": "string" } }, "encrypted": { "type": "boolean" }, "e2e_stamp": { "description": "End-to-end sends: the sender's device stamped `watermark_label` into this file (PDFs and images) before encrypting it.", "type": "boolean" }, "e2e_each": { "description": "Mark each recipient: on a `restricted` end-to-end send of up to 50 people, the sender's device also stamped one copy per listed person with the label and their email; each person downloads their own once they confirm their email.", "type": "boolean" }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "watermark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewer_mark": { "description": "Each viewer sees their own copy of every image and PDF page, marked with the label and their confirmed email; on a video the player draws that email over the picture.", "type": "boolean" }, "allow_guests": { "description": "Guests may also view without an email: their copy is marked with their IP address, the time and a view id instead. They download only with `guest_downloads`.", "type": "boolean" }, "guest_downloads": { "description": "Guests may also download: each download is their own marked copy, carrying their guest mark. Needs `allow_guests` and `download_mark`.", "type": "boolean" }, "viewers_invite": { "description": "Viewers may invite others: a recipient who confirmed their email can invite people by email from the link's page; each invited person confirms their own email and gets their own copies and marks.", "type": "boolean" }, "download_mark": { "description": "Download with watermark: recipients download a marked copy (and see marked previews), never the original.", "type": "boolean" }, "mark_unsupported": { "description": "With `download_mark`: files that can't be marked are blocked (`block`) or downloaded as their originals (`send`).", "anyOf": [ { "const": "block", "type": "string" }, { "const": "send", "type": "string" } ] }, "bundle_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The send's first link; null for a single-file send made without one.", "type": "string" }, { "type": "null" } ] }, "available_at": { "anyOf": [ { "format": "date-time", "description": "A scheduled send's go-live time; null = live now.", "type": "string" }, { "type": "null" } ] }, "notify_on_download": { "type": "boolean" }, "feedback": { "$ref": "#/components/schemas/FeedbackSettings" }, "created_at": { "format": "date-time", "type": "string" }, "restore_until": { "anyOf": [ { "format": "date-time", "description": "End of the File Restore window; null = off.", "type": "string" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paused_by": { "anyOf": [ { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "trust", "type": "string" } ] }, { "type": "null" } ] }, "capabilities": { "anyOf": [ { "$ref": "#/components/schemas/LinkCapabilities" }, { "type": "null" } ] }, "placement": { "$ref": "#/components/schemas/LinkPlacement" }, "restore": { "$ref": "#/components/schemas/RestoreState" }, "preview": { "anyOf": [ { "$ref": "#/components/schemas/LinkPreview" }, { "type": "null" } ] }, "expiry_capped": { "anyOf": [ { "$ref": "#/components/schemas/ExpiryCapped" }, { "type": "null" } ] }, "replayed": { "const": true, "type": "boolean" } } }, "LinkEvent": { "type": "object", "required": [ "kind", "bytes", "recipient", "verified", "created_at" ], "properties": { "kind": { "description": "open, view, download, restore, forward, comment, signup, access_off, access_on.", "type": "string" }, "bytes": { "pattern": "^[0-9]+$", "type": "string" }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verified": { "type": "boolean" }, "stamp_check": { "anyOf": [ { "description": "On an end-to-end link stamped on the sender's device: what the recipient's page found on the decrypted file — found or missing; null when it didn't look.", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "LinkFeedback": { "type": "object", "required": [ "settings", "root_id", "ended_at", "kept_until", "all_approved", "files", "reviewers" ], "properties": { "settings": { "$ref": "#/components/schemas/FeedbackSettings" }, "root_id": { "description": "The transfer (its first link's id).", "type": "string" }, "ended_at": { "anyOf": [ { "format": "date-time", "description": "When the last file was revoked or expired.", "type": "string" }, { "type": "null" } ] }, "kept_until": { "anyOf": [ { "format": "date-time", "description": "When the feedback is deleted (90 days after it ended, by default).", "type": "string" }, { "type": "null" } ] }, "all_approved": { "description": "Approvals are on, every live file is approved, and nobody asked for changes.", "type": "boolean" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackFileSummary" } }, "reviewers": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackReviewerSummary" } } } }, "LinkFeedbackSummary": { "description": "The whole send's feedback totals.", "type": "object", "required": [ "comments", "favorites", "rating_count", "rating_avg", "rating_max", "approved_files", "changes_requested" ], "properties": { "comments": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "favorites": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "rating_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "rating_avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rating_max": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "approved_files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "changes_requested": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "LinkListItem": { "type": "object", "required": [ "id", "slug", "url", "file_id", "has_password", "expires_at", "max_downloads", "download_count", "note", "subject", "require_email", "access", "allowed_emails", "encrypted", "e2e_stamp", "e2e_each", "delivery", "watermark_label", "viewer_mark", "allow_guests", "guest_downloads", "viewers_invite", "download_mark", "mark_unsupported", "bundle_id", "available_at", "notify_on_download", "feedback", "created_at", "restore_until", "revoked_at", "paused_by", "scan", "preview", "feedback_summary" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "url": { "description": "The download page, https://sendflo.app/l/{slug}.", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" }, "has_password": { "type": "boolean" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "max_downloads": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "download_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "require_email": { "type": "boolean" }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "allowed_emails": { "type": "array", "items": { "type": "string" } }, "encrypted": { "type": "boolean" }, "e2e_stamp": { "description": "End-to-end sends: the sender's device stamped `watermark_label` into this file (PDFs and images) before encrypting it.", "type": "boolean" }, "e2e_each": { "description": "Mark each recipient: on a `restricted` end-to-end send of up to 50 people, the sender's device also stamped one copy per listed person with the label and their email; each person downloads their own once they confirm their email.", "type": "boolean" }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "watermark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewer_mark": { "description": "Each viewer sees their own copy of every image and PDF page, marked with the label and their confirmed email; on a video the player draws that email over the picture.", "type": "boolean" }, "allow_guests": { "description": "Guests may also view without an email: their copy is marked with their IP address, the time and a view id instead. They download only with `guest_downloads`.", "type": "boolean" }, "guest_downloads": { "description": "Guests may also download: each download is their own marked copy, carrying their guest mark. Needs `allow_guests` and `download_mark`.", "type": "boolean" }, "viewers_invite": { "description": "Viewers may invite others: a recipient who confirmed their email can invite people by email from the link's page; each invited person confirms their own email and gets their own copies and marks.", "type": "boolean" }, "download_mark": { "description": "Download with watermark: recipients download a marked copy (and see marked previews), never the original.", "type": "boolean" }, "mark_unsupported": { "description": "With `download_mark`: files that can't be marked are blocked (`block`) or downloaded as their originals (`send`).", "anyOf": [ { "const": "block", "type": "string" }, { "const": "send", "type": "string" } ] }, "bundle_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The send's first link; null for a single-file send made without one.", "type": "string" }, { "type": "null" } ] }, "available_at": { "anyOf": [ { "format": "date-time", "description": "A scheduled send's go-live time; null = live now.", "type": "string" }, { "type": "null" } ] }, "notify_on_download": { "type": "boolean" }, "feedback": { "$ref": "#/components/schemas/FeedbackSettings" }, "created_at": { "format": "date-time", "type": "string" }, "restore_until": { "anyOf": [ { "format": "date-time", "description": "End of the File Restore window; null = off.", "type": "string" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paused_by": { "anyOf": [ { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "trust", "type": "string" } ] }, { "type": "null" } ] }, "capabilities": { "anyOf": [ { "$ref": "#/components/schemas/LinkCapabilities" }, { "type": "null" } ] }, "scan": { "anyOf": [ { "$ref": "#/components/schemas/LinkScan" }, { "type": "null" } ] }, "preview": { "anyOf": [ { "$ref": "#/components/schemas/LinkPreview" }, { "type": "null" } ] }, "feedback_summary": { "anyOf": [ { "$ref": "#/components/schemas/LinkFeedbackSummary" }, { "type": "null" } ] } } }, "LinkPlacement": { "type": "object", "required": [ "tier", "relocating", "eligible" ], "properties": { "tier": { "anyOf": [ { "description": "pool or flat.", "type": "string" }, { "type": "null" } ] }, "relocating": { "type": "boolean" }, "eligible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } }, "LinkPreview": { "description": "The rendition behind a preview-only or watermarked link.", "type": "object", "required": [ "state", "kind", "variant", "pages" ], "properties": { "state": { "description": "queued, ready, failed, quota (or unsupported on create).", "type": "string" }, "kind": { "anyOf": [ { "description": "image, pdf, video or audio.", "type": "string" }, { "type": "null" } ] }, "variant": { "anyOf": [ { "description": "720p or 480p for video and audio.", "type": "string" }, { "type": "null" } ] }, "pages": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] } } }, "LinkRevokeRetained": { "type": "object", "required": [ "revoked", "retained_until", "storage_freed" ], "properties": { "revoked": { "const": true, "type": "boolean" }, "retained_until": { "format": "date-time", "type": "string" }, "storage_freed": { "const": true, "type": "boolean" } } }, "LinkScan": { "type": "object", "required": [ "state", "severity", "labels", "coverage" ], "properties": { "state": { "description": "pending, clean, flagged, failed, released or not_scannable.", "type": "string" }, "severity": { "anyOf": [ { "anyOf": [ { "const": "low", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "high", "type": "string" }, { "const": "critical", "type": "string" } ] }, { "type": "null" } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "coverage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "LinkUpdated": { "type": "object", "required": [ "id", "slug", "url", "file_id", "has_password", "expires_at", "max_downloads", "download_count", "note", "subject", "require_email", "access", "allowed_emails", "encrypted", "e2e_stamp", "e2e_each", "delivery", "watermark_label", "viewer_mark", "allow_guests", "guest_downloads", "viewers_invite", "download_mark", "mark_unsupported", "bundle_id", "available_at", "notify_on_download", "feedback", "created_at", "restore_until", "revoked_at", "paused_by", "preview", "placement", "expiry_capped" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "url": { "description": "The download page, https://sendflo.app/l/{slug}.", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" }, "has_password": { "type": "boolean" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "max_downloads": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "download_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "require_email": { "type": "boolean" }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "allowed_emails": { "type": "array", "items": { "type": "string" } }, "encrypted": { "type": "boolean" }, "e2e_stamp": { "description": "End-to-end sends: the sender's device stamped `watermark_label` into this file (PDFs and images) before encrypting it.", "type": "boolean" }, "e2e_each": { "description": "Mark each recipient: on a `restricted` end-to-end send of up to 50 people, the sender's device also stamped one copy per listed person with the label and their email; each person downloads their own once they confirm their email.", "type": "boolean" }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "watermark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewer_mark": { "description": "Each viewer sees their own copy of every image and PDF page, marked with the label and their confirmed email; on a video the player draws that email over the picture.", "type": "boolean" }, "allow_guests": { "description": "Guests may also view without an email: their copy is marked with their IP address, the time and a view id instead. They download only with `guest_downloads`.", "type": "boolean" }, "guest_downloads": { "description": "Guests may also download: each download is their own marked copy, carrying their guest mark. Needs `allow_guests` and `download_mark`.", "type": "boolean" }, "viewers_invite": { "description": "Viewers may invite others: a recipient who confirmed their email can invite people by email from the link's page; each invited person confirms their own email and gets their own copies and marks.", "type": "boolean" }, "download_mark": { "description": "Download with watermark: recipients download a marked copy (and see marked previews), never the original.", "type": "boolean" }, "mark_unsupported": { "description": "With `download_mark`: files that can't be marked are blocked (`block`) or downloaded as their originals (`send`).", "anyOf": [ { "const": "block", "type": "string" }, { "const": "send", "type": "string" } ] }, "bundle_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The send's first link; null for a single-file send made without one.", "type": "string" }, { "type": "null" } ] }, "available_at": { "anyOf": [ { "format": "date-time", "description": "A scheduled send's go-live time; null = live now.", "type": "string" }, { "type": "null" } ] }, "notify_on_download": { "type": "boolean" }, "feedback": { "$ref": "#/components/schemas/FeedbackSettings" }, "created_at": { "format": "date-time", "type": "string" }, "restore_until": { "anyOf": [ { "format": "date-time", "description": "End of the File Restore window; null = off.", "type": "string" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paused_by": { "anyOf": [ { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "trust", "type": "string" } ] }, { "type": "null" } ] }, "capabilities": { "anyOf": [ { "$ref": "#/components/schemas/LinkCapabilities" }, { "type": "null" } ] }, "preview": { "anyOf": [ { "$ref": "#/components/schemas/LinkPreview" }, { "type": "null" } ] }, "placement": { "$ref": "#/components/schemas/LinkPlacement" }, "expiry_capped": { "anyOf": [ { "$ref": "#/components/schemas/ExpiryCapped" }, { "type": "null" } ] } } }, "MyDriveLinks": { "type": "object", "required": [ "links" ], "properties": { "links": { "type": "array", "items": { "type": "object", "required": [ "id", "node_id", "slug", "url", "mode", "version_id", "audience", "emails", "password", "delivery", "expires_at", "download_limit", "downloads", "share_id", "last_opened_at", "created_at", "node" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "node_id": { "pattern": "^[0-9]+$", "description": "The file or folder it opens.", "type": "string" }, "slug": { "type": "string" }, "url": { "description": "The page anyone it lets in opens: https://sendflo.app/d/.", "type": "string" }, "mode": { "anyOf": [ { "const": "latest", "type": "string" }, { "const": "version", "type": "string" } ] }, "version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "mode version: the version it serves.", "type": "string" }, { "type": "null" } ] }, "audience": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "emails": { "description": "restricted: the addresses that may open it (each confirms with a code).", "type": "array", "items": { "type": "string" } }, "password": { "type": "boolean" }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "download_limit": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "downloads": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "share_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "Set on the link made for an outside person's share (it goes with the share).", "type": "string" }, { "type": "null" } ] }, "last_opened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "node": { "type": "object", "required": [ "id", "kind", "name", "trashed" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "kind": { "anyOf": [ { "const": "folder", "type": "string" }, { "const": "file", "type": "string" } ] }, "name": { "type": "string" }, "trashed": { "type": "boolean" } } } } } } } }, "NotificationChannel": { "type": "object", "required": [ "id", "channel", "name", "target", "active" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "channel": { "anyOf": [ { "const": "email", "type": "string" }, { "const": "slack", "type": "string" }, { "const": "discord", "type": "string" }, { "const": "teams", "type": "string" }, { "const": "webhook", "type": "string" } ] }, "name": { "type": "string" }, "target": { "description": "The address or URL, partly masked.", "type": "string" }, "active": { "type": "boolean" }, "pending": { "const": true, "type": "boolean" }, "detail": { "type": "string" } } }, "NotificationChannelLimits": { "type": "object", "required": [ "email", "slack", "discord", "teams", "webhook" ], "properties": { "email": { "type": "object", "required": [ "used", "allowance" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowance": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "slack": { "type": "object", "required": [ "used", "allowance" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowance": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "discord": { "type": "object", "required": [ "used", "allowance" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowance": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "teams": { "type": "object", "required": [ "used", "allowance" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowance": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "webhook": { "type": "object", "required": [ "used", "allowance" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowance": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } }, "Ok": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "const": true, "type": "boolean" } } }, "PersonAccessResult": { "type": "object", "required": [ "email", "open", "changes", "person" ], "properties": { "email": { "type": "string" }, "open": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "changes": { "type": "array", "items": { "type": "object", "required": [ "link_id", "change" ], "properties": { "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "change": { "anyOf": [ { "const": "removed", "type": "string" }, { "const": "restored", "type": "string" }, { "const": "none", "type": "string" }, { "const": "not_listed", "type": "string" } ] } } } }, "person": { "anyOf": [ { "$ref": "#/components/schemas/TransferPerson" }, { "type": "null" } ] } } }, "PreparedSend": { "description": "A request for the person to send files from their browser.", "type": "object", "required": [ "id", "state", "url", "links", "expires_at" ], "properties": { "id": { "type": "string" }, "state": { "anyOf": [ { "const": "waiting", "type": "string" }, { "const": "sent", "type": "string" }, { "const": "declined", "type": "string" } ] }, "url": { "description": "The page the person opens, signed in as the account the key or app acts for.", "type": "string" }, "links": { "description": "The links the person's send made (empty until `sent`).", "type": "array", "items": { "type": "object", "required": [ "id", "url", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" } } } }, "expires_at": { "format": "date-time", "type": "string" } } }, "ProjectAgentTarget": { "description": "An agent on one of your computers, bound to a project folder.", "type": "object", "required": [ "kind", "id", "project_id", "name", "destination", "device", "agent", "binding", "available", "unavailable", "public_key" ], "properties": { "kind": { "const": "project", "type": "string" }, "id": { "description": "project:", "type": "string" }, "project_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "destination": { "type": "string" }, "device": { "type": "object", "required": [ "id", "name", "platform", "online" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "online": { "type": "boolean" } } }, "agent": { "type": "object", "required": [ "ref", "name", "runner", "product", "status", "presets", "sessions", "accept", "policy" ], "properties": { "ref": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "runner": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "const": "ready", "type": "string" }, { "const": "busy", "type": "string" }, { "const": "paused", "type": "string" } ] }, { "type": "null" } ] }, "presets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPreset" } }, "sessions": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "live": { "type": "boolean" }, "last_active": { "format": "date-time", "type": "string" }, "source": { "type": "string" } } } }, "accept": { "anyOf": [ { "$ref": "#/components/schemas/AgentAccept" }, { "type": "null" } ] }, "policy": { "anyOf": [ { "type": "object", "properties": { "ask_first": { "type": "boolean" }, "permissions": { "anyOf": [ { "const": "ask", "type": "string" }, { "const": "allow", "type": "string" }, { "const": "deny", "type": "string" } ] }, "max_minutes": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "senders": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "team", "type": "string" } ] } } }, { "type": "null" } ] } } }, "binding": { "type": "object", "required": [ "agent_ref" ], "properties": { "agent_ref": { "type": "string" }, "session": { "anyOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "name", "type": "string" }, { "const": "id", "type": "string" }, { "const": "new", "type": "string" } ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "ask_first": { "type": "boolean" }, "direct_only": { "type": "boolean" }, "results": { "anyOf": [ { "const": "send", "type": "string" }, { "const": "keep", "type": "string" } ] }, "default_preset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "available": { "type": "boolean" }, "unavailable": { "anyOf": [ { "anyOf": [ { "const": "device_gone", "type": "string" }, { "const": "no_connector", "type": "string" }, { "const": "agent_missing", "type": "string" }, { "const": "agent_paused", "type": "string" } ] }, { "type": "null" } ] }, "public_key": { "anyOf": [ { "$ref": "#/components/schemas/AgentPublicKey" }, { "type": "null" } ] } } }, "ReceivedDownload": { "type": "object", "required": [ "url", "name", "size", "ticket" ], "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "ticket": { "type": "string" } } }, "ReceivedFile": { "description": "A file someone uploaded to you.", "type": "object", "required": [ "id", "file_id", "name", "size", "from", "from_email", "answers", "contact", "submission_id", "scan_state", "preview_kind", "scan_labels", "rejected_at", "reject_reason", "received_at", "expires_at", "ad_supported", "file_request_id", "inbox_id", "link", "view_only", "member_mark", "can_open_original" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "from": { "anyOf": [ { "description": "The name the uploader typed.", "type": "string" }, { "type": "null" } ] }, "from_email": { "anyOf": [ { "description": "Verified on Verified and Only-them pages; null on public ones.", "type": "string" }, { "type": "null" } ] }, "answers": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } } } }, "contact": { "anyOf": [ { "type": "object", "required": [ "name", "email", "email_verified" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" } } }, { "type": "null" } ] }, "submission_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scan_state": { "description": "rejected, or the file's scan state (pending, clean, flagged, failed, released, not_scannable).", "type": "string" }, "preview_kind": { "anyOf": [ { "anyOf": [ { "const": "image", "type": "string" }, { "const": "video", "type": "string" }, { "const": "audio", "type": "string" }, { "const": "pdf", "type": "string" } ] }, { "type": "null" } ] }, "scan_labels": { "type": "array", "items": { "type": "string" } }, "rejected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "reject_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_at": { "format": "date-time", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "ad_supported": { "type": "boolean" }, "file_request_id": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "inbox_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The inbox it was delivered into, if any.", "type": "string" }, { "type": "null" } ] }, "link": { "anyOf": [ { "type": "object", "required": [ "id", "name", "kind", "slug" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "view_only": { "description": "A view-only PDF or image (its page's setting or the team's rule): preview it; the download is refused.", "type": "boolean" }, "member_mark": { "description": "Its previews are your own copies with your email on them.", "type": "boolean" }, "can_open_original": { "description": "You're the team's Owner or an Admin: the app's View original… opens it, with a reason.", "type": "boolean" } } }, "ReceivedPreview": { "type": "object", "required": [ "url", "kind", "content_type", "plane", "name", "size" ], "properties": { "url": { "type": "string" }, "kind": { "anyOf": [ { "const": "image", "type": "string" }, { "const": "video", "type": "string" }, { "const": "audio", "type": "string" }, { "const": "pdf", "type": "string" } ] }, "content_type": { "type": "string" }, "plane": { "anyOf": [ { "const": "stored", "type": "string" }, { "const": "direct", "type": "string" } ] }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "view_only": { "type": "boolean" }, "marked": { "type": "boolean" }, "pages": { "description": "A view-only PDF's page count.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "A view-only PDF's page count.", "type": "integer" } ] }, "page_urls": { "description": "A view-only PDF's first pages; null = paused.", "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "marked_pages": { "type": "boolean" }, "preview_paused": { "type": "boolean" } } }, "ReceivedPreviewPages": { "type": "object", "required": [ "from", "pages", "page_urls" ], "properties": { "from": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "pages": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "page_urls": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "preview_paused": { "type": "boolean" } } }, "RestoreState": { "anyOf": [ { "type": "object", "required": [ "active" ], "properties": { "active": { "const": true, "type": "boolean" } } }, { "type": "object", "required": [ "active", "reason" ], "properties": { "active": { "const": false, "type": "boolean" }, "reason": { "anyOf": [ { "const": "off", "type": "string" }, { "const": "plan", "type": "string" }, { "const": "team", "type": "string" } ] } } } ] }, "RosterAgent": { "type": "object", "required": [ "id", "name", "runner", "enabled" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "runner": { "anyOf": [ { "const": "folder", "type": "string" }, { "const": "command", "type": "string" }, { "const": "acp", "type": "string" }, { "const": "channel", "type": "string" }, { "const": "session", "type": "string" } ] }, "product": { "type": "string" }, "enabled": { "type": "boolean" }, "status": { "anyOf": [ { "const": "ready", "type": "string" }, { "const": "busy", "type": "string" }, { "const": "paused", "type": "string" } ] }, "presets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPreset" } }, "accept": { "$ref": "#/components/schemas/AgentAccept" }, "sessions": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "live": { "type": "boolean" }, "last_active": { "format": "date-time", "type": "string" }, "source": { "type": "string" } } } }, "policy": { "type": "object", "properties": { "ask_first": { "type": "boolean" }, "permissions": { "anyOf": [ { "const": "ask", "type": "string" }, { "const": "allow", "type": "string" }, { "const": "deny", "type": "string" } ] }, "max_minutes": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "senders": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "team", "type": "string" } ] } } } } }, "SearchBackfill": { "type": "object", "required": [ "id", "status", "trigger", "files_seen", "queued", "done", "failed", "skipped", "processed", "total", "started_at", "finished_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "status": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "paused", "type": "string" }, { "const": "done", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "failed", "type": "string" } ] }, "trigger": { "description": "Why it ran: `trial`, `upgrade`, `reupgrade`, `converted` (a trial became a paid plan), `ocr_opt_in` (text in images was turned on), `staff`.", "type": "string" }, "files_seen": { "description": "Files it looked at (end-to-end files included: their contents are never read).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Files it looked at (end-to-end files included: their contents are never read).", "type": "integer" } ] }, "queued": { "description": "Files it sent to be read.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Files it sent to be read.", "type": "integer" } ] }, "done": { "description": "Files read.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Files read.", "type": "integer" } ] }, "failed": { "description": "Files that couldn't be read (a password-protected or broken document, or the reader gave up).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Files that couldn't be read (a password-protected or broken document, or the reader gave up).", "type": "integer" } ] }, "skipped": { "description": "Files left out, by reason: `e2e`, `type` (one we don't read), `empty`, `too_big`, `already` (read before), `cap` (past a trial's documents or OCR pages), `gone`, and for text in images `off`, `too_small`, `too_large`.", "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "processed": { "description": "Files back from the reader: `done`, `failed` and those skipped there. The progress bar's numerator.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Files back from the reader: `done`, `failed` and those skipped there. The progress bar's numerator.", "type": "integer" } ] }, "total": { "description": "Files it expects to read: an estimate while it walks, exact once the walk is over.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Files it expects to read: an estimate while it walks, exact once the walk is over.", "type": "integer" } ] }, "started_at": { "anyOf": [ { "format": "date-time", "description": "Null while it waits for its turn: backfills run first come, first served.", "type": "string" }, { "type": "null" } ] }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, "SearchIndexing": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "workspace", "kind", "team", "plan", "enabled", "trial", "cap", "until", "documents", "backfill", "ocr" ], "properties": { "workspace": { "pattern": "^[0-9]+$", "description": "The Drive's workspace.", "type": "string" }, "kind": { "anyOf": [ { "const": "personal", "type": "string" }, { "const": "team", "type": "string" } ] }, "team": { "anyOf": [ { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "description": "The team plan.", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "plan": { "anyOf": [ { "description": "The Drive plan, e.g. `drive-5tb`; null after it ended.", "type": "string" }, { "type": "null" } ] }, "enabled": { "description": "The plan searches inside files now.", "type": "boolean" }, "trial": { "type": "boolean" }, "cap": { "anyOf": [ { "description": "Documents searched inside at most (a trial's cap, or the plan's), newest first.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Documents searched inside at most (a trial's cap, or the plan's), newest first.", "type": "integer" } ] }, { "type": "null" } ] }, "until": { "anyOf": [ { "format": "date-time", "description": "The plan no longer has it: what was read stays searchable until then.", "type": "string" }, { "type": "null" } ] }, "documents": { "description": "Documents searched inside now.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Documents searched inside now.", "type": "integer" } ] }, "backfill": { "anyOf": [ { "$ref": "#/components/schemas/SearchBackfill" }, { "type": "null" } ] }, "ocr": { "anyOf": [ { "description": "Text in images: null when the plan never offered it. `backfill` reads the images and scans already there when it's turned on.", "type": "object", "required": [ "allowed", "on", "since", "until", "cap_pages", "pages", "files", "backfill" ], "properties": { "allowed": { "description": "The plan offers text in images (Drive 5 TB, Team Drive Pro and Enterprise).", "type": "boolean" }, "on": { "description": "Turned on for this Drive (PUT /v1/search/settings).", "type": "boolean" }, "since": { "anyOf": [ { "format": "date-time", "description": "When it was last turned on.", "type": "string" }, { "type": "null" } ] }, "until": { "anyOf": [ { "format": "date-time", "description": "The text read from images is kept until then: it was turned off, or the plan no longer offers it.", "type": "string" }, { "type": "null" } ] }, "cap_pages": { "anyOf": [ { "description": "A trial's pages read for text in images (200).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "A trial's pages read for text in images (200).", "type": "integer" } ] }, { "type": "null" } ] }, "pages": { "description": "Pages read for text in images so far.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Pages read for text in images so far.", "type": "integer" } ] }, "files": { "description": "Files whose text in images was read and is searchable.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Files whose text in images was read and is searchable.", "type": "integer" } ] }, "backfill": { "anyOf": [ { "$ref": "#/components/schemas/SearchBackfill" }, { "type": "null" } ] } } }, { "type": "null" } ] } } } } } }, "SearchMeta": { "description": "Present when `q` was given. `engine` is `postgres` while the search engine is unavailable: a plain name match, newest first.", "type": "object", "required": [ "engine", "page", "total", "next_page" ], "properties": { "engine": { "anyOf": [ { "const": "meilisearch", "type": "string" }, { "const": "postgres", "type": "string" } ] }, "page": { "description": "This page (1–8).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "This page (1–8).", "type": "integer" } ] }, "total": { "description": "About how many match (the search engine's estimate).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "About how many match (the search engine's estimate).", "type": "integer" } ] }, "next_page": { "anyOf": [ { "description": "Pass as `page` for more; null = the last page (200 results at most).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Pass as `page` for more; null = the last page (200 results at most).", "type": "integer" } ] }, { "type": "null" } ] } } }, "SearchSettingsItem": { "type": "object", "required": [ "workspace", "kind", "team", "plan", "ocr" ], "properties": { "workspace": { "pattern": "^[0-9]+$", "description": "The Drive's workspace: pass it back as `workspace` to change this Drive.", "type": "string" }, "kind": { "anyOf": [ { "const": "personal", "type": "string" }, { "const": "team", "type": "string" } ] }, "team": { "anyOf": [ { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "description": "The team plan.", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "plan": { "anyOf": [ { "description": "The Drive plan, e.g. `drive-5tb`.", "type": "string" }, { "type": "null" } ] }, "ocr": { "type": "object", "required": [ "allowed", "on", "since", "until", "cap_pages" ], "properties": { "allowed": { "description": "The plan offers text in images: Drive 5 TB, Team Drive Pro and Team Drive Enterprise.", "type": "boolean" }, "on": { "type": "boolean" }, "since": { "anyOf": [ { "format": "date-time", "description": "When it was last turned on.", "type": "string" }, { "type": "null" } ] }, "until": { "anyOf": [ { "format": "date-time", "description": "The text read from images is kept until then (turned off, or no longer offered); null while on.", "type": "string" }, { "type": "null" } ] }, "cap_pages": { "anyOf": [ { "description": "A trial's pages read for text in images (200).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "A trial's pages read for text in images (200).", "type": "integer" } ] }, { "type": "null" } ] } } } } }, "SendAgainPlan": { "type": "object", "required": [ "file", "targets", "eligible", "reasons", "live_links", "plan", "extend", "quota", "ad_required" ], "properties": { "file": { "type": "object", "required": [ "id", "name", "size", "expires_at", "tier", "downloaded", "capabilities" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "tier": { "anyOf": [ { "anyOf": [ { "const": "pool", "type": "string" }, { "const": "flat", "type": "string" } ] }, { "type": "null" } ] }, "downloaded": { "type": "boolean" }, "capabilities": { "anyOf": [ { "$ref": "#/components/schemas/LinkCapabilities" }, { "type": "null" } ] } } }, "targets": { "description": "Where a copy of a file on included storage may go. Both unavailable on a file on unlimited-download storage (a new link reuses it).", "type": "object", "required": [ "same", "flexible" ], "properties": { "same": { "description": "A copy on the same provider (a file on included storage): a new file under the same rules, fixed download limit.", "type": "object", "required": [ "available", "counts_as_read" ], "properties": { "available": { "type": "boolean" }, "counts_as_read": { "type": "boolean" } } }, "flexible": { "description": "A copy to unlimited-download storage within the monthly copy allowance: its download limit is editable afterwards.", "type": "object", "required": [ "available", "needs_bytes", "remaining_bytes", "size_bytes", "period_end", "reason" ], "properties": { "available": { "type": "boolean" }, "needs_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "remaining_bytes": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "size_bytes": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] }, "period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "anyOf": [ { "const": "no_flat_target", "type": "string" }, { "const": "copy_quota_exhausted", "type": "string" } ] }, { "type": "null" } ] } } } } }, "eligible": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "anyOf": [ { "const": "staging", "type": "string" }, { "const": "archived", "type": "string" }, { "const": "relocating", "type": "string" }, { "const": "scan", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "encrypted", "type": "string" }, { "const": "paused", "type": "string" }, { "const": "abuse", "type": "string" }, { "const": "suspended", "type": "string" } ] }, "message": { "type": "string" } } } }, "live_links": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "url", "expires_at", "max_downloads", "download_count", "downloads_left", "delivery", "has_password", "access" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "max_downloads": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "download_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "downloads_left": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "delivery": { "anyOf": [ { "const": "preview_download", "type": "string" }, { "const": "download_only", "type": "string" }, { "const": "preview_only", "type": "string" }, { "const": "preview_watermark", "type": "string" } ] }, "has_password": { "type": "boolean" }, "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] } } } }, "plan": { "type": "object", "required": [ "mode", "representative_file_id", "representative_expires_at", "copying", "pool_headroom", "charge_bytes", "repoints_original_links" ], "properties": { "mode": { "anyOf": [ { "const": "reuse", "type": "string" }, { "const": "copy", "type": "string" } ] }, "representative_file_id": { "pattern": "^[0-9]+$", "type": "string" }, "representative_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "copying": { "type": "boolean" }, "pool_headroom": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "charge_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "repoints_original_links": { "type": "boolean" } } }, "extend": { "type": "object", "required": [ "near_expiry", "current_until", "max_until" ], "properties": { "near_expiry": { "type": "boolean" }, "current_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "max_until": { "format": "date-time", "type": "string" } } }, "quota": { "type": "object", "required": [ "used", "limit", "after", "allowed" ], "properties": { "used": { "pattern": "^[0-9]+$", "type": "string" }, "limit": { "pattern": "^[0-9]+$", "type": "string" }, "after": { "pattern": "^[0-9]+$", "type": "string" }, "allowed": { "type": "boolean" }, "code": { "anyOf": [ { "const": "storage_quota_exceeded", "type": "string" }, { "const": "overage_requires_ad", "type": "string" } ] } } }, "ad_required": { "type": "boolean" } } }, "SendAgainResult": { "type": "object", "required": [ "mode", "link", "file", "charged_bytes" ], "properties": { "mode": { "anyOf": [ { "const": "reuse", "type": "string" }, { "const": "copy", "type": "string" } ] }, "target": { "anyOf": [ { "const": "same", "type": "string" }, { "const": "flexible", "type": "string" } ] }, "link": { "$ref": "#/components/schemas/LinkCreated" }, "file": { "type": "object", "required": [ "id", "copying" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "copying": { "type": "boolean" } } }, "charged_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "allowance_bytes": { "pattern": "^[0-9]+$", "description": "What the copy used of the monthly copy allowance (0 for `same`).", "type": "string" }, "counts_as_read": { "description": "The copy counted as a read of the original on its included storage.", "type": "boolean" } } }, "SimilarImages": { "type": "object", "required": [ "items", "similar" ], "properties": { "items": { "description": "Most alike first. Only pictures you can open now, in the Drives you can search (each one checked again).", "type": "array", "items": { "type": "object", "required": [ "id", "parent_id", "kind", "name", "size", "mime", "content_hash", "versions", "modified_at", "updated_at", "created_at", "trashed_at", "purge_after", "seq", "version_id", "path", "space", "score" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "parent_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The folder it is in (null: the top folder itself).", "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "folder", "type": "string" }, { "const": "file", "type": "string" } ] }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "description": "The current version's size (0 for a folder).", "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_hash": { "anyOf": [ { "description": "BLAKE3 (hex) of the current version, as SendFlo computed it — null until it has been checked (seconds after an upload).", "type": "string" }, { "type": "null" } ] }, "versions": { "description": "Versions kept (the current one included).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Versions kept (the current one included).", "type": "integer" } ] }, "modified_at": { "format": "date-time", "description": "When the content last changed.", "type": "string" }, "updated_at": { "format": "date-time", "description": "When anything last changed (a rename, a move…).", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "trashed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "purge_after": { "anyOf": [ { "format": "date-time", "description": "In the trash: when it is deleted for good.", "type": "string" }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "seq": { "description": "The change that last touched it (see GET /v1/drive/changes).", "type": "string" }, "thumb_url": { "anyOf": [ { "description": "A thumbnail for images.", "type": "string" }, { "type": "null" } ] }, "inside": { "description": "Trash: how many items a trashed folder holds.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Trash: how many items a trashed folder holds.", "type": "integer" } ] }, "scan_state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "clean", "type": "string" }, { "const": "flagged", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "released", "type": "string" }, { "const": "not_scannable", "type": "string" }, { "const": "error", "type": "string" } ] }, "version_id": { "anyOf": [ { "pattern": "^[0-9]+$", "description": "The current version (files): a sync client sends it back as `base_version_id` when it saves.", "type": "string" }, { "type": "null" } ] }, "lock": { "description": "Locked for editing: others' saves are refused until then (P6).", "type": "object", "required": [ "user_id", "name", "until", "mine" ], "properties": { "user_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "until": { "format": "date-time", "type": "string" }, "mine": { "type": "boolean" } } }, "conflict": { "description": "This file is a sync conflict's copy of `file_id` (P6).", "type": "object", "required": [ "id", "file_id" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" } } }, "path": { "description": "The folders above it, from the top you can see.", "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } } }, "space": { "description": "Its space (as in `GET /v1/drive/search`)." }, "score": { "description": "How alike the two pictures are: 0.5 (unrelated) to 1 (the same picture), from their image embeddings.", "type": "number" } } } }, "similar": { "anyOf": [ { "const": "searched", "type": "string" }, { "const": "not_a_picture", "type": "string" }, { "const": "not_in_plan", "type": "string" }, { "const": "no_vector", "type": "string" }, { "const": "unavailable", "type": "string" }, { "const": "blocked_by_team", "type": "string" } ] } } }, "StoredEvent": { "type": "object", "required": [ "id", "type", "version", "created_at", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "created_at": { "format": "date-time", "type": "string" }, "data": {} } }, "TeamBackupPolicy": { "type": "object", "required": [ "policy" ], "properties": { "policy": { "type": "object", "required": [ "required", "exclude", "max_mbps", "may_pause", "may_remove", "restore" ], "properties": { "required": { "type": "array", "items": { "anyOf": [ { "const": "desktop", "type": "string" }, { "const": "documents", "type": "string" }, { "const": "pictures", "type": "string" } ] } }, "exclude": { "type": "array", "items": { "type": "string" } }, "max_mbps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "may_pause": { "type": "boolean" }, "may_remove": { "type": "boolean" }, "restore": { "anyOf": [ { "const": "members", "type": "string" }, { "const": "admins", "type": "string" }, { "const": "own_devices", "type": "string" } ] } } } } }, "TeamDeviceLocations": { "type": "object", "required": [ "shows", "manages", "devices" ], "properties": { "shows": { "type": "boolean" }, "manages": { "type": "boolean" }, "devices": { "type": "array", "items": { "type": "object", "required": [ "device_id", "last" ], "properties": { "device_id": { "type": "string" }, "last": { "type": "object", "required": [ "at", "lat", "lon", "accuracy_km", "city", "region", "country", "source" ], "properties": { "at": { "format": "date-time", "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "accuracy_km": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "const": "ip", "type": "string" }, { "const": "country", "type": "string" } ] } } } } } } } }, "TeamInboxAccess": { "type": "object", "required": [ "id", "workspace_id", "subscription_id", "name", "restricted", "seat_ids", "group_ids", "members", "created_at", "added", "removed" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "workspace_id": { "pattern": "^[0-9]+$", "type": "string" }, "subscription_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "restricted": { "type": "boolean" }, "seat_ids": { "type": "array", "items": { "pattern": "^[0-9]+$", "type": "string" } }, "group_ids": { "type": "array", "items": { "pattern": "^[0-9]+$", "type": "string" } }, "members": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "created_at": { "format": "date-time", "type": "string" }, "added": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "removed": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "TeamInboxMember": { "type": "object", "required": [ "user_id", "email", "name" ], "properties": { "user_id": { "pattern": "^[0-9]+$", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "TeamInboxMembers": { "type": "object", "required": [ "id", "workspace_id", "subscription_id", "name", "restricted", "seat_ids", "group_ids", "members", "created_at", "data" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "workspace_id": { "pattern": "^[0-9]+$", "type": "string" }, "subscription_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "restricted": { "type": "boolean" }, "seat_ids": { "type": "array", "items": { "pattern": "^[0-9]+$", "type": "string" } }, "group_ids": { "type": "array", "items": { "pattern": "^[0-9]+$", "type": "string" } }, "members": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "created_at": { "format": "date-time", "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamInboxMember" } } } }, "TransferActivity": { "type": "object", "required": [ "transfer_id", "slug", "files", "people", "people_total", "events", "next_cursor" ], "properties": { "transfer_id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "required": [ "link_id", "name" ], "properties": { "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" } } } }, "people": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ActivityPerson" } }, { "type": "null" } ] }, "people_total": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" } }, "next_cursor": { "anyOf": [ { "pattern": "^[0-9]+$", "type": "string" }, { "type": "null" } ] } } }, "TransferCompleted": { "type": "object", "required": [ "id", "state", "file_id", "size" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "state": { "const": "complete", "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "approval": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "status": { "type": "string" } } } } }, "TransferCreated": { "type": "object", "required": [ "id", "name", "size", "state", "storage_class", "placement", "upload" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "size": { "description": "The size you declared (a number here; byte counts are strings elsewhere).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "The size you declared (a number here; byte counts are strings elsewhere).", "type": "integer" } ] }, "state": { "const": "open", "type": "string" }, "storage_class": { "type": "string" }, "placement": { "type": "object", "required": [ "tier", "reason", "pool_multiple", "eligible", "eligibility_reason" ], "properties": { "tier": { "anyOf": [ { "const": "pool", "type": "string" }, { "const": "flat", "type": "string" }, { "const": "fallback", "type": "string" } ] }, "reason": { "type": "string" }, "pool_multiple": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "eligible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "eligibility_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "upload": { "type": "object", "required": [ "upload_id", "part_size", "part_urls" ], "properties": { "upload_id": { "type": "string" }, "part_size": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "part_urls": { "type": "array", "items": { "type": "string" } } } } } }, "TransferDetail": { "type": "object", "required": [ "transfer_id", "files", "live", "revoked", "paused", "paused_by", "created_at", "links" ], "properties": { "transfer_id": { "pattern": "^[0-9]+$", "description": "The send's first link.", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "live": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "revoked": { "type": "boolean" }, "paused": { "type": "boolean" }, "paused_by": { "anyOf": [ { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "trust", "type": "string" } ] }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "links": { "type": "array", "items": { "type": "object", "required": [ "link_id", "slug", "url", "file_id", "name", "size", "download_count", "expires_at", "revoked_at", "paused_by", "live", "capabilities" ], "properties": { "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string" }, "file_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "download_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paused_by": { "anyOf": [ { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "trust", "type": "string" } ] }, { "type": "null" } ] }, "live": { "type": "boolean" }, "capabilities": { "anyOf": [ { "$ref": "#/components/schemas/LinkCapabilities" }, { "type": "null" } ] } } } } } }, "TransferPeople": { "type": "object", "required": [ "access", "manageable", "files", "people" ], "properties": { "access": { "anyOf": [ { "const": "public", "type": "string" }, { "const": "tracked", "type": "string" }, { "const": "restricted", "type": "string" } ] }, "manageable": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "required": [ "link_id", "name", "live" ], "properties": { "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "live": { "type": "boolean" } } } }, "people": { "type": "array", "items": { "$ref": "#/components/schemas/TransferPerson" } } } }, "TransferPerson": { "type": "object", "required": [ "email", "sources", "files", "open" ], "properties": { "email": { "type": "string" }, "sources": { "type": "array", "items": { "anyOf": [ { "const": "listed", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "emailed", "type": "string" } ] } }, "files": { "type": "array", "items": { "type": "object", "required": [ "link_id", "name", "access" ], "properties": { "link_id": { "pattern": "^[0-9]+$", "type": "string" }, "name": { "type": "string" }, "access": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "removed", "type": "string" } ] } } } }, "open": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "TransferReplies": { "type": "array", "items": { "type": "object", "required": [ "id", "from_email", "body", "encrypted", "created_at", "files_expected", "files" ], "properties": { "id": { "type": "string" }, "from_email": { "description": "The replier's verified address.", "type": "string" }, "body": { "anyOf": [ { "description": "The message: text, or on an end-to-end transfer an `sfm1.…` envelope.", "type": "string" }, { "type": "null" } ] }, "encrypted": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "files_expected": { "description": "How many files the replier said they'd send.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "How many files the replier said they'd send.", "type": "integer" } ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "item_id", "file_id", "name", "size", "scan" ], "properties": { "item_id": { "type": "string" }, "file_id": { "type": "string" }, "name": { "type": "string" }, "sealed_name": { "type": "string" }, "size": { "type": "string" }, "scan": { "type": "string" } } } }, "key_half": { "description": "A reply to a secure message: the half its key is derived from with the link's client half (packages/transfer `deriveSplitLinkKey`). Only for a signed-in sender, never an API key.", "type": "string" } } } }, "TransferReportRow": { "type": "object", "required": [ "id", "slug", "name", "size", "created_at", "expires_at", "revoked", "opens", "downloads", "views", "signups", "egress_bytes", "comments", "favorites", "rating_count", "rating_avg", "rating_max" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "size": { "pattern": "^[0-9]+$", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "revoked": { "type": "boolean" }, "opens": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "downloads": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "views": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "signups": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "egress_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "comments": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "favorites": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "rating_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "rating_avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rating_max": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "TransferRevoked": { "type": "object", "required": [ "transfer_id", "files", "live", "revoked", "paused", "paused_by", "revoked_now", "storage" ], "properties": { "transfer_id": { "pattern": "^[0-9]+$", "description": "The send's first link.", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "live": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "revoked": { "type": "boolean" }, "paused": { "type": "boolean" }, "paused_by": { "anyOf": [ { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "trust", "type": "string" } ] }, { "type": "null" } ] }, "revoked_now": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "storage": { "type": "object", "required": [ "freed_bytes", "held", "kept" ], "properties": { "freed_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "held": { "type": "array", "items": { "type": "object", "required": [ "file_id", "until" ], "properties": { "file_id": { "pattern": "^[0-9]+$", "type": "string" }, "until": { "format": "date-time", "type": "string" } } } }, "kept": { "type": "array", "items": { "type": "object", "required": [ "file_id", "reason" ], "properties": { "file_id": { "pattern": "^[0-9]+$", "type": "string" }, "reason": { "anyOf": [ { "const": "shared", "type": "string" }, { "const": "review", "type": "string" }, { "const": "restore", "type": "string" } ] } } } } } } } }, "TransferState": { "type": "object", "required": [ "transfer_id", "files", "live", "revoked", "paused", "paused_by" ], "properties": { "transfer_id": { "pattern": "^[0-9]+$", "description": "The send's first link.", "type": "string" }, "files": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "live": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "revoked": { "type": "boolean" }, "paused": { "type": "boolean" }, "paused_by": { "anyOf": [ { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "trust", "type": "string" } ] }, { "type": "null" } ] } } }, "UploadQuestion": { "description": "A question the upload page asks with every upload.", "type": "object", "required": [ "id", "label", "type", "required" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "anyOf": [ { "const": "short_text", "type": "string" }, { "const": "long_text", "type": "string" }, { "const": "email", "type": "string" }, { "const": "number", "type": "string" }, { "const": "date", "type": "string" }, { "const": "multiple_choice", "type": "string" }, { "const": "opinion_scale", "type": "string" }, { "const": "phone", "type": "string" }, { "const": "yes_no", "type": "string" }, { "const": "consent", "type": "string" } ] }, "required": { "type": "boolean" }, "help": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "settings": { "description": "The type's own settings (DZ4).", "type": "object", "properties": { "placeholder": { "type": "string" }, "max_length": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "min": { "type": "number" }, "max": { "type": "number" }, "decimals": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "unit": { "type": "string" }, "range": { "anyOf": [ { "const": "any", "type": "string" }, { "const": "past", "type": "string" }, { "const": "future", "type": "string" }, { "const": "between", "type": "string" } ] }, "from": { "type": "string" }, "to": { "type": "string" }, "week_start": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "dob": { "type": "boolean" }, "multiple": { "type": "boolean" }, "other": { "type": "boolean" }, "display": { "anyOf": [ { "const": "list", "type": "string" }, { "const": "dropdown", "type": "string" } ] }, "scale": { "anyOf": [ { "const": "0-10", "type": "string" }, { "const": "1-5", "type": "string" }, { "const": "1-10", "type": "string" } ] }, "low_label": { "type": "string" }, "high_label": { "type": "string" }, "default_country": { "type": "string" }, "statement": { "type": "string" }, "link_url": { "type": "string" }, "link_label": { "type": "string" } } } } }, "Usage": { "type": "object", "required": [ "period_start", "period_end", "direct_bytes", "relay_bytes", "turn_bytes", "link_egress_bytes", "storage_resident_bytes", "storage_received_bytes", "storage_own_bytes", "staging_resident_bytes", "storage_quota_bytes", "egress_cap_bytes", "egress_pooled", "egress_used_bytes", "downloads", "plan_class", "max_transfer_bytes", "max_file_bytes", "max_claims_per_code", "max_files_per_transfer", "max_downloads_per_file", "account_egress_multiple", "account_egress_cap_bytes", "turn_projects", "billing_cycle", "direct_is_free", "preview" ], "properties": { "period_start": { "format": "date-time", "type": "string" }, "period_end": { "format": "date-time", "type": "string" }, "direct_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "relay_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "turn_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "link_egress_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "storage_resident_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "storage_received_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "storage_own_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "staging_resident_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "storage_quota_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "egress_cap_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "egress_pooled": { "type": "boolean" }, "egress_used_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "downloads": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "plan_class": { "anyOf": [ { "const": "free", "type": "string" }, { "const": "starter", "type": "string" }, { "const": "plus", "type": "string" }, { "const": "pro", "type": "string" }, { "const": "enterprise", "type": "string" } ] }, "max_transfer_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "max_file_bytes": { "pattern": "^[0-9]+$", "description": "The same as max_transfer_bytes (kept for older clients).", "type": "string" }, "max_claims_per_code": { "type": "number" }, "max_files_per_transfer": { "type": "number" }, "max_downloads_per_file": { "type": "number" }, "account_egress_multiple": { "type": "number" }, "account_egress_cap_bytes": { "pattern": "^[0-9]+$", "type": "string" }, "turn_projects": { "type": "boolean" }, "billing_cycle": { "anyOf": [ { "anyOf": [ { "const": "monthly", "type": "string" }, { "const": "annual", "type": "string" } ] }, { "type": "null" } ] }, "direct_is_free": { "const": true, "type": "boolean" }, "preview": { "type": "object", "required": [ "images", "pdf_pages", "video_bytes" ], "properties": { "images": { "type": "object", "required": [ "used", "limit" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "limit": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "pdf_pages": { "type": "object", "required": [ "used", "limit" ], "properties": { "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "limit": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } }, "video_bytes": { "type": "object", "required": [ "used", "limit" ], "properties": { "used": { "pattern": "^[0-9]+$", "type": "string" }, "limit": { "pattern": "^[0-9]+$", "type": "string" } } }, "pooled": { "description": "A team seat: these are the team's pooled allowances and its usage, shared by every member.", "type": "boolean" } } }, "marked_views": { "description": "Team Pro and Team Enterprise seats only: the team's pooled marked views this month (each viewer's email on their own copy of an image or PDF page). ok under 80%, warn under 100%, packs (packs pay), grace (a further 10%), paused (new viewers see \"This preview is paused\").", "type": "object", "required": [ "state", "used", "included", "packs_left" ], "properties": { "state": { "anyOf": [ { "const": "ok", "type": "string" }, { "const": "warn", "type": "string" }, { "const": "packs", "type": "string" }, { "const": "grace", "type": "string" }, { "const": "paused", "type": "string" } ] }, "used": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "included": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "packs_left": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } }, "WebhookCreated": { "description": "The endpoint (as WebhookEndpoint) and its secret.", "type": "object", "required": [ "id", "url", "events", "team", "secret", "description", "filters", "payload_version", "app", "disabled", "plan_paused", "plan_pause_at", "failure_count", "failed_events", "paused_at", "paused_reason", "secret_rotated_at", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "team": { "type": "boolean" }, "secret": { "description": "Shown only now.", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filters": { "anyOf": [ {}, { "type": "null" } ] }, "payload_version": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "app": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disabled": { "type": "boolean" }, "plan_paused": { "type": "boolean" }, "plan_pause_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "failure_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "failed_events": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "paused_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paused_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secret_rotated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "event_id", "event_type", "attempt", "ok", "status_code", "error", "duration_ms", "response_excerpt", "created_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "event_id": { "description": "The event's id — the `webhook-id` header; the same on every attempt and on Resend.", "type": "string" }, "event_type": { "type": "string" }, "attempt": { "description": "1–6; 0 for a Resend.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "1–6; 0 for a Resend.", "type": "integer" } ] }, "ok": { "description": "Your server answered 2xx.", "type": "boolean" }, "status_code": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "description": "`http_`, or why no answer came (`timeout`, `dns`, `private_address`, `network`…).", "type": "string" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, { "type": "null" } ] }, "response_excerpt": { "anyOf": [ { "description": "The first 500 characters of your server's answer.", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } }, "WebhookEndpoint": { "description": "A webhook endpoint (never its secret).", "type": "object", "required": [ "id", "url", "events", "disabled", "failure_count", "failed_events", "paused_at", "team", "created_at", "description", "filters", "payload_version", "app", "plan_paused", "plan_pause_at", "paused_reason", "secret_rotated_at" ], "properties": { "id": { "pattern": "^[0-9]+$", "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "disabled": { "type": "boolean" }, "failure_count": { "description": "Failed attempts since the last success.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Failed attempts since the last success.", "type": "integer" } ] }, "failed_events": { "description": "Events in a row whose every attempt failed; the endpoint pauses at 5.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "Events in a row whose every attempt failed; the endpoint pauses at 5.", "type": "integer" } ] }, "paused_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "team": { "description": "A team-wide endpoint: every member's events.", "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filters": { "anyOf": [ { "description": "`{ file_request_ids?, link_ids?, destination_ids? }`: only events about these." }, { "type": "null" } ] }, "payload_version": { "description": "The payload version this endpoint receives (2).", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "The payload version this endpoint receives (2).", "type": "integer" } ] }, "app": { "anyOf": [ { "description": "The app that subscribed it: zapier, make or n8n.", "type": "string" }, { "type": "null" } ] }, "plan_paused": { "description": "Paused because the plan has no webhooks; an upgrade resumes it.", "type": "boolean" }, "plan_pause_at": { "anyOf": [ { "format": "date-time", "description": "The plan no longer has webhooks: this endpoint keeps running until then, then pauses.", "type": "string" }, { "type": "null" } ] }, "paused_reason": { "anyOf": [ { "anyOf": [ { "const": "failing", "type": "string" }, { "const": "address", "type": "string" }, { "const": "manual", "type": "string" }, { "const": "staff", "type": "string" } ] }, { "type": "null" } ] }, "secret_rotated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "deliveries_24h": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "success_rate_24h": { "anyOf": [ { "description": "Percent of the last 24 hours' attempts that succeeded.", "type": "number" }, { "type": "null" } ] } } }, "WebhookIntake": { "type": "object", "required": [ "id", "status", "external_refs", "count", "files", "uploader_verified", "answers", "handed_to", "expires_at", "submitted_at", "ready_at", "url" ], "properties": { "id": { "type": "string" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "opened", "type": "string" }, { "const": "submitted", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "closed", "type": "string" } ] }, "external_refs": { "anyOf": [ { "description": "Where it came from: {provider, kind, id, url?, label?}.", "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "count": { "description": "How many files arrived.", "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "description": "How many files arrived.", "type": "integer" } ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "item_id", "type", "size", "scan", "name" ], "properties": { "item_id": { "type": "string" }, "type": { "anyOf": [ { "description": "The content type.", "type": "string" }, { "type": "null" } ] }, "size": { "description": "Bytes, as a decimal string.", "type": "string" }, "scan": { "description": "pending, clean, flagged, released, not_scannable or rejected.", "type": "string" }, "name": { "description": "\"Collected file.\" unless the intake shares names.", "type": "string" } } } }, "uploader_verified": { "description": "The uploader proved their email (never the address itself).", "type": "boolean" }, "answers": { "description": "Only the answers the intake shares with the bot.", "type": "array", "items": { "type": "object", "required": [ "id", "label", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } } } }, "handed_to": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "grantee_id", "email", "permission", "expires_at" ], "properties": { "id": { "type": "string" }, "kind": { "anyOf": [ { "const": "user", "type": "string" }, { "const": "group", "type": "string" } ] }, "grantee_id": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "permission": { "anyOf": [ { "const": "view", "type": "string" }, { "const": "manage", "type": "string" } ] }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "ready_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "url": { "description": "The intake's files in SendFlo, for the people they're handed to (sign-in needed).", "type": "string" } } }, "WebhookLink": { "type": "object", "required": [ "id", "slug", "transfer_id", "file_id", "file_name", "size", "encrypted", "access", "expires_at", "url" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "transfer_id": { "description": "The send's first link.", "type": "string" }, "file_id": { "type": "string" }, "file_name": { "description": "\"Encrypted file.\" when the name is sealed.", "type": "string" }, "size": { "description": "Bytes, as a decimal string.", "type": "string" }, "encrypted": { "type": "boolean" }, "access": { "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "url": { "description": "The link in My Links (sign-in needed).", "type": "string" } } }, "WebhookReceivedItem": { "type": "object", "required": [ "id", "file_id", "file_name", "size", "from_email", "file_request_id", "received_at", "url" ], "properties": { "id": { "type": "string" }, "file_id": { "type": "string" }, "file_name": { "type": "string" }, "size": { "type": "string" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_at": { "format": "date-time", "type": "string" }, "url": { "description": "Received, in SendFlo (sign-in needed).", "type": "string" } } }, "WebhookRequest": { "type": "object", "required": [ "id", "slug", "name", "kind", "url" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "request", "type": "string" }, { "const": "reception", "type": "string" } ] }, "url": { "description": "The upload page.", "type": "string" } } }, "WebhookResent": { "type": "object", "required": [ "queued", "event_id" ], "properties": { "queued": { "const": true, "type": "boolean" }, "event_id": { "type": "string" } } }, "WebhookTransfer": { "type": "object", "required": [ "id", "slug", "file_count", "subject", "encrypted", "access", "expires_at", "url" ], "properties": { "id": { "description": "The send's first link.", "type": "string" }, "slug": { "type": "string" }, "file_count": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "subject": { "anyOf": [ { "description": "Null on an end-to-end send whose subject is sealed.", "type": "string" }, { "type": "null" } ] }, "encrypted": { "type": "boolean" }, "access": { "description": "public, tracked or restricted.", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "url": { "description": "The send in SendFlo (sign-in needed); never a download.", "type": "string" } } }, "WebhookWho": { "type": "object", "required": [ "email", "via", "country" ], "properties": { "email": { "anyOf": [ { "description": "Only a verified address, the address a per-person link was emailed to, or one the sender added.", "type": "string" }, { "type": "null" } ] }, "via": { "anyOf": [ { "const": "verified", "type": "string" }, { "const": "emailed", "type": "string" }, { "const": "sender", "type": "string" }, { "const": "anonymous", "type": "string" } ] }, "country": { "anyOf": [ { "description": "ISO 3166-1 alpha-2.", "type": "string" }, { "type": "null" } ] } } } } } }