{ "openapi": "3.1.0", "info": { "title": "Foldr API", "version": "1.1.0", "description": "Foldr's REST API. An app calls it with an OAuth access token, as the person who signed in and agreed to it, and sees exactly what that person can see in Foldr (and nothing more).\n\nShares are addressed by their id. Files and folders are addressed by their share's id plus a path inside the share, sent as `?path=` and never in the URL path; responses give back the canonical form of that path, which is the one to keep. Collections are paged with an opaque cursor. Errors are `application/problem+json` (RFC 9457): branch on `type` or `code`, never on `title` or `detail`.\n\nEvery operation carries `x-foldr-rate-cost`, what one call takes from your app's rate budget; a call answered 304 costs 1. Your app has a budget for each person and one across your organisation, and a call is charged to both only when both can pay it. `X-RateLimit-Limit` and `X-RateLimit-Remaining` describe whichever will run out first. A call over budget is answered 429 with `Retry-After`.\n\nEvery read (`GET`) also answers `HEAD`: the same status and headers as its `GET`, without the body, for a rate cost of 1. The API is meant to be called from servers, not from web pages, so it sends no CORS headers. A method an address does not answer (`OPTIONS` on any address, `GET` on a change) is answered 405 `method-not-allowed`, with an `Allow` header naming the methods that address answers; an address that is not the API's is answered 404 `not-found`.\n\nChanges need a write scope (`files.write`, `fields.write` or `sharing`) and are also limited by what the person's organisation allows your app: which kinds of change, which shares, and how many changes a day for each person (429 `daily-write-limit` when that runs out, with `Retry-After` to midnight UTC). A change refused for any reason does not count against that. A write scope never deletes, moves away or overwrites anything, and sharing is only ever asked for: an approver decides.\n\nChanges that remove or replace (`overwriteFile`, `restoreVersion`, `moveItem`, `deleteItem`) each need a scope of their own (`files.overwrite`, `files.move`, `files.delete`), which the person agrees to and the organisation allows your app separately, on shares it names, with a daily allowance counted in items (a folder counts everything in it; 429 `destructive-budget`). Every one needs `If-Match` with the ETag you last read (`*` is refused: name the version you mean). They are refused, whatever your app is allowed, for an item someone else has checked out, one under a legal hold, a published file (never moved or deleted by an app), and the document of a signing still out. Where a share's storage cannot undo a change, its administrator may refuse apps such changes there (409 `not-recoverable-here`). A delete answers where the item went (a recycle bin, earlier versions, shadow copies, or nowhere), so you can tell your user whether it can be brought back. `moveItem` with `to_share` moves to another of the person's shares (both allowed for your app): the item is copied, the copy proven whole, and only then is the original removed, so nothing is lost; a label that keeps a file in its share refuses it (403 `download-blocked`). If an original cannot be removed after its copy is made, the move answers 409 `source-remains`: the item is in both places, and the answer says where.\n\nAn organisation may require approval for your app's changes that remove or replace. Then a delete, move or version restore passes every check above and is counted against the allowance, but is not made: it answers 202 with an operation in state `pending_approval` (poll it; `Retry-After` is longer, as approvals take hours), held for someone other than the person to approve in Foldr. Once approved it is made as the person, and asked again as things stand then: if the item changed after you asked (your `If-Match` no longer names it) nothing is changed and the operation ends 412 `changed-since-requested`; if the share cannot be opened as the person then, it ends 409 `requester-not-connected` (request it again). Declined, it ends 403 `change-declined`; not decided in time, 409 `change-expired`; cancelling it (`cancelOperation`) withdraws it. Replacing a file's contents is not offered to such an app (403 `needs-approval-not-available`), and one nobody else could approve is refused (409 `no-approver`).\n\nOperations that create something take an `Idempotency-Key` header: send the same request again with the same key (after a timeout, say) and you get the first answer back, with `Idempotent-Replayed: true`, instead of a second copy. While the first request with a key is still being handled, the same key is answered 409 `conflict`: wait, then send it again. If that first request was cut off part way (a server restarting, say), its key, and any name it was writing, are free again about two minutes after it last made progress, and the same request sent again then runs. Operations that change something that exists (rename, setting a field value, and every change that removes or replaces) need `If-Match` with the ETag you last read, so a change made in the meantime is never overwritten: 428 without it, 412 when it no longer matches.\n\nFiles upload in one request at any size (`uploadFile`: `PUT` with the file as the body and `If-None-Match: *`, HTTP's \"create, never replace\"), with the body streamed to the share as it arrives; a person may have only a few uploads in flight through your app at once. Where a share offers it, an upload session sends the bytes straight to its storage instead (`createUploadSession`).\n\nA copy too big or too slow for one request (a folder, a large file, anything in Microsoft 365, or any copy sent with `Prefer: respond-async`) is made by Foldr afterwards: `copyItem` answers 202 with an operation, whose `Location` you poll (`getOperation`) after `Retry-After` seconds. It answers 202 while the copy runs, 200 with the copy once it has succeeded, and the problem the copy ended with, at that problem's own status, if it failed. This is the polling pattern Power Automate and Logic Apps follow on their own. A move to another share that is too big for one request is the same, an operation of kind `move`: every item is copied first, and the originals are removed only once the whole copy is proven. An operation is yours alone (the person, through your app), read under the scope of the change that started it (a copy `files.write`, a move `files.move`, a delete held for approval `files.delete`, a version restore held for approval `files.overwrite`), and is kept for 7 days after it finishes.\n\n## Foldr API: versioning and deprecation\n\nThis is how we change the Foldr API, and what we promise while we do.\n\n### One version, in the path\n\nThe API's major version is part of every address: `/api/v1`. Nothing else chooses a version (there's no version header and there are no dated versions).\n\n### What may change within v1 at any time\n\n- new endpoints;\n- new optional parameters;\n- new fields in a response;\n- new values in a list of values that the reference marks as open;\n- new problem types;\n- new optional headers;\n- a looser limit;\n- a different encoding of cursors, which are opaque (never build or change one);\n- a stable `id` for files and folders, if Foldr ever has one.\n\nSo your client should ignore fields it doesn't recognise, and accept values it doesn't recognise wherever the reference says a list is open.\n\n### What needs a new version\n\n- removing or renaming an endpoint, field or parameter;\n- changing a field's type or meaning;\n- making an optional input required;\n- validating an existing input more strictly;\n- a different status code for an existing condition;\n- a changed default;\n- a different scope on an existing endpoint;\n- changing how pages or ids work;\n- changing how paths are written back to you (their case, their Unicode form, the leading `/`).\n\nChanges like these go into a new major version (`/api/v2`), or come through the deprecation route below.\n\n### Security fixes\n\nA change that closes a security hole may break a client without notice. We'll say what changed straight afterwards.\n\n### How long things last\n\n- A major version is supported for at least 24 months after the next one is generally available.\n- A deprecated endpoint keeps working for at least 12 months before its sunset date.\n- If you run Foldr on your own server, removal also waits for a major Foldr release, and the release notes of the two releases before it say what's going, because your server upgrades on your schedule rather than ours.\n\n### How you'll know\n\n- a `Deprecation` header (RFC 9745) on every response from a deprecated endpoint;\n- a `Sunset` header (RFC 8594) once its date is set;\n- a `Link` header with `rel=\"deprecation\"` pointing to the notice;\n- `deprecated: true` on the endpoint in the OpenAPI document;\n- the document's changelog (`info.x-changelog`), with the document's own version number (`info.version`), which is separate from the API's major version.\n\n### Beta endpoints\n\nAn endpoint marked `x-foldr-stability: beta` may change with 30 days' notice and stays off unless your organisation opts in. There are no beta endpoints in v1 today.", "x-api-major": 1, "x-changelog": [ { "version": "1.1.0", "changes": [ "restoreVersion takes a new optional body field, as_copy. With it true the chosen version is written beside the file as a new file (for example \"Report (3 Nov 2026 14.02).docx\", the first free name) and nothing is replaced: no If-Match is needed, the answer is 201 with the new file, and it is not counted against the allowance or held for approval.", "On an SMB share, restoreVersion over a file that no shadow copy holds (it changed since the newest one) is refused 409 not-recoverable-here, because the overwrite would lose what the file holds now. Restore as a copy instead." ] }, { "version": "1.0.0", "changes": [ "First release of API v1: read access to shares, files and folders, file contents, search and custom fields, and the signed-in person's profile.", "Changes, each within what the person's organisation allows your app: create folders, upload files (streamed through Foldr, or straight to the storage with an upload session), rename and copy files and folders, set custom field values, and ask to share (an approver decides). Creates take an Idempotency-Key; renames and field values need If-Match. A copy too big for one request is answered 202 with an operation to poll.", "Changes that remove or replace, each under a scope of its own that your app is allowed separately: replace a file's contents, list a file's versions and restore one, move files and folders within a share or to another share, and delete them. Each needs If-Match; a delete says where the item went. A move to another share copies, proves the copy, then removes the original; one too big for a request is an operation to poll.", "Approval mode: where the organisation requires approval for your app's changes that remove or replace, a delete, move or version restore is answered 202 with an operation that waits for an approver, and is made as the person once approved (or ends declined, expired or withdrawn, with nothing changed). Replacing a file's contents is not offered to such an app." ] } ] }, "servers": [ { "url": "https://{tenant}/api/v1", "description": "Your Foldr site.", "variables": { "tenant": { "default": "example.foldr.cloud", "description": "The address you sign in to Foldr at: your-company.foldr.cloud, your own domain, or your server's name." } } } ], "paths": { "/fields": { "get": { "operationId": "listFields", "summary": "The custom fields the person can see, across their shares", "tags": [ "Fields" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "responses": { "200": { "description": "Every matching Field.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } } } } }, "400": { "description": "Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 1 } }, "/me": { "get": { "operationId": "getMe", "summary": "Who the token acts as", "description": "The same body as GET /api/me, which stays.", "tags": [ "Me" ], "security": [ { "foldr_oauth": [ "profile" ] } ], "responses": { "200": { "description": "The Me.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "description": "Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 1 } }, "/operations": { "get": { "operationId": "listOperations", "summary": "The person's operations through this app, newest first, finished ones included for 7 days after they finish: for a client that lost an operation's id", "description": "Copies with files.write, moves with files.move, deletes held for approval with files.delete, version restores held for approval with files.overwrite. Each is the operation as it stands; poll one with getOperation for its answer.", "tags": [ "Operations" ], "security": [ { "foldr_oauth": [ "files.write" ] }, { "foldr_oauth": [ "files.move" ] }, { "foldr_oauth": [ "files.delete" ] }, { "foldr_oauth": [ "files.overwrite" ] } ], "parameters": [ { "name": "cursor", "in": "query", "description": "From a previous page's next_cursor.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Operations per page, from 1: default 50; more than 200 is read as 200. 0 is refused.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "One page of Operations.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationPage" } } } }, "400": { "description": "One of: Invalid cursor (invalid-cursor); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-cursor", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 1 } }, "/operations/{id}": { "get": { "operationId": "getOperation", "summary": "An operation, as it stands", "description": "While it is queued, running or cancelling: 202 with Retry-After, ask again after that many seconds. Once it has succeeded: 200, its result what it made (Content-Location names it). Once it has failed: the problem it ended with, at that problem's own status (409 conflict, 403 download-blocked, 409 copy-incomplete, 409 source-remains, ...), carrying the operation as `operation`. Once cancelled: 409 operation-cancelled, carrying it. Held for an approver (state pending_approval): 202 with a longer Retry-After until someone decides; declined, 403 change-declined; not decided in time, 409 change-expired; approved but the item changed since it was asked for, 412 changed-since-requested; approved but the share could not be opened as the person, 409 requester-not-connected (request it again). This is the polling pattern Power Automate and Logic Apps follow on their own. A copy is read under files.write, a move under files.move, a delete held for approval under files.delete and a version restore under files.overwrite. Another person's or another app's operation, or one your token has not the scope for, is the same 404 as one that does not exist.", "tags": [ "Operations" ], "security": [ { "foldr_oauth": [ "files.write" ] }, { "foldr_oauth": [ "files.move" ] }, { "foldr_oauth": [ "files.delete" ] }, { "foldr_oauth": [ "files.overwrite" ] } ], "parameters": [ { "name": "id", "in": "path", "description": "The operation's id (from the Location of the 202 that started it).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "It has succeeded: the operation, its result what it made (a copy or a move: the item, named by Content-Location; a delete: its deletion).", "headers": { "Content-Location": { "description": "Where to read what the operation made (the item at its canonical path). Absent when it made no item (a delete).", "required": false, "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "202": { "description": "Still under way: the operation, its progress so far. Ask again after Retry-After.", "headers": { "Location": { "description": "Where to poll the operation: GET it until it answers anything but 202.", "required": true, "schema": { "type": "string", "format": "uri" } }, "Retry-After": { "description": "Seconds to wait before polling again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "400": { "description": "One of: Copy into itself (copy-into-itself); Invalid path (invalid-path); Invalid request (invalid-request); Move into itself (move-into-itself).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "copy-into-itself", "invalid-path", "invalid-request", "move-into-itself" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Change declined (change-declined); Download blocked (download-blocked); Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "change-declined", "download-blocked", "insufficient-scope", "legal-hold", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); Change not approved in time (change-expired); Conflict (conflict); Copy incomplete (copy-incomplete); Out for signature (envelope-source); Folder too large (folder-too-large); Not a file (not-a-file); Not a folder (not-a-folder); Not recoverable here (not-recoverable-here); Operation cancelled (operation-cancelled); Published (published); Not connected when approved (requester-not-connected); Moved, but the original remains (source-remains); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "approved-version-unavailable", "change-expired", "conflict", "copy-incomplete", "envelope-source", "folder-too-large", "not-a-file", "not-a-folder", "not-recoverable-here", "operation-cancelled", "published", "requester-not-connected", "source-remains", "storage-account-not-connected" ] }, "412": { "description": "Changed since requested (changed-since-requested).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "changed-since-requested" ] }, "413": { "description": "One of: Copy too large (copy-too-large); Too large (too-large).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "copy-too-large", "too-large" ] }, "423": { "description": "Checked out (checked-out).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "checked-out" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Copy interrupted (copy-interrupted); Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "copy-interrupted", "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 1 } }, "/operations/{id}/cancel": { "post": { "operationId": "cancelOperation", "summary": "Ask an operation to stop", "description": "One held for an approver is withdrawn at once, nothing changed (its approval then says withdrawn). A queued one is cancelled at once; a running one stops at its next item, and the copy it had made so far is removed (a move's original is untouched). Answers 204 either way: poll the operation to see it end (409 operation-cancelled). An operation that has already finished cannot be cancelled (409 operation-finished); a copy whose last item is done as the cancel arrives succeeds, and so does a move already removing its originals (phase deleting): stopping it then would leave the item split between two places.", "tags": [ "Operations" ], "security": [ { "foldr_oauth": [ "files.write" ] }, { "foldr_oauth": [ "files.move" ] }, { "foldr_oauth": [ "files.delete" ] }, { "foldr_oauth": [ "files.overwrite" ] } ], "parameters": [ { "name": "id", "in": "path", "description": "The operation's id.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Cancelled, or asked to stop.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } } }, "400": { "description": "Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "Operation finished (operation-finished).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "operation-finished" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 2 } }, "/search": { "get": { "operationId": "search", "summary": "Search the person's indexed shares by keyword", "description": "Hits are ordered by relevance within each search index; where the person's shares are spread over several indexes, pages walk them one after another. Shares that could not be searched are named in not_searched.", "tags": [ "Search" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "q", "in": "query", "description": "The words to search for, at most 500 characters.", "required": true, "schema": { "type": "string" } }, { "name": "share_id", "in": "query", "description": "Search only this share (its id).", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "From a previous page's next_cursor, with the same q and share_id.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Hits per page, from 1: default 20; more than 50 is read as 50. 0 is refused.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The SearchResults.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResults" } } } }, "400": { "description": "One of: Invalid cursor (invalid-cursor); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-cursor", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "410": { "description": "Cursor expired (cursor-expired).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "cursor-expired" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 3 } }, "/share-requests": { "get": { "operationId": "listShareRequests", "summary": "The person's own sharing requests, newest first, through any app", "tags": [ "ShareRequests" ], "security": [ { "foldr_oauth": [ "sharing" ] } ], "parameters": [ { "name": "cursor", "in": "query", "description": "From a previous page's next_cursor.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Requests per page, from 1: default 50; more than 200 is read as 200. 0 is refused.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "One page of ShareRequests.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareRequestPage" } } } }, "400": { "description": "One of: Invalid cursor (invalid-cursor); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-cursor", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 1 } }, "/share-requests/{id}": { "get": { "operationId": "getShareRequest", "summary": "One of the person's own sharing requests, as it stands now", "description": "Another person's, or one that does not exist, is the same 404.", "tags": [ "ShareRequests" ], "security": [ { "foldr_oauth": [ "sharing" ] } ], "parameters": [ { "name": "id", "in": "path", "description": "The request's id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The ShareRequest.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareRequest" } } } }, "400": { "description": "Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 1 } }, "/shares": { "get": { "operationId": "listShares", "summary": "List the shares the person can read", "description": "Shares whose file server is down just now are listed with reachable false, after the rest. Shares that only open with the person's own password are not listed: a token carries none.", "tags": [ "Shares" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "cursor", "in": "query", "description": "From a previous page's next_cursor.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Shares per page, from 1: default 100; more than 200 is read as 200. 0 is refused.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "One page of Shares.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharePage" } } } }, "400": { "description": "One of: Invalid cursor (invalid-cursor); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-cursor", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "410": { "description": "Cursor expired (cursor-expired).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "cursor-expired" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 1 } }, "/shares/{share_id}": { "get": { "operationId": "getShare", "summary": "One of the person's shares, by id", "description": "A share that does not exist and one that is not the person's get the same 404.", "tags": [ "Shares" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Share.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Share" } } } }, "400": { "description": "Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 1 } }, "/shares/{share_id}/children": { "get": { "operationId": "listChildren", "summary": "The files and folders in a folder, folders first, then by name", "description": "Pages hold a snapshot of the folder taken on the first page and kept for a minute while it is paged through: a folder that changes in the meantime shows the snapshot; a cursor whose snapshot has gone answers 410, so start again from the first page. A folder of more than 25,000 entries is paged as the first 25,000 the storage lists, and every page of it says truncated: true.", "tags": [ "Items" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path of the folder; \"/\", empty or absent for the top of the share (a path of only spaces is refused).", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "From a previous page's next_cursor.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Items per page, from 1: default 100; more than 200 is read as 200. 0 is refused.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "One page of Items.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPage" } } } }, "400": { "description": "One of: Invalid cursor (invalid-cursor); Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-cursor", "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Not a folder (not-a-folder); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "not-a-folder", "storage-account-not-connected" ] }, "410": { "description": "Cursor expired (cursor-expired).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "cursor-expired" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable" ] } }, "x-foldr-rate-cost": 1 } }, "/shares/{share_id}/content": { "get": { "operationId": "getContent", "summary": "Download a file", "description": "On a share with direct downloads this is a 302 to a short-lived URL on the storage itself, which carries its own authorisation (follow it without the Foldr token); ?direct=false keeps the bytes coming through Foldr. Range requests are honoured where the storage can seek; If-None-Match with the file's etag answers 304. A native Google document (an item whose export is set) is downloaded as its export, always through Foldr: Content-Type is export.mime_type, Content-Disposition names it with export.extension (Minutes.docx), and as its length is not known until it has been sent there is no Content-Length and no ranges (Accept-Ranges: none; a Range is answered 200, whole). A Google type with no export (a Form) is 409 not-downloadable.", "tags": [ "Content" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path of the file.", "required": false, "schema": { "type": "string" } }, { "name": "direct", "in": "query", "description": "false: never redirect, send the bytes through Foldr. Absent: the share's own setting.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The whole file. Content-Type is the file's own type.", "headers": { "Content-Disposition": { "description": "attachment, naming the file (filename*, UTF-8).", "required": true, "schema": { "type": "string" } }, "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "The range asked for. Content-Type is the file's own type.", "headers": { "Content-Disposition": { "description": "attachment, naming the file (filename*, UTF-8).", "required": true, "schema": { "type": "string" } }, "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Download it from the Location URL.", "headers": { "Location": { "description": "Where to go.", "required": true, "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } } }, "304": { "description": "If-None-Match named the file as it is now.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Download blocked (download-blocked); Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "download-blocked", "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); Not a file (not-a-file); Not downloadable (not-downloadable); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "approved-version-unavailable", "not-a-file", "not-downloadable", "storage-account-not-connected" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable" ] } }, "x-foldr-rate-cost": 5 }, "put": { "operationId": "overwriteFile", "summary": "Replace a file's contents: the request body is the new contents, streamed to the share as it arrives, at any size (Content-Length required)", "description": "Send If-Match with the file's ETag as you last read it (GET .../item, a listing, or a write's answer): without it 428, with a stale one 412, so nothing is replaced that you did not look at. A body that ends before its Content-Length leaves the file exactly as it was. Needs files.overwrite, allowed for your app on this share. Refused for a file someone else has checked out (423), one under a legal hold (403), the document of a signing still out (409), and, for a person who may only read the approved version of a published file, that file (403). Where the share's storage keeps no earlier versions an administrator may refuse apps this change (409 not-recoverable-here). Answers the file with its new ETag. Not offered to an app whose administrator requires approval for its changes (403 needs-approval-not-available): new contents cannot be held for approval.", "tags": [ "Changes" ], "security": [ { "foldr_oauth": [ "files.overwrite" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "The path of the file to replace.", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "The file's ETag as you last read it (any form this API gave you for it; a list matches if any member does). \"*\" is refused.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The file's new contents, exactly Content-Length bytes.", "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The file, with its new ETag.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not offered in approval mode (needs-approval-not-available); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "legal-hold", "needs-approval-not-available", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Out for signature (envelope-source); Not a file (not-a-file); Not recoverable here (not-recoverable-here); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "envelope-source", "not-a-file", "not-recoverable-here", "storage-account-not-connected" ] }, "412": { "description": "Precondition failed (precondition-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-failed" ] }, "413": { "description": "Too large (too-large).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "too-large" ] }, "423": { "description": "Checked out (checked-out).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "checked-out" ] }, "428": { "description": "Precondition required (precondition-required).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-required" ] }, "429": { "description": "One of: Daily limit of removals reached (destructive-budget); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "destructive-budget", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 5 } }, "/shares/{share_id}/copy": { "post": { "operationId": "copyItem", "summary": "Copy a file or a folder, within its share or into another of the person's shares", "description": "to_path is the copy's full path; the folder it goes in must exist. Something already called that is never replaced (on_conflict \"fail\" answers 409, \"rename\" picks the first free name); a folder copy is a new folder, never merged into one already there. Both shares must be ones your app may change. The original is not touched. A copy into another share is refused when a label on the file stops it being downloaded. A small file is copied in the request and answered 201 with the copy. A folder, a file whose source or destination is in Microsoft 365, a file over 64 MiB going between storages or over 1 GiB within one, or any copy sent with Prefer: respond-async, is copied by Foldr afterwards: answered 202 with an operation, its Location the address to poll (getOperation) until it answers 200 with the copy or the problem the copy ended with. A folder copy takes at most 10,000 files and folders, nested at most 64 deep (413 copy-too-large); a person may have at most 20 copies waiting through one app (429), and 2 run at once. Send an Idempotency-Key: the same request sent again with it answers the first answer (the same operation) and copies nothing more; after 24 hours, an operation still under way is answered 202 again, and one that has finished its final answer: 201 with the copy, or the problem it ended with, carrying the operation.", "tags": [ "Items" ], "security": [ { "foldr_oauth": [ "files.write" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The id of the share the file or folder is in.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A value of your own, 1 to 255 visible ASCII characters, new for each new request. The same key with the same request within 24 hours answers the first answer again (for a copy made afterwards, the same operation) and copies nothing more; later, the operation as it stands (202 while under way, its final answer once finished); with a different request it is refused (422).", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "description": "respond-async: copy afterwards and answer 202 with an operation, whatever the size (Preference-Applied says it was). Without it, small files are copied in the request.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyBody" } } } }, "responses": { "201": { "description": "The copy, at its canonical path.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "Location": { "description": "Where to read what was made.", "required": true, "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "202": { "description": "The copy will be made by Foldr: the operation. Poll its Location after Retry-After seconds.", "headers": { "Location": { "description": "Where to poll the operation: GET it until it answers anything but 202.", "required": true, "schema": { "type": "string", "format": "uri" } }, "Preference-Applied": { "description": "respond-async: sent when the request's Prefer: respond-async is why this is an operation rather than an answer in the request (RFC 7240). Absent when Foldr chose the operation itself (a folder, a large file, Microsoft 365).", "required": false, "schema": { "type": "string", "enum": [ "respond-async" ] } }, "Retry-After": { "description": "Seconds to wait before polling again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "400": { "description": "One of: Copy into itself (copy-into-itself); Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "copy-into-itself", "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Download blocked (download-blocked); Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "download-blocked", "insufficient-scope", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); Conflict (conflict); Copy incomplete (copy-incomplete); Not a file (not-a-file); Not a folder (not-a-folder); Operation cancelled (operation-cancelled); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "approved-version-unavailable", "conflict", "copy-incomplete", "not-a-file", "not-a-folder", "operation-cancelled", "storage-account-not-connected" ] }, "413": { "description": "One of: Copy too large (copy-too-large); Too large (too-large).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "copy-too-large", "too-large" ] }, "422": { "description": "Idempotency key reused (idempotency-key-reused).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "idempotency-key-reused" ] }, "429": { "description": "One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "daily-write-limit", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Copy interrupted (copy-interrupted); Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "copy-interrupted", "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 2 } }, "/shares/{share_id}/download-url": { "get": { "operationId": "getDownloadUrl", "summary": "A short-lived URL that downloads the file straight from its storage, for clients that cannot follow a redirect to another host", "description": "Only on shares with direct downloads; the same governance rules as content apply. A native Google document is never given one (it is exported through Foldr: use content).", "tags": [ "Content" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path of the file.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The DownloadUrl.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadUrl" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Download blocked (download-blocked); Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "download-blocked", "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); No direct download (no-direct-download); Not a file (not-a-file); Not downloadable (not-downloadable); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "approved-version-unavailable", "no-direct-download", "not-a-file", "not-downloadable", "storage-account-not-connected" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable" ] } }, "x-foldr-rate-cost": 2 } }, "/shares/{share_id}/field-values": { "get": { "operationId": "getFieldValues", "summary": "The custom field values on one file or folder", "description": "A field that holds several values appears once per value. The ETag header covers the whole set; send it back as If-None-Match for a 304 while nothing has changed.", "tags": [ "Fields" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path of the file or folder.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every matching FieldValue.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FieldValue" } } } } }, "304": { "description": "If-None-Match named the values as they are now.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "approved-version-unavailable", "storage-account-not-connected" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable" ] } }, "x-foldr-rate-cost": 1 } }, "/shares/{share_id}/field-values/{field_id}": { "put": { "operationId": "setFieldValue", "summary": "Set one custom field on one file, through the field's own rules: the person must be allowed to set it, a field with allowed values takes one of them, and a value must suit the field's type (422 otherwise)", "description": "A field whose change needs approval is held for its approver. Send If-Match with the ETag of the file's field values as you last read them (GET .../field-values): without one the change is refused (428), and if anything changed since, 412. Answers every value on the file the person can see, as GET .../field-values does, with the new ETag.", "tags": [ "Fields" ], "security": [ { "foldr_oauth": [ "fields.write" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "field_id", "in": "path", "description": "The field's id (see GET /fields).", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "description": "The ETag of the file's field values as you last read them; \"*\" for whatever they are now.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFieldValueBody" } } } }, "responses": { "200": { "description": "The file's field values now.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FieldValue" } } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Not a file (not-a-file); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "not-a-file", "storage-account-not-connected" ] }, "412": { "description": "Precondition failed (precondition-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-failed" ] }, "422": { "description": "Validation failed (validation-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "validation-failed" ] }, "423": { "description": "Checked out (checked-out).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "checked-out" ] }, "428": { "description": "Precondition required (precondition-required).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-required" ] }, "429": { "description": "One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "daily-write-limit", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 2 } }, "/shares/{share_id}/files": { "put": { "operationId": "uploadFile", "summary": "Upload a new file: the request body is the file", "description": "The bytes stream to the share as they arrive, at any size; Content-Length is required, so a share without room refuses before the first byte. New files only, said as HTTP says it: send If-None-Match: * (required, 428 without it). Something already called that is never replaced: the default answers 412 precondition-failed; on_conflict=rename picks the first free name instead, so read the answer's path (and Location). If-Match names a file to replace, which this operation never does: sending it is refused (400); replace a file with overwriteFile. A person may have only a few uploads in flight through your app at once (429 with Retry-After beyond that). On a share that offers it, an upload session (createUploadSession) sends the bytes straight to the storage instead. Send an Idempotency-Key: the same upload sent again with it (the same path, query and bytes) answers the first answer and writes nothing; other bytes under the same key are refused (422).", "tags": [ "Items" ], "security": [ { "foldr_oauth": [ "files.write" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "The new file's full path in the share, its name last. The folder it goes in must exist.", "required": true, "schema": { "type": "string" } }, { "name": "on_conflict", "in": "query", "description": "What to do when something is already called that: \"fail\" (the default) or \"rename\". Nothing is ever replaced.", "required": false, "schema": { "type": "string", "enum": [ "fail", "rename" ] } }, { "name": "If-None-Match", "in": "header", "description": "\"*\": create only, never replace (RFC 9110). Required; no other value is taken.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A value of your own, 1 to 255 visible ASCII characters, new for each new upload. Sending the same upload again (the same path, query and bytes) with the same key within 24 hours answers the first answer and writes nothing (the body is read again, to be sure it is the same); with a different request, other bytes included, it is refused (422).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The file's bytes, exactly Content-Length of them.", "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "The file, at its canonical path.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "Location": { "description": "Where to read what was made.", "required": true, "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Conflict (conflict); Not a folder (not-a-folder); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "conflict", "not-a-folder", "storage-account-not-connected" ] }, "412": { "description": "Precondition failed (precondition-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-failed" ] }, "413": { "description": "Too large (too-large).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "too-large" ] }, "422": { "description": "Idempotency key reused (idempotency-key-reused).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "idempotency-key-reused" ] }, "428": { "description": "Precondition required (precondition-required).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-required" ] }, "429": { "description": "One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "daily-write-limit", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 5 } }, "/shares/{share_id}/folders": { "post": { "operationId": "createFolder", "summary": "Create a folder", "description": "The folder it goes in must exist; the new name follows the name rules (one name, no \"/\", no spaces at either end). Something already called that is never replaced: on_conflict \"fail\" answers 409, \"rename\" picks the first free name, so read the answer's path. Send an Idempotency-Key: sending the same request again with the same key answers the first answer again and creates nothing more.", "tags": [ "Items" ], "security": [ { "foldr_oauth": [ "files.write" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A value of your own, 1 to 255 visible ASCII characters (a UUID, say), new for each new request. The same key with the same request within 24 hours answers the first answer again (with Idempotent-Replayed: true) and changes nothing; with a different request it is refused (422). Your app's keys are its own, for each person.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderBody" } } } }, "responses": { "201": { "description": "The folder, at its canonical path.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "Location": { "description": "Where to read what was made.", "required": true, "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Conflict (conflict); Not a folder (not-a-folder); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "conflict", "not-a-folder", "storage-account-not-connected" ] }, "413": { "description": "Too large (too-large).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "too-large" ] }, "422": { "description": "Idempotency key reused (idempotency-key-reused).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "idempotency-key-reused" ] }, "429": { "description": "One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "daily-write-limit", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 2 } }, "/shares/{share_id}/item": { "get": { "operationId": "getItem", "summary": "One file or folder, at its canonical path", "description": "The ETag header is the item's etag; send it back as If-None-Match for a 304 while the item is unchanged.", "tags": [ "Items" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "Path inside the share; \"/\", empty or absent for the top (a path of only spaces is refused). The leading \"/\" is optional.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Item.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "304": { "description": "If-None-Match named the item as it is now.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "approved-version-unavailable", "storage-account-not-connected" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable" ] } }, "x-foldr-rate-cost": 1 } }, "/shares/{share_id}/items": { "delete": { "operationId": "deleteItem", "summary": "Delete a file, or a folder with everything in it (at most 1,000 items: 409 folder-too-large beyond that)", "description": "Send If-Match with the item's ETag as you last read it (428 without, 412 stale). Needs files.delete, allowed for your app on this share. Refused for anything checked out by someone else (423), under a legal hold (403), published (409 published), or the document of a signing still out (409). Where the share's storage keeps no bin an administrator may refuse apps deletions there (409 not-recoverable-here). Answers 200 with what was deleted and where its storage keeps it now (recoverable, destination, where), so you can tell your user whether it can be brought back; a folder counts every item in it against your app's daily allowance. Send an Idempotency-Key: the same request sent again with it answers the first answer. For an app whose administrator requires approval for its changes, it is not made at once: once every check has passed (and the items are counted against the allowance) it is answered 202 with an operation in state pending_approval, held for someone other than the person to approve in Foldr, then made as the person; poll it at its Location (getOperation). Refused 409 no-approver when nobody else could approve it. Once approved and made, the operation's deletion says what was deleted and where it is now.", "tags": [ "Changes" ], "security": [ { "foldr_oauth": [ "files.delete" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "The path of the file or folder to delete. The top of a share cannot be deleted.", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "The item's ETag as you last read it. \"*\" is refused.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A value of your own, 1 to 255 visible ASCII characters, new for each new request. The same key with the same request within 24 hours answers the first answer again (what was deleted) and deletes nothing more; with a different request it is refused (422).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "What was deleted, and where it is now.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deletion" } } } }, "202": { "description": "Held for an approver (the app's administrator requires approval for its changes): the operation, state pending_approval. Poll its Location after Retry-After seconds.", "headers": { "Location": { "description": "Where to poll the operation: GET it until it answers anything but 202.", "required": true, "schema": { "type": "string", "format": "uri" } }, "Retry-After": { "description": "Seconds to wait before polling again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Change declined (change-declined); Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "change-declined", "insufficient-scope", "legal-hold", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Change not approved in time (change-expired); Out for signature (envelope-source); Folder too large (folder-too-large); No approver (no-approver); Not recoverable here (not-recoverable-here); Operation cancelled (operation-cancelled); Published (published); Not connected when approved (requester-not-connected); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "change-expired", "envelope-source", "folder-too-large", "no-approver", "not-recoverable-here", "operation-cancelled", "published", "requester-not-connected", "storage-account-not-connected" ] }, "412": { "description": "One of: Changed since requested (changed-since-requested); Precondition failed (precondition-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "changed-since-requested", "precondition-failed" ] }, "422": { "description": "Idempotency key reused (idempotency-key-reused).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "idempotency-key-reused" ] }, "423": { "description": "Checked out (checked-out).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "checked-out" ] }, "428": { "description": "Precondition required (precondition-required).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-required" ] }, "429": { "description": "One of: Daily limit of removals reached (destructive-budget); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "destructive-budget", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 5 } }, "/shares/{share_id}/move": { "post": { "operationId": "moveItem", "summary": "Move a file or a folder (with everything in it) to another folder, in the same share or in another of the person's shares (to_share), keeping its name or giving it a new one", "description": "to_path is its full new path; the folder it goes in must exist. Something already there is never replaced (on_conflict \"fail\": 409; \"rename\": the first free name, so read the answer's path). Send If-Match with the item's ETag as you last read it (428 without, 412 stale). Needs files.move, allowed for your app on this share (and, for another share, on that one too). Refused for anything checked out by someone else (423), under a legal hold (403), published (409 published: an app never moves a published file, or a folder holding one), or the document of a signing still out (409), and for a folder of more than 1,000 items (409 folder-too-large). A folder counts every item in it against your app's daily allowance. Within a share the storage moves it in one step. To another share it is copied, the copy proven whole, and only then is the original removed: refused for a file a label keeps in its share (403 download-blocked), and for a folder nested more than 64 deep. A small file is moved in the request (200, the item at its new place). A folder, a file whose source or destination is in Microsoft 365, a file over 64 MiB, or any move to another share sent with Prefer: respond-async, is moved by Foldr afterwards: answered 202 with an operation (kind move) to poll at its Location (getOperation): it copies every item first and removes the originals only once the whole copy is proven; cancelled while copying, its partial copy is removed and the original left as it was; once it is removing the originals it is too late to cancel. If the copy is whole but an original could not be removed, the move ends 409 source-remains: the item is in both places, nothing is lost, and the answer says where. Send an Idempotency-Key: the same request sent again with it answers the first answer (for a move made afterwards, the same operation) and moves nothing more. For an app whose administrator requires approval for its changes, it is not made at once: once every check has passed (and the items are counted against the allowance) it is answered 202 with an operation in state pending_approval, held for someone other than the person to approve in Foldr, then made as the person; poll it at its Location (getOperation). Refused 409 no-approver when nobody else could approve it.", "tags": [ "Changes" ], "security": [ { "foldr_oauth": [ "files.move" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "The item's ETag as you last read it. \"*\" is refused.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A value of your own, 1 to 255 visible ASCII characters, new for each new request. The same key with the same request within 24 hours answers the first answer again (for a move made afterwards, the same operation) and moves nothing more; later, an operation still under way is answered 202 again and a finished one its final answer (200 with the item, or the problem it ended with); with a different request it is refused (422).", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "description": "respond-async: for a move to another share, move it afterwards and answer 202 with an operation, whatever the size (Preference-Applied says it was). Without it, small files are moved in the request. A move within a share is always made in the request.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveBody" } } } }, "responses": { "200": { "description": "The item, at its new canonical path.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "202": { "description": "A move to another share Foldr will make, or any move held for an approver (state pending_approval): the operation. Poll its Location after Retry-After seconds.", "headers": { "Location": { "description": "Where to poll the operation: GET it until it answers anything but 202.", "required": true, "schema": { "type": "string", "format": "uri" } }, "Preference-Applied": { "description": "respond-async: sent when the request's Prefer: respond-async is why this is an operation rather than an answer in the request (RFC 7240). Absent when Foldr chose the operation itself (a folder, a large file, Microsoft 365).", "required": false, "schema": { "type": "string", "enum": [ "respond-async" ] } }, "Retry-After": { "description": "Seconds to wait before polling again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request); Move into itself (move-into-itself).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request", "move-into-itself" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Change declined (change-declined); Download blocked (download-blocked); Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "change-declined", "download-blocked", "insufficient-scope", "legal-hold", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); Change not approved in time (change-expired); Conflict (conflict); Out for signature (envelope-source); Folder too large (folder-too-large); No approver (no-approver); Not a folder (not-a-folder); Operation cancelled (operation-cancelled); Published (published); Not connected when approved (requester-not-connected); Moved, but the original remains (source-remains); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "approved-version-unavailable", "change-expired", "conflict", "envelope-source", "folder-too-large", "no-approver", "not-a-folder", "operation-cancelled", "published", "requester-not-connected", "source-remains", "storage-account-not-connected" ] }, "412": { "description": "One of: Changed since requested (changed-since-requested); Precondition failed (precondition-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "changed-since-requested", "precondition-failed" ] }, "413": { "description": "One of: Copy too large (copy-too-large); Too large (too-large).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "copy-too-large", "too-large" ] }, "422": { "description": "Idempotency key reused (idempotency-key-reused).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "idempotency-key-reused" ] }, "423": { "description": "Checked out (checked-out).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "checked-out" ] }, "428": { "description": "Precondition required (precondition-required).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-required" ] }, "429": { "description": "One of: Daily limit of removals reached (destructive-budget); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "destructive-budget", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Copy interrupted (copy-interrupted); Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "copy-interrupted", "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 5 } }, "/shares/{share_id}/rename": { "post": { "operationId": "renameItem", "summary": "Rename a file or folder where it is", "description": "Send If-Match with the ETag you last read for it (GET .../item, a listing, or a write's answer): a rename without one is refused (428), and one whose item has changed since is refused (412), so nothing renamed is something you did not look at. An item under a legal hold (or a folder holding one) is refused 403 legal-hold, whatever the app is allowed. Answers the item at its NEW canonical path; the old path names nothing afterwards.", "tags": [ "Items" ], "security": [ { "foldr_oauth": [ "files.write" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "The item's ETag as you last read it (any form this API gave you for it; a list matches if any member does).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameBody" } } } }, "responses": { "200": { "description": "The item, at its new canonical path.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "legal-hold", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Conflict (conflict); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "conflict", "storage-account-not-connected" ] }, "412": { "description": "Precondition failed (precondition-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-failed" ] }, "423": { "description": "Checked out (checked-out).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "checked-out" ] }, "428": { "description": "Precondition required (precondition-required).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-required" ] }, "429": { "description": "One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "daily-write-limit", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 2 } }, "/shares/{share_id}/share-requests": { "post": { "operationId": "createShareRequest", "summary": "Ask to share a file or folder", "description": "The request waits for an approver and is answered 202 with status pending_approval; nothing is shared until an approver agrees, and the answer never carries a link. Refused (409 no-approver) when nobody but the person could approve it, and (409 already-shared) when the person already shares the item or has a request for it waiting: an app only starts sharing. Send an Idempotency-Key: the same request sent again with it answers the first answer and asks nothing more.", "tags": [ "ShareRequests" ], "security": [ { "foldr_oauth": [ "sharing" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A value of your own, 1 to 255 visible ASCII characters, new for each new request. The same key with the same request within 24 hours answers the first answer again and asks nothing more; with a different request it is refused (422).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareRequestBody" } } } }, "responses": { "202": { "description": "The request, waiting for an approver.", "headers": { "Location": { "description": "Where to read what was made.", "required": true, "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareRequest" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Already shared (already-shared); Ambiguous path (ambiguous-path); Conflict (conflict); No approver (no-approver); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "already-shared", "ambiguous-path", "conflict", "no-approver", "storage-account-not-connected" ] }, "422": { "description": "One of: Idempotency key reused (idempotency-key-reused); Validation failed (validation-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "idempotency-key-reused", "validation-failed" ] }, "429": { "description": "One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "daily-write-limit", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 2 } }, "/shares/{share_id}/versions": { "get": { "operationId": "listVersions", "summary": "The versions of a file its storage keeps, newest first: earlier saves (Foldr's own hosted storage, S3 and Azure that keep versions, SharePoint) or an SMB server's shadow copies (Previous Versions)", "description": "One page holds them all. Storage that keeps none answers an empty list. Someone who may only read the approved version of a published file is shown that version alone.", "tags": [ "Changes" ], "security": [ { "foldr_oauth": [ "foldr.read" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "description": "The path of the file.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of Versions.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionPage" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "Insufficient scope (insufficient-scope).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Not a file (not-a-file); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "not-a-file", "storage-account-not-connected" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 2 } }, "/shares/{share_id}/versions/restore": { "post": { "operationId": "restoreVersion", "summary": "Make an earlier version of a file its current contents again (one of listVersions' ids)", "description": "Send If-Match with the file's ETag as you last read it (428 without, 412 stale). Foldr's own hosted storage copies the version over the file within the storage; other storage that keeps versions (S3, Azure, SharePoint, an SMB server's shadow copies) is given that version's bytes, proven whole, so a restore that fails leaves the file as it was. Needs files.overwrite, allowed for your app on this share; refused as replacing a file is (checked out, legal hold, out for signature, published to this reader). Answers the file with its new ETag. With as_copy true the version is instead written beside the file as a new file (\"Report (3 Nov 2026 14.02).docx\", the first free name) and nothing is replaced: no If-Match is needed, it is answered 201 with the new file, and it is not counted against the allowance or held for approval. On an SMB share, restoring over a file that no shadow copy holds (it changed since the newest one) is refused 409 not-recoverable-here, because the overwrite would lose it: restore as a copy instead. Send an Idempotency-Key: the same request sent again with it answers the first answer. For an app whose administrator requires approval for its changes, it is not made at once: once every check has passed (and the items are counted against the allowance) it is answered 202 with an operation in state pending_approval, held for someone other than the person to approve in Foldr, then made as the person; poll it at its Location (getOperation). Refused 409 no-approver when nobody else could approve it.", "tags": [ "Changes" ], "security": [ { "foldr_oauth": [ "files.overwrite" ] } ], "parameters": [ { "name": "share_id", "in": "path", "description": "The share's id.", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "The file's ETag as you last read it. \"*\" is refused.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A value of your own, 1 to 255 visible ASCII characters, new for each new request. The same key with the same request within 24 hours answers the first answer again and restores nothing more; with a different request it is refused (422).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreVersionBody" } } } }, "responses": { "200": { "description": "The file, with its new ETag.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "201": { "description": "With as_copy: the new file, beside the original, with its ETag.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "Location": { "description": "Where to read what was made.", "required": true, "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "202": { "description": "Held for an approver (the app's administrator requires approval for its changes): the operation, state pending_approval. Poll its Location after Retry-After seconds.", "headers": { "Location": { "description": "Where to poll the operation: GET it until it answers anything but 202.", "required": true, "schema": { "type": "string", "format": "uri" } }, "Retry-After": { "description": "Seconds to wait before polling again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Change declined (change-declined); Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "change-declined", "insufficient-scope", "legal-hold", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Change not approved in time (change-expired); Out for signature (envelope-source); No approver (no-approver); Not a file (not-a-file); Not recoverable here (not-recoverable-here); Operation cancelled (operation-cancelled); Not connected when approved (requester-not-connected); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "change-expired", "envelope-source", "no-approver", "not-a-file", "not-recoverable-here", "operation-cancelled", "requester-not-connected", "storage-account-not-connected" ] }, "412": { "description": "One of: Changed since requested (changed-since-requested); Precondition failed (precondition-failed).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "changed-since-requested", "precondition-failed" ] }, "413": { "description": "Too large (too-large).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "too-large" ] }, "422": { "description": "Idempotency key reused (idempotency-key-reused).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "idempotency-key-reused" ] }, "423": { "description": "Checked out (checked-out).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "checked-out" ] }, "428": { "description": "Precondition required (precondition-required).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "precondition-required" ] }, "429": { "description": "One of: Daily limit of removals reached (destructive-budget); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "destructive-budget", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 5 } }, "/uploads": { "post": { "operationId": "createUploadSession", "summary": "Open an upload straight to the share's storage, for shares that offer it (Amazon S3 and compatible storage, Microsoft 365, Dropbox up to 150 MB)", "description": "Answers where and how to send the file; send it, then complete the session. Elsewhere 409 no-direct-upload: send the file through uploadFile instead. size is the file's exact size: completing checks it. New files only: something already called that is never replaced. A session is kept until about an hour after its expires_at: one neither completed nor cancelled by then is gone (404), and a file sent to the storage for it is removed, never announced.", "tags": [ "Uploads" ], "security": [ { "foldr_oauth": [ "files.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionBody" } } } }, "responses": { "201": { "description": "The session: where and how to send the file.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "400": { "description": "One of: Invalid path (invalid-path); Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-path", "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Ambiguous path (ambiguous-path); Conflict (conflict); No direct upload (no-direct-upload); Not a folder (not-a-folder); Storage account not connected (storage-account-not-connected).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "ambiguous-path", "conflict", "no-direct-upload", "not-a-folder", "storage-account-not-connected" ] }, "413": { "description": "Too large (too-large).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "too-large" ] }, "429": { "description": "One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "daily-write-limit", "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 2 } }, "/uploads/{id}/cancel": { "post": { "operationId": "cancelUploadSession", "summary": "Cancel an upload session that has not been completed", "description": "Removes the empty placeholder some storage keeps for the upload; never a file with bytes in it. A completed session cannot be cancelled (409).", "tags": [ "Uploads" ], "security": [ { "foldr_oauth": [ "files.write" ] } ], "parameters": [ { "name": "id", "in": "path", "description": "The session's id.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Cancelled.", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } } }, "400": { "description": "Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "Conflict (conflict).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "conflict" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] } }, "x-foldr-rate-cost": 2 } }, "/uploads/{id}/complete": { "post": { "operationId": "completeUploadSession", "summary": "Complete an upload session once the file is at the storage", "description": "The storage must hold exactly the declared size at the session's path, or 409 upload-incomplete (the session stays open: finish sending, then complete again). Answers the new file. Completing a completed session answers the same file again.", "tags": [ "Uploads" ], "security": [ { "foldr_oauth": [ "files.write" ] } ], "parameters": [ { "name": "id", "in": "path", "description": "The session's id.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The file, at its canonical path.", "headers": { "ETag": { "description": "The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.", "required": true, "schema": { "type": "string" } }, "Location": { "description": "Where to read what was made.", "required": true, "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "Invalid request (invalid-request).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-request" ] }, "401": { "description": "Invalid token (invalid-token).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": true, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "invalid-token" ] }, "403": { "description": "One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).", "headers": { "WWW-Authenticate": { "description": "The bearer challenge (RFC 6750): where to find the authorisation server, and the scope needed. Sent with invalid-token and insufficient-scope.", "required": false, "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "insufficient-scope", "write-not-allowed" ] }, "404": { "description": "Not found (not-found).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "not-found" ] }, "409": { "description": "One of: Conflict (conflict); Storage account not connected (storage-account-not-connected); Upload incomplete (upload-incomplete).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "conflict", "storage-account-not-connected", "upload-incomplete" ] }, "429": { "description": "Too many requests (rate-limited).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "rate-limited" ] }, "500": { "description": "Internal error (internal-error).", "headers": { "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "internal-error" ] }, "503": { "description": "One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Limit": { "description": "The size of the rate budget that will run out first for you: your app's budget for this person, or your app's budget across your organisation once that has less left. A 429 names the budget that refused.", "required": true, "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "What is left of it after this call. Each operation costs its x-foldr-rate-cost (a HEAD, or a 304, costs 1); the budget refills over time.", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "x-foldr-problem-types": [ "share-unavailable", "share-unreachable", "write-failed" ] } }, "x-foldr-rate-cost": 2 } } }, "components": { "schemas": { "Checkout": { "type": "object", "description": "Who has an item checked out (or open for editing), and since when.", "properties": { "by": { "description": "The person holding it.", "allOf": [ { "$ref": "#/components/schemas/Person" } ] }, "since": { "description": "When they took it (RFC 3339, UTC).", "type": "string", "format": "date-time" } }, "required": [ "by", "since" ] }, "CopyBody": { "type": "object", "description": "A file to copy, and where the copy goes.", "properties": { "path": { "description": "The path of the file to copy (files only).", "type": "string" }, "to_share": { "description": "The id of the share the copy goes in: this share or another of the person's.", "type": "string", "format": "uuid" }, "to_path": { "description": "The copy's full path in that share, its name last. The folder it goes in must exist.", "type": "string" }, "on_conflict": { "description": "What to do when something is already called that: \"fail\" (the default) answers 409 conflict; \"rename\" gives the copy the first free name (\"Q3 copy.xlsx\"). Nothing is ever replaced.", "type": "string", "enum": [ "fail", "rename" ] } }, "required": [ "path", "to_share", "to_path" ] }, "CreateFolderBody": { "type": "object", "description": "A folder to create.", "properties": { "path": { "description": "The new folder's full path in the share, its name last: \"/Reports/2027\". The folder it goes in must exist. The leading \"/\" is optional.", "type": "string" }, "on_conflict": { "description": "What to do when something is already called that: \"fail\" (the default) answers 409 conflict; \"rename\" creates it under the first free name in Foldr's style (\"2027 copy\"). Nothing is ever replaced.", "type": "string", "enum": [ "fail", "rename" ] } }, "required": [ "path" ] }, "Deletion": { "type": "object", "description": "What a delete did: the item as it was, and where its storage keeps it now, so your app can tell its user whether and how it can be brought back.", "properties": { "deleted": { "description": "The item that was deleted, as it was (its path names nothing now).", "allOf": [ { "$ref": "#/components/schemas/Item" } ] }, "items": { "description": "How many files and folders went: 1 for a file; a folder and everything in it.", "type": "integer" }, "recoverable": { "description": "\"bin\": the storage keeps it in a recycle bin, a trash or its earlier versions, so it can be brought back there; \"snapshot\": only the server's shadow copies hold it, as of the last one; \"none\": as far as Foldr can tell it is gone for good.", "type": "string", "enum": [ "bin", "snapshot", "none" ] }, "destination": { "description": "Where it is, as a stable name: microsoft-365-recycle-bin, google-drive-trash, box-trash, dropbox-deleted-files, foldr-deleted-files, bucket-versions, azure-soft-delete, shadow-copies, shadow-copies-if-enabled, or unknown (Foldr cannot tell whether this storage keeps deleted items). Null where it is certainly gone.", "type": [ "string", "null" ] }, "where": { "description": "The same, in words for a person (\"the Microsoft 365 recycle bin\"). Bins belong to the share's storage account, not the person: getting something back is usually for whoever manages it.", "type": [ "string", "null" ] } }, "required": [ "deleted", "items", "recoverable", "destination", "where" ] }, "DownloadUrl": { "type": "object", "description": "A short-lived URL that downloads a file straight from its storage, for clients that cannot follow a redirect to another host.", "properties": { "url": { "description": "The URL. It carries its own authorisation: send it no Foldr token, and do not log or share it.", "type": "string", "format": "uri" }, "expires_at": { "description": "The URL works until at least this time (RFC 3339, UTC); some storage keeps it working longer.", "type": "string", "format": "date-time" } }, "required": [ "url", "expires_at" ] }, "Export": { "type": "object", "description": "What a native Google document (Docs, Sheets, Slides, Drawings) is downloaded as. It has no bytes of its own: content exports it, as this type, named with this extension.", "properties": { "mime_type": { "description": "The media type content delivers (for a Google Doc, application/vnd.openxmlformats-officedocument.wordprocessingml.document).", "type": "string" }, "extension": { "description": "The extension the download is named with, without the dot (docx for a Google Doc). The item's name and path stay as stored.", "type": "string" } }, "required": [ "mime_type", "extension" ] }, "Field": { "type": "object", "description": "A custom field: a named piece of information people record on files.", "properties": { "id": { "description": "The field's id. Always a uuid.", "type": "string", "format": "uuid" }, "name": { "description": "The field's name.", "type": "string" }, "type": { "description": "What kind of value it holds. New values may appear. Known values: string, text, number, bool, date, location, select, signature, delegate. Clients must accept values not listed here.", "type": "string", "x-extensible-enum": [ "string", "text", "number", "bool", "date", "location", "select", "signature", "delegate" ] }, "options": { "description": "The values it may take, where it has a fixed list (on at least one of the person's shares); otherwise null.", "type": [ "array", "null" ], "items": { "type": "string" } }, "multiple": { "description": "Whether a file can carry more than one value of it.", "type": "boolean" }, "read_only": { "description": "True when the person may not set it on any of their shares.", "type": "boolean" } }, "required": [ "id", "name", "type", "options", "multiple", "read_only" ] }, "FieldValue": { "type": "object", "description": "One value of a custom field on one item. A field that holds several values appears once per value.", "properties": { "field_id": { "description": "The field's id (see GET /fields).", "type": "string", "format": "uuid" }, "value": { "description": "The value: a string, number or boolean by the field's type; a location is an object." }, "updated_at": { "description": "When it was last set (RFC 3339, UTC).", "type": [ "string", "null" ], "format": "date-time" }, "updated_by": { "description": "Who last set it, where known.", "anyOf": [ { "$ref": "#/components/schemas/Person" }, { "type": "null" } ] } }, "required": [ "field_id", "value", "updated_at", "updated_by" ] }, "Item": { "type": "object", "description": "A file or folder in a share. Identified by its share id and canonical path; there is no separate item id.", "properties": { "share_id": { "description": "The id of the share the item is in.", "type": "string", "format": "uuid" }, "path": { "description": "The canonical path: as the storage holds it (its case), Unicode NFC, always starting with \"/\". \"/\" is the top of the share. Send this form back in later calls.", "type": "string" }, "name": { "description": "The item's name (the last segment of its path; the share's name for the top).", "type": "string" }, "kind": { "description": "file or folder.", "type": "string", "enum": [ "file", "folder" ] }, "size": { "description": "Size in bytes; null for a folder, and null when the item has no fixed byte size (a native Google document, exported on download: see export).", "type": [ "integer", "null" ] }, "modified": { "description": "Last modified (RFC 3339, UTC), where the storage reports it.", "type": [ "string", "null" ], "format": "date-time" }, "mime_type": { "description": "The item's own media type, as the storage reports it or guessed from the name; null for a folder. A native Google document has Google's own type here (application/vnd.google-apps.document for a Doc); export says what it downloads as.", "type": [ "string", "null" ] }, "export": { "description": "For a native Google document that can be downloaded, what content delivers: its media type and the extension the download is named with. Null for everything else, including a native Google type that cannot be downloaded (a Form: content answers 409 not-downloadable).", "anyOf": [ { "$ref": "#/components/schemas/Export" }, { "type": "null" } ] }, "etag": { "description": "The item's entity tag: the storage's own where it has one, else a weak tag over size and modified time (over modified time alone for a native Google document, whose export is made afresh each time). Null on a search hit, which comes from the index; GET .../item for the live one.", "type": [ "string", "null" ] }, "read_only": { "description": "True when the person cannot change things in this share.", "type": "boolean" }, "checked_out": { "description": "Who has the item checked out, or null. Null on a search hit.", "anyOf": [ { "$ref": "#/components/schemas/Checkout" }, { "type": "null" } ] } }, "required": [ "share_id", "path", "name", "kind", "size", "modified", "mime_type", "export", "etag", "read_only", "checked_out" ] }, "ItemPage": { "type": "object", "description": "One page of a collection. Pass next_cursor back as ?cursor= for the next page; null on the last. Cursors are opaque: never build or change one.", "properties": { "items": { "type": "array", "description": "This page's entries.", "items": { "$ref": "#/components/schemas/Item" } }, "next_cursor": { "type": [ "string", "null" ], "description": "The cursor for the next page, or null when this is the last." }, "truncated": { "type": "boolean", "description": "True when the collection holds more than one listing can read (a folder of more than 25,000 entries): the pages give the first 25,000 the storage lists, and every page of it says true, so a null next_cursor is not the whole folder. False otherwise." } }, "required": [ "items", "next_cursor", "truncated" ] }, "Me": { "type": "object", "description": "The person the token acts as. The same body as GET /api/me.", "properties": { "name": { "description": "Display name, or the username where there is none.", "type": "string" }, "email": { "description": "Email address, where the directory has one.", "type": [ "string", "null" ] }, "username": { "description": "Sign-in name.", "type": "string" } }, "required": [ "name", "email", "username" ] }, "MoveBody": { "type": "object", "description": "A file or folder to move, and where it goes: in the same share, or in another of the person's shares (to_share).", "properties": { "path": { "description": "The path of the file or folder to move.", "type": "string" }, "to_path": { "description": "Its full new path, its name last (the same name, or a new one), in the same share or in to_share. The folder it goes in must exist.", "type": "string" }, "to_share": { "description": "The id of the share it goes to, when that is another share; absent (or this share's id) moves it within this share.", "type": [ "string", "null" ], "format": "uuid" }, "on_conflict": { "description": "What to do when something is already called that: \"fail\" (the default) answers 409 conflict; \"rename\" gives it the first free name (\"Q3 copy.xlsx\"). Nothing is ever replaced.", "type": "string", "enum": [ "fail", "rename" ] } }, "required": [ "path", "to_path" ] }, "NotSearched": { "type": "object", "description": "One of the person's shares that a search did not cover, and why.", "properties": { "share_id": { "description": "The share's id.", "type": "string", "format": "uuid" }, "name": { "description": "The share's name.", "type": "string" }, "reason": { "description": "unreachable: its file server is down just now; not-indexed: the share is not indexed for search; index-unavailable: its search index did not answer. New values may appear. Known values: unreachable, not-indexed, index-unavailable. Clients must accept values not listed here.", "type": "string", "x-extensible-enum": [ "unreachable", "not-indexed", "index-unavailable" ] } }, "required": [ "share_id", "name", "reason" ] }, "Operation": { "type": "object", "description": "Work Foldr carries on after answering: a copy (copyItem) or a move to another share (moveItem) of a folder, or of a file too big or too slow for one request; and, for an app whose administrator requires approval for its changes, a delete, move or version restore held for an approver (state pending_approval), made once someone approves it. Poll it at its Location (getOperation) until the answer is no longer 202. Kept for 7 days after it finishes.", "properties": { "id": { "description": "The operation's id.", "type": "string", "format": "uuid" }, "kind": { "description": "What it does: copy, move (to another share, or held for approval within one), delete or restore (a version restore). delete and restore are only ever operations held for approval. Known values: copy, move, delete, restore. Clients must accept values not listed here.", "type": "string", "x-extensible-enum": [ "copy", "move", "delete", "restore" ] }, "state": { "description": "Where it has got to. pending_approval: held for an approver, nothing changed yet (approval says until when); queued: waiting to start; running: under way; cancelling: asked to stop, stopping at its next item; succeeded: done, result is what was made; failed: ended with the problem getOperation answers; cancelled: stopped, and what it had made removed (or, held for approval, withdrawn, nothing changed); declined: an approver said no, nothing changed; expired: nobody approved it in time, nothing changed.", "type": "string", "enum": [ "pending_approval", "queued", "running", "cancelling", "succeeded", "failed", "cancelled", "declined", "expired" ] }, "phase": { "description": "A move's phase: copying (every item is copied first; nothing has been removed from where it was, and a cancel removes the partial copy), then deleting (the copy is whole and proven, and the originals are being removed: too late to cancel). Null for a copy. Known values: copying, deleting. Clients must accept values not listed here.", "type": [ "string", "null" ], "x-extensible-enum": [ "copying", "deleting" ] }, "created_at": { "description": "When it was asked for (RFC 3339, UTC).", "type": "string", "format": "date-time" }, "started_at": { "description": "When a worker first started it; null while queued.", "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "description": "When it finished; null until then.", "type": [ "string", "null" ], "format": "date-time" }, "source": { "description": "What is being copied, moved, deleted or restored.", "allOf": [ { "$ref": "#/components/schemas/OperationSource" } ] }, "target": { "description": "Where it was asked to go: the path asked for. result.path is where it landed (on_conflict \"rename\" may have given it another name). Null for a delete or a restore.", "anyOf": [ { "$ref": "#/components/schemas/OperationTarget" }, { "type": "null" } ] }, "version_id": { "description": "For a restore: the version asked for (one of listVersions' ids). Null otherwise.", "type": [ "string", "null" ] }, "progress": { "description": "How far it has got.", "allOf": [ { "$ref": "#/components/schemas/OperationProgress" } ] }, "result": { "description": "Once it has succeeded, what it made (the copy, the moved item at its new place, the restored file), at its canonical path; null until then, and for a delete (see deletion). A move that ended source-remains also has it: the whole copy it made.", "anyOf": [ { "$ref": "#/components/schemas/Item" }, { "type": "null" } ] }, "deletion": { "description": "A delete held for approval, once it has succeeded: what was deleted and where its storage keeps it now, as deleteItem answers. Null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/Deletion" }, { "type": "null" } ] }, "approval": { "description": "For an operation held for an approver: how its approval stands. Null for one that never waited for approval.", "anyOf": [ { "$ref": "#/components/schemas/OperationApproval" }, { "type": "null" } ] }, "failures": { "description": "At most 100 items (failures_truncated says when there were more): for a copy that ended copy-incomplete, those it could not copy; for a move that ended source-remains, those still at the source. Empty otherwise.", "type": "array", "items": { "$ref": "#/components/schemas/OperationFailure" } }, "failures_truncated": { "description": "True when more items failed than failures lists.", "type": "boolean" } }, "required": [ "id", "kind", "state", "phase", "created_at", "started_at", "finished_at", "source", "target", "version_id", "progress", "result", "deletion", "approval", "failures", "failures_truncated" ] }, "OperationApproval": { "type": "object", "description": "An operation held for an approver: the app's administrator requires approval for its deletes, moves and version restores. Who approves, and where, is the organisation's own business: nothing here names them.", "properties": { "status": { "description": "pending: waiting for an approver; approved: someone approved it (the operation then made the change, or says why it could not); declined: an approver said no; expired: nobody decided it in time; withdrawn: the person (or your app, by cancelling the operation) took it back; closed: it could no longer be decided as asked. Known values: pending, approved, declined, expired, withdrawn, closed. Clients must accept values not listed here.", "type": "string", "x-extensible-enum": [ "pending", "approved", "declined", "expired", "withdrawn", "closed" ] }, "expires_at": { "description": "When it lapses if nobody decides it (RFC 3339, UTC).", "type": [ "string", "null" ], "format": "date-time" }, "decided_at": { "description": "When it was decided; null while it waits.", "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "status", "expires_at", "decided_at" ] }, "OperationFailure": { "type": "object", "description": "One item an operation could not copy, or (a move that ended source-remains) one whose original is still at the source.", "properties": { "path": { "description": "The item's canonical path in the source share.", "type": "string" }, "code": { "description": "Why, as a problem slug (the last segment of a problem type: download-blocked, invalid-path, not-found, ...).", "type": "string" } }, "required": [ "path", "code" ] }, "OperationPage": { "type": "object", "description": "One page of a collection. Pass next_cursor back as ?cursor= for the next page; null on the last. Cursors are opaque: never build or change one.", "properties": { "items": { "type": "array", "description": "This page's entries.", "items": { "$ref": "#/components/schemas/Operation" } }, "next_cursor": { "type": [ "string", "null" ], "description": "The cursor for the next page, or null when this is the last." }, "truncated": { "type": "boolean", "description": "True when the collection holds more than one listing can read (a folder of more than 25,000 entries): the pages give the first 25,000 the storage lists, and every page of it says true, so a null next_cursor is not the whole folder. False otherwise." } }, "required": [ "items", "next_cursor", "truncated" ] }, "OperationProgress": { "type": "object", "description": "How far an operation has got. The totals are null until Foldr has counted what there is to do: nothing is guessed.", "properties": { "items_done": { "description": "Files and folders copied so far (the copied folder itself included).", "type": "integer" }, "items_total": { "description": "Files and folders to do in all, or null until counted.", "type": [ "integer", "null" ] }, "bytes_done": { "description": "Bytes of files done so far.", "type": "integer" }, "bytes_total": { "description": "Bytes of files to do in all, or null until counted.", "type": [ "integer", "null" ] } }, "required": [ "items_done", "items_total", "bytes_done", "bytes_total" ] }, "OperationSource": { "type": "object", "description": "What an operation copies, or moves.", "properties": { "share_id": { "description": "The id of the share it is in.", "type": "string", "format": "uuid" }, "path": { "description": "Its canonical path.", "type": "string" }, "kind": { "description": "file or folder.", "type": "string", "enum": [ "file", "folder" ] } }, "required": [ "share_id", "path", "kind" ] }, "OperationTarget": { "type": "object", "description": "Where an operation was asked to put what it makes.", "properties": { "share_id": { "description": "The id of the share.", "type": "string", "format": "uuid" }, "path": { "description": "The path asked for, as sent (to_path).", "type": "string" } }, "required": [ "share_id", "path" ] }, "Person": { "type": "object", "description": "A person, as far as a file record names them.", "properties": { "id": { "description": "The person's id (their directory guid).", "type": "string" }, "name": { "description": "Display name.", "type": "string" } }, "required": [ "id", "name" ] }, "ProblemDetails": { "type": "object", "description": "An error, as application/problem+json (RFC 9457). Branch on type (or code), never on title or detail.", "properties": { "type": { "description": "What went wrong, as a URL: https:///api/v1/problems/. New types may appear.", "type": "string", "format": "uri" }, "title": { "description": "A short human summary of the type.", "type": "string" }, "status": { "description": "The HTTP status.", "type": "integer" }, "code": { "description": "The same condition as an upper-case code, as Foldr's other APIs name errors.", "type": "string" }, "detail": { "description": "More about this occurrence, where there is anything safe to say.", "type": [ "string", "null" ] }, "instance": { "description": "A fault code for this occurrence (\"#\" and 8 hex digits) to quote to support, where there is one.", "type": [ "string", "null" ] }, "operation": { "description": "Where the problem is how an operation ended (getOperation on a failed or cancelled one): that operation, as it stands.", "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] } }, "required": [ "type", "title", "status", "code" ] }, "RenameBody": { "type": "object", "description": "A file or folder to rename where it is.", "properties": { "path": { "description": "The path of the file or folder to rename.", "type": "string" }, "new_name": { "description": "Its new name: one name, no \"/\", no spaces at either end. Something already called that is never replaced (409 conflict).", "type": "string" } }, "required": [ "path", "new_name" ] }, "RestoreVersionBody": { "type": "object", "description": "A file, and which of its versions to make current again.", "properties": { "path": { "description": "The path of the file.", "type": "string" }, "version_id": { "description": "The version to restore: an id listVersions gave for this file.", "type": "string" }, "as_copy": { "description": "true to write the version BESIDE the file as a new file named \"name (3 Nov 2026 14.02).ext\" (the first free name) and change nothing else. Needs no If-Match, is never refused for the file's state (checked out, legal hold) and is not held for approval, because it replaces nothing. Default false: the version replaces the file.", "type": "boolean" } }, "required": [ "path", "version_id" ] }, "SearchHit": { "type": "object", "description": "One search result.", "properties": { "item": { "description": "The item found, as the search index knows it.", "allOf": [ { "$ref": "#/components/schemas/Item" } ] }, "score": { "description": "Relevance: higher is better, comparable only within one response's ordering.", "type": [ "number", "null" ] }, "snippet": { "description": "A short passage of text around the match, where there is one and it may be shown.", "type": [ "string", "null" ] } }, "required": [ "item", "score", "snippet" ] }, "SearchResults": { "type": "object", "description": "One page of search results. Ordered by relevance within each search index; where the person's shares sit in more than one index, the pages walk the indexes one after another. Pass next_cursor back as ?cursor= (with the same q and share_id) for the next page.", "properties": { "items": { "description": "This page's hits.", "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } }, "next_cursor": { "description": "The cursor for the next page, or null when this is the last. A page can hold fewer hits than the limit and still not be the last.", "type": [ "string", "null" ] }, "total_estimate": { "description": "About how many items match, over every index searched. An estimate: it is not a count of the pages to come.", "type": "integer" }, "not_searched": { "description": "The person's shares this search did not cover, and why.", "type": "array", "items": { "$ref": "#/components/schemas/NotSearched" } } }, "required": [ "items", "next_cursor", "total_estimate", "not_searched" ] }, "SetFieldValueBody": { "type": "object", "description": "A custom field value to set on one file.", "properties": { "path": { "description": "The path of the file (files only).", "type": "string" }, "value": { "description": "The value: a string, a number, or true or false, as the field's type takes (a date as 2027-01-31). A field with a list of allowed values takes one of them." } }, "required": [ "path", "value" ] }, "Share": { "type": "object", "description": "A share: a storage location the person can read. Files and folders are addressed by a share id plus a path inside it.", "properties": { "id": { "description": "The share's id. Always a uuid.", "type": "string", "format": "uuid" }, "name": { "description": "The share's name, as people see it in Foldr.", "type": "string" }, "type": { "description": "The kind of storage behind the share. New values may appear: treat an unknown one as \"other\". Known values: smb, local, hosted, s3, b2, azure_blob, sftp, ftp, webdav, edge, google_drive, google_shared_drive, group_drive, onedrive, sharepoint, teams, dropbox, box, other. Clients must accept values not listed here.", "type": "string", "x-extensible-enum": [ "smb", "local", "hosted", "s3", "b2", "azure_blob", "sftp", "ftp", "webdav", "edge", "google_drive", "google_shared_drive", "group_drive", "onedrive", "sharepoint", "teams", "dropbox", "box", "other" ] }, "indexed": { "description": "Whether the share is indexed for GET /search.", "type": "boolean" }, "read_only": { "description": "True when the person cannot change anything in the share.", "type": "boolean" }, "reachable": { "description": "False when the share's file server could not be reached just now. It still exists and is the person's: try again in a few minutes.", "type": "boolean" } }, "required": [ "id", "name", "type", "indexed", "read_only", "reachable" ] }, "SharePage": { "type": "object", "description": "One page of a collection. Pass next_cursor back as ?cursor= for the next page; null on the last. Cursors are opaque: never build or change one.", "properties": { "items": { "type": "array", "description": "This page's entries.", "items": { "$ref": "#/components/schemas/Share" } }, "next_cursor": { "type": [ "string", "null" ], "description": "The cursor for the next page, or null when this is the last." }, "truncated": { "type": "boolean", "description": "True when the collection holds more than one listing can read (a folder of more than 25,000 entries): the pages give the first 25,000 the storage lists, and every page of it says true, so a null next_cursor is not the whole folder. False otherwise." } }, "required": [ "items", "next_cursor", "truncated" ] }, "ShareRequest": { "type": "object", "description": "A request to share a file or folder, made through an app. It waits for an approver; once approved, the sharing works in Foldr, where the person finds the link. Never carries a link or its address.", "properties": { "id": { "description": "The request's id.", "type": "string", "format": "uuid" }, "share_id": { "description": "The id of the share the item is in.", "type": "string", "format": "uuid" }, "path": { "description": "The item's canonical path.", "type": "string" }, "kind": { "description": "What was asked for. Known values: people, public_link, secure_link, inbox. Clients must accept values not listed here.", "type": "string", "x-extensible-enum": [ "people", "public_link", "secure_link", "inbox" ] }, "status": { "description": "Where it stands: pending_approval until an approver decides; approved; declined (by an approver, or left undecided until it lapsed); withdrawn. Known values: pending_approval, approved, declined, withdrawn. Clients must accept values not listed here.", "type": "string", "x-extensible-enum": [ "pending_approval", "approved", "declined", "withdrawn" ] }, "created_at": { "description": "When it was asked for (RFC 3339, UTC).", "type": [ "string", "null" ], "format": "date-time" }, "decided_at": { "description": "When it was decided, or null while it waits.", "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "share_id", "path", "kind", "status", "created_at", "decided_at" ] }, "ShareRequestBody": { "type": "object", "description": "What to share and how. A request always waits for an approver; nothing is shared until one approves it.", "properties": { "path": { "description": "The path of the file or folder to share (an inbox needs a folder).", "type": "string" }, "kind": { "description": "people: people in the organisation; public_link: a link anyone with it can open; secure_link: a link for the outside email addresses named; inbox: an email address that files sent to it arrive in (a folder).", "type": "string", "enum": [ "people", "public_link", "secure_link", "inbox" ] }, "people": { "description": "For people: their email addresses, usernames or exact group names (at most 20).", "type": [ "array", "null" ], "items": { "type": "string" } }, "permission": { "description": "For people: \"read\" (the default) or \"write\".", "type": [ "string", "null" ], "enum": [ "read", "write", null ] }, "recipient_emails": { "description": "For secure_link: the outside email addresses it is for (at most 20).", "type": [ "array", "null" ], "items": { "type": "string" } }, "expiry_days": { "description": "Days until access ends once approved; 0 or absent for never. For a link, -1 ends it after its first download.", "type": [ "integer", "null" ] }, "message": { "description": "A note shown with the link (at most 1,000 characters).", "type": [ "string", "null" ] } }, "required": [ "path", "kind" ] }, "ShareRequestPage": { "type": "object", "description": "One page of a collection. Pass next_cursor back as ?cursor= for the next page; null on the last. Cursors are opaque: never build or change one.", "properties": { "items": { "type": "array", "description": "This page's entries.", "items": { "$ref": "#/components/schemas/ShareRequest" } }, "next_cursor": { "type": [ "string", "null" ], "description": "The cursor for the next page, or null when this is the last." }, "truncated": { "type": "boolean", "description": "True when the collection holds more than one listing can read (a folder of more than 25,000 entries): the pages give the first 25,000 the storage lists, and every page of it says true, so a null next_cursor is not the whole folder. False otherwise." } }, "required": [ "items", "next_cursor", "truncated" ] }, "UploadSession": { "type": "object", "description": "An upload straight to the share's storage. Send the file to url with method and headers (in chunk_size pieces with Content-Range where chunk_size is set), then complete the session; or cancel it. The url is a credential for this one upload: do not log or share it.", "properties": { "id": { "description": "The session's id, for complete and cancel.", "type": "string" }, "mode": { "description": "How the file is sent: direct, straight to the storage. Known values: direct. Clients must accept values not listed here.", "type": "string", "x-extensible-enum": [ "direct" ] }, "share_id": { "description": "The id of the share.", "type": "string", "format": "uuid" }, "path": { "description": "The canonical path the file will have (on_conflict \"rename\" may have given it a new name).", "type": "string" }, "size": { "description": "The size declared, in bytes.", "type": "integer" }, "url": { "description": "Where to send the file.", "type": "string", "format": "uri" }, "method": { "description": "The HTTP method to send it with (PUT or POST).", "type": "string" }, "headers": { "description": "Headers to send with it, exactly as given.", "type": "object", "additionalProperties": { "type": "string" } }, "chunk_size": { "description": "Where set, send the file in pieces of at most this many bytes (a multiple of it, except the last), each with a Content-Range header; null: send it whole in one request.", "type": [ "integer", "null" ] }, "expires_at": { "description": "Send the file before this time (RFC 3339, UTC); then the url stops working. Complete the session afterwards.", "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "mode", "share_id", "path", "size", "url", "method", "headers", "chunk_size", "expires_at" ] }, "UploadSessionBody": { "type": "object", "description": "A file to upload straight to the share's storage.", "properties": { "share_id": { "description": "The id of the share.", "type": "string", "format": "uuid" }, "path": { "description": "The new file's full path in the share, its name last. The folder it goes in must exist.", "type": "string" }, "size": { "description": "The file's exact size in bytes. Completing the session checks the storage holds exactly this many.", "type": "integer" }, "on_conflict": { "description": "What to do when something is already called that: \"fail\" (the default) answers 409 conflict; \"rename\" uploads it under the first free name. Nothing is ever replaced.", "type": "string", "enum": [ "fail", "rename" ] }, "content_type": { "description": "The file's media type, where the storage records one (default application/octet-stream).", "type": [ "string", "null" ] } }, "required": [ "share_id", "path", "size" ] }, "Version": { "type": "object", "description": "One version of a file that its storage keeps: an earlier save (S3 and hosted storage, Azure, SharePoint) or a shadow copy (an SMB server's Previous Versions).", "properties": { "id": { "description": "The version's id, as the storage names it: what restoreVersion takes. Opaque; never build one.", "type": "string" }, "modified": { "description": "When this version was saved (RFC 3339, UTC), where the storage says.", "type": [ "string", "null" ], "format": "date-time" }, "size": { "description": "Its size in bytes, where the storage says.", "type": [ "integer", "null" ] }, "current": { "description": "True for the version the file is now.", "type": "boolean" } }, "required": [ "id", "modified", "size", "current" ] }, "VersionPage": { "type": "object", "description": "One page of a collection. Pass next_cursor back as ?cursor= for the next page; null on the last. Cursors are opaque: never build or change one.", "properties": { "items": { "type": "array", "description": "This page's entries.", "items": { "$ref": "#/components/schemas/Version" } }, "next_cursor": { "type": [ "string", "null" ], "description": "The cursor for the next page, or null when this is the last." }, "truncated": { "type": "boolean", "description": "True when the collection holds more than one listing can read (a folder of more than 25,000 entries): the pages give the first 25,000 the storage lists, and every page of it says true, so a null next_cursor is not the whole folder. False otherwise." } }, "required": [ "items", "next_cursor", "truncated" ] } }, "securitySchemes": { "foldr_oauth": { "type": "oauth2", "description": "OAuth 2.1 authorisation code flow, with PKCE (S256) required of every client. The person signs in to Foldr and agrees to what the app may do; the app then calls the API as that person, seeing only what they may see. Ask for offline_access to receive a refresh token. The authorisation server describes itself at /.well-known/oauth-authorization-server.", "flows": { "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/oauth/token", "refreshUrl": "/oauth/token", "scopes": { "foldr.read": "Read files and search, as you", "offline_access": "Stay connected without signing in again", "profile": "See your name and email", "files.write": "Create and change files in the shares an administrator allows", "fields.write": "Change file information (custom fields)", "sharing": "Ask to share files on your behalf (an approver decides)", "files.overwrite": "Replace the contents of files, and put back earlier versions, in the shares an administrator allows. Where the storage keeps no earlier versions, the old contents cannot be got back", "files.move": "Move files and folders to other folders, in the shares an administrator allows", "files.delete": "Delete files and folders, in the shares an administrator allows. Where the storage has no recycle bin, a deletion cannot be undone" } } } } } } }