Schemas

The objects the API sends and takes, as the OpenAPI document defines them.

Checkout

Who has an item checked out (or open for editing), and since when.

Field	Type	Description
by	Person	Required. The person holding it.
since	string (date-time)	Required. When they took it (RFC 3339, UTC).

CopyBody

A file to copy, and where the copy goes.

Field	Type	Description
path	string	Required. The path of the file to copy (files only).
to_share	string (uuid)	Required. The id of the share the copy goes in: this share or another of the person’s.
to_path	string	Required. The copy’s full path in that share, its name last. The folder it goes in must exist.
on_conflict	string, one of fail, rename	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.

Used by: copyItem.

CreateFolderBody

A folder to create.

Field	Type	Description
path	string	Required. 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.
on_conflict	string, one of fail, rename	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.

Used by: createFolder.

Deletion

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.

Field	Type	Description
deleted	Item	Required. The item that was deleted, as it was (its path names nothing now).
items	integer	Required. How many files and folders went: 1 for a file; a folder and everything in it.
recoverable	string, one of bin, snapshot, none	Required. “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.
destination	string or null	Required. 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.
where	string or null	Required. 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.

Used by: deleteItem.

DownloadUrl

A short-lived URL that downloads a file straight from its storage, for clients that cannot follow a redirect to another host.

Field	Type	Description
url	string (uri)	Required. The URL. It carries its own authorisation: send it no Foldr token, and do not log or share it.
expires_at	string (date-time)	Required. The URL works until at least this time (RFC 3339, UTC); some storage keeps it working longer.

Used by: getDownloadUrl.

Export

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.

Field	Type	Description
mime_type	string	Required. The media type content delivers (for a Google Doc, application/vnd.openxmlformats-officedocument.wordprocessingml.document).
extension	string	Required. The extension the download is named with, without the dot (docx for a Google Doc). The item’s name and path stay as stored.

Field

A custom field: a named piece of information people record on files.

Field	Type	Description
id	string (uuid)	Required. The field’s id. Always a uuid.
name	string	Required. The field’s name.
type	string	Required. 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.
options	array or null	Required. The values it may take, where it has a fixed list (on at least one of the person’s shares); otherwise null.
multiple	boolean	Required. Whether a file can carry more than one value of it.
read_only	boolean	Required. True when the person may not set it on any of their shares.

Used by: listFields.

FieldValue

One value of a custom field on one item. A field that holds several values appears once per value.

Field	Type	Description
field_id	string (uuid)	Required. The field’s id (see GET /fields).
value	any	Required. The value: a string, number or boolean by the field’s type; a location is an object.
updated_at	string or null (date-time)	Required. When it was last set (RFC 3339, UTC).
updated_by	Person or null	Required. Who last set it, where known.

Used by: getFieldValues, setFieldValue.

Item

A file or folder in a share. Identified by its share id and canonical path; there is no separate item id.

Field	Type	Description
share_id	string (uuid)	Required. The id of the share the item is in.
path	string	Required. 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.
name	string	Required. The item’s name (the last segment of its path; the share’s name for the top).
kind	string, one of file, folder	Required. file or folder.
size	integer or null	Required. 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).
modified	string or null (date-time)	Required. Last modified (RFC 3339, UTC), where the storage reports it.
mime_type	string or null	Required. 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.
export	Export or null	Required. 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).
etag	string or null	Required. 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.
read_only	boolean	Required. True when the person cannot change things in this share.
checked_out	Checkout or null	Required. Who has the item checked out, or null. Null on a search hit.

Used by: overwriteFile, copyItem, uploadFile, createFolder, getItem, moveItem, renameItem, restoreVersion, completeUploadSession.

ItemPage

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.

Field	Type	Description
items	array of Item	Required. This page’s entries.
next_cursor	string or null	Required. The cursor for the next page, or null when this is the last.
truncated	boolean	Required. 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.

Used by: listChildren.

Me

The person the token acts as. The same body as GET /api/me.

Field	Type	Description
name	string	Required. Display name, or the username where there is none.
email	string or null	Required. Email address, where the directory has one.
username	string	Required. Sign-in name.

Used by: getMe.

MoveBody

A file or folder to move, and where it goes: in the same share, or in another of the person’s shares (to_share).

Field	Type	Description
path	string	Required. The path of the file or folder to move.
to_path	string	Required. 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.
to_share	string or null (uuid)	The id of the share it goes to, when that is another share; absent (or this share’s id) moves it within this share.
on_conflict	string, one of fail, rename	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.

Used by: moveItem.

NotSearched

One of the person’s shares that a search did not cover, and why.

Field	Type	Description
share_id	string (uuid)	Required. The share’s id.
name	string	Required. The share’s name.
reason	string	Required. 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.

Operation

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.

Field	Type	Description
id	string (uuid)	Required. The operation’s id.
kind	string	Required. 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.
state	string, one of pending_approval, queued, running, cancelling, succeeded, failed, cancelled, declined, expired	Required. 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.
phase	string or null	Required. 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.
created_at	string (date-time)	Required. When it was asked for (RFC 3339, UTC).
started_at	string or null (date-time)	Required. When a worker first started it; null while queued.
finished_at	string or null (date-time)	Required. When it finished; null until then.
source	OperationSource	Required. What is being copied, moved, deleted or restored.
target	OperationTarget or null	Required. 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.
version_id	string or null	Required. For a restore: the version asked for (one of listVersions’ ids). Null otherwise.
progress	OperationProgress	Required. How far it has got.
result	Item or null	Required. 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.
deletion	Deletion or null	Required. A delete held for approval, once it has succeeded: what was deleted and where its storage keeps it now, as deleteItem answers. Null otherwise.
approval	OperationApproval or null	Required. For an operation held for an approver: how its approval stands. Null for one that never waited for approval.
failures	array of OperationFailure	Required. 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.
failures_truncated	boolean	Required. True when more items failed than failures lists.

Used by: getOperation, copyItem, deleteItem, moveItem, restoreVersion.

OperationApproval

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.

Field	Type	Description
status	string	Required. 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.
expires_at	string or null (date-time)	Required. When it lapses if nobody decides it (RFC 3339, UTC).
decided_at	string or null (date-time)	Required. When it was decided; null while it waits.

OperationFailure

One item an operation could not copy, or (a move that ended source-remains) one whose original is still at the source.

Field	Type	Description
path	string	Required. The item’s canonical path in the source share.
code	string	Required. Why, as a problem slug (the last segment of a problem type: download-blocked, invalid-path, not-found, …).

OperationPage

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.

Field	Type	Description
items	array of Operation	Required. This page’s entries.
next_cursor	string or null	Required. The cursor for the next page, or null when this is the last.
truncated	boolean	Required. 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.

Used by: listOperations.

OperationProgress

How far an operation has got. The totals are null until Foldr has counted what there is to do: nothing is guessed.

Field	Type	Description
items_done	integer	Required. Files and folders copied so far (the copied folder itself included).
items_total	integer or null	Required. Files and folders to do in all, or null until counted.
bytes_done	integer	Required. Bytes of files done so far.
bytes_total	integer or null	Required. Bytes of files to do in all, or null until counted.

OperationSource

What an operation copies, or moves.

Field	Type	Description
share_id	string (uuid)	Required. The id of the share it is in.
path	string	Required. Its canonical path.
kind	string, one of file, folder	Required. file or folder.

OperationTarget

Where an operation was asked to put what it makes.

Field	Type	Description
share_id	string (uuid)	Required. The id of the share.
path	string	Required. The path asked for, as sent (to_path).

Person

A person, as far as a file record names them.

Field	Type	Description
id	string	Required. The person’s id (their directory guid).
name	string	Required. Display name.

ProblemDetails

An error, as application/problem+json (RFC 9457). Branch on type (or code), never on title or detail.

Field	Type	Description
type	string (uri)	Required. What went wrong, as a URL: https://<host>/api/v1/problems/<slug>. New types may appear.
title	string	Required. A short human summary of the type.
status	integer	Required. The HTTP status.
code	string	Required. The same condition as an upper-case code, as Foldr’s other APIs name errors.
detail	string or null	More about this occurrence, where there is anything safe to say.
instance	string or null	A fault code for this occurrence (”#” and 8 hex digits) to quote to support, where there is one.
operation	Operation or null	Where the problem is how an operation ended (getOperation on a failed or cancelled one): that operation, as it stands.

Used by: listFields, getMe, listOperations, getOperation, cancelOperation, search, listShareRequests, getShareRequest, listShares, getShare, listChildren, getContent, overwriteFile, copyItem, getDownloadUrl, getFieldValues, setFieldValue, uploadFile, createFolder, getItem, deleteItem, moveItem, renameItem, createShareRequest, listVersions, restoreVersion, createUploadSession, cancelUploadSession, completeUploadSession.

RenameBody

A file or folder to rename where it is.

Field	Type	Description
path	string	Required. The path of the file or folder to rename.
new_name	string	Required. Its new name: one name, no ”/”, no spaces at either end. Something already called that is never replaced (409 conflict).

Used by: renameItem.

RestoreVersionBody

A file, and which of its versions to make current again.

Field	Type	Description
path	string	Required. The path of the file.
version_id	string	Required. The version to restore: an id listVersions gave for this file.
as_copy	boolean	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.

Used by: restoreVersion.

SearchHit

One search result.

Field	Type	Description
item	Item	Required. The item found, as the search index knows it.
score	number or null	Required. Relevance: higher is better, comparable only within one response’s ordering.
snippet	string or null	Required. A short passage of text around the match, where there is one and it may be shown.

SearchResults

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.

Field	Type	Description
items	array of SearchHit	Required. This page’s hits.
next_cursor	string or null	Required. 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.
total_estimate	integer	Required. About how many items match, over every index searched. An estimate: it is not a count of the pages to come.
not_searched	array of NotSearched	Required. The person’s shares this search did not cover, and why.

Used by: search.

SetFieldValueBody

A custom field value to set on one file.

Field	Type	Description
path	string	Required. The path of the file (files only).
value	any	Required. 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.

Used by: setFieldValue.

Share

A share: a storage location the person can read. Files and folders are addressed by a share id plus a path inside it.

Field	Type	Description
id	string (uuid)	Required. The share’s id. Always a uuid.
name	string	Required. The share’s name, as people see it in Foldr.
type	string	Required. 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.
indexed	boolean	Required. Whether the share is indexed for GET /search.
read_only	boolean	Required. True when the person cannot change anything in the share.
reachable	boolean	Required. 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.

Used by: getShare.

SharePage

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.

Field	Type	Description
items	array of Share	Required. This page’s entries.
next_cursor	string or null	Required. The cursor for the next page, or null when this is the last.
truncated	boolean	Required. 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.

Used by: listShares.

ShareRequest

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.

Field	Type	Description
id	string (uuid)	Required. The request’s id.
share_id	string (uuid)	Required. The id of the share the item is in.
path	string	Required. The item’s canonical path.
kind	string	Required. What was asked for. Known values: people, public_link, secure_link, inbox. Clients must accept values not listed here.
status	string	Required. 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.
created_at	string or null (date-time)	Required. When it was asked for (RFC 3339, UTC).
decided_at	string or null (date-time)	Required. When it was decided, or null while it waits.

Used by: getShareRequest, createShareRequest.

ShareRequestBody

What to share and how. A request always waits for an approver; nothing is shared until one approves it.

Field	Type	Description
path	string	Required. The path of the file or folder to share (an inbox needs a folder).
kind	string, one of people, public_link, secure_link, inbox	Required. 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).
people	array or null	For people: their email addresses, usernames or exact group names (at most 20).
permission	string or null, one of read, write, null	For people: “read” (the default) or “write”.
recipient_emails	array or null	For secure_link: the outside email addresses it is for (at most 20).
expiry_days	integer or null	Days until access ends once approved; 0 or absent for never. For a link, -1 ends it after its first download.
message	string or null	A note shown with the link (at most 1,000 characters).

Used by: createShareRequest.

ShareRequestPage

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.

Field	Type	Description
items	array of ShareRequest	Required. This page’s entries.
next_cursor	string or null	Required. The cursor for the next page, or null when this is the last.
truncated	boolean	Required. 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.

Used by: listShareRequests.

UploadSession

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.

Field	Type	Description
id	string	Required. The session’s id, for complete and cancel.
mode	string	Required. How the file is sent: direct, straight to the storage. Known values: direct. Clients must accept values not listed here.
share_id	string (uuid)	Required. The id of the share.
path	string	Required. The canonical path the file will have (on_conflict “rename” may have given it a new name).
size	integer	Required. The size declared, in bytes.
url	string (uri)	Required. Where to send the file.
method	string	Required. The HTTP method to send it with (PUT or POST).
headers	map of string	Required. Headers to send with it, exactly as given.
chunk_size	integer or null	Required. 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.
expires_at	string or null (date-time)	Required. Send the file before this time (RFC 3339, UTC); then the url stops working. Complete the session afterwards.

Used by: createUploadSession.

UploadSessionBody

A file to upload straight to the share’s storage.

Field	Type	Description
share_id	string (uuid)	Required. The id of the share.
path	string	Required. The new file’s full path in the share, its name last. The folder it goes in must exist.
size	integer	Required. The file’s exact size in bytes. Completing the session checks the storage holds exactly this many.
on_conflict	string, one of fail, rename	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.
content_type	string or null	The file’s media type, where the storage records one (default application/octet-stream).

Used by: createUploadSession.

Version

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).

Field	Type	Description
id	string	Required. The version’s id, as the storage names it: what restoreVersion takes. Opaque; never build one.
modified	string or null (date-time)	Required. When this version was saved (RFC 3339, UTC), where the storage says.
size	integer or null	Required. Its size in bytes, where the storage says.
current	boolean	Required. True for the version the file is now.

VersionPage

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.

Field	Type	Description
items	array of Version	Required. This page’s entries.
next_cursor	string or null	Required. The cursor for the next page, or null when this is the last.
truncated	boolean	Required. 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.

Used by: listVersions.