Foldr API v1

Developer guide

This guide is for developers building an app or integration that works with files in Foldr, on a Foldr Cloud site or on a Foldr server (an appliance) run by an organisation. You don’t need to know anything about how Foldr is built. With this guide and the OpenAPI document you can build a working client from nothing.

The guide says how the API behaves and why; the OpenAPI document is the exact contract (every field, header and status code). Where the two ever seem to differ, the OpenAPI document wins, and we’d like to hear about it.

What the API is

/api/v1 is Foldr’s public REST API. A few things are worth knowing before anything else.

An app acts as a person. The person signs in to Foldr, sees what your app asks for, and agrees. From then on your app calls the API with an OAuth access token and sees exactly what that person can see in Foldr, and can do only what they could do themselves (and, for changes, only what their organisation has allowed your app to do). There are no service accounts and no app-wide access.
Files live in shares. Foldr puts many kinds of storage (file servers, Microsoft 365, Google Drive, S3 and more) behind one set of shares. You address a share by its id and a file or folder by a path inside that share. The API looks the same whatever sits behind the share.
JSON in and out, except file contents, which are raw bytes. Errors are application/problem+json (RFC 9457).
It’s meant to be called from servers, scripts and automation tools, not from web pages. It sends no CORS headers, and OPTIONS is answered 405.
Every call is recorded against the person and your app, so an administrator can see what an app did.

Base URL

Every address is under /api/v1 on the host you sign in to Foldr at.

Where Foldr runs	Base URL
Foldr Cloud	`https://your-company.foldr.cloud/api/v1`
Your own domain on Foldr Cloud	`https://files.your-company.example/api/v1`
A Foldr server (appliance)	`https://<the server's name>/api/v1`

Use the address people type into their browser to reach Foldr, with /api/v1 after it. There is no central endpoint: each site is its own authorisation server and its own API, so an app that serves several organisations keeps one base URL, one set of tokens and one client registration per site.

In this guide the examples use https://files.example.com as the site. Replace it with yours.

The OpenAPI document

The API describes itself in an OpenAPI 3.1 document, served by the API itself and needing no token:

GET https://files.example.com/api/v1/openapi.json

Connector platforms (Power Automate, Logic Apps, n8n and the like) and code generators can import it from that address before they have a token. It is cached for five minutes and carries an ETag. Every operation has an operationId (listShares, uploadFile and so on); this guide uses those names, so you can match a section of the guide to an operation in the document.

The document also holds a few Foldr extensions:

x-foldr-rate-cost on each operation says what one call takes from your app’s rate budget (see Conventions).
info.version is the document’s own version number, and info.x-changelog lists what changed in each. Neither is the API’s major version, which is the v1 in the path.

Stability

The major version is in the path and nothing else selects a version: there is no version header and there are no dated versions. Within v1 we may add things, and we won’t break what’s there.

What may change within v1 at any time:

new endpoints, new optional parameters, new optional headers;
new fields in a response;
new values in a list the reference marks as open (marked x-extensible-enum, or described as “new values may appear”): Share type, Field type, Operation kind and phase, ShareRequest kind and status, and a few more;
new problem types;
a looser limit;
the encoding of cursors, which are opaque.

So your client should ignore fields it doesn’t recognise, accept enum values it doesn’t recognise where the reference says a list is open, and branch on a problem’s type or code, never on its title or detail.

What needs a new major version (/api/v2) or the deprecation route: removing or renaming an endpoint, field or parameter; changing a field’s type or meaning; making an optional input required; validating an existing input more strictly; a different status code for an existing condition; a changed default; a different scope on an existing endpoint; changing how pages or ids work; and changing how paths are written back to you (their case, their Unicode form, the leading /).

How long things last:

A major version is supported for at least 24 months after the next one is generally available.
A deprecated endpoint keeps working for at least 12 months before its sunset date.
On your own Foldr server, removal also waits for a major Foldr release, and the release notes of the two releases before it say what’s going, because servers upgrade on their owners’ schedules.
You’ll know an endpoint is deprecated from a Deprecation header (RFC 9745) on every response from it, a Sunset header (RFC 8594) once its date is set, a Link header with rel="deprecation", and deprecated: true in the OpenAPI document.
An endpoint marked x-foldr-stability: beta may change on 30 days’ notice and stays off unless the organisation opts in. There are none in v1 today.

One exception, which we’d rather say plainly: a change that closes a security hole may break a client without notice. We’ll say what changed straight afterwards.

What’s in this guide

Page	What it covers
Getting access	Turning connected apps on, registering your app, the OAuth 2.1 sign-in flow step by step, scopes, token lifetimes, refresh and revocation
Conventions	Ids, paths, ETags and conditional requests, idempotency keys, pagination, timestamps, rate limits, HEAD, 405 and 404
Errors	The problem document and every problem type, with what to do about each
Reading	Shares, listings, item metadata, downloads, search, custom fields, versions
Writing	Folders, uploads (streamed and direct), rename, overwrite, move, copy, delete, restore a version, field values, share requests
Operations and approval	Long-running operations (`202` and polling), cancelling, and changes held for approval
Recoverability and audit	What “can it be undone?” means on each kind of storage, and what administrators can see of an app
A worked example	A short end-to-end client in Python
Trying it in Postman	A ready-made Postman collection with a request for every operation, and how to use it
Troubleshooting and a checklist	Common questions, and what a well-behaved client does

A first look

Once you have an access token (see Getting access), this is the whole of a first session:

export FOLDR=https://files.example.com
export TOKEN=...   # an access token; never paste a real one into a script you commit

# Who am I?
curl -s -H "Authorization: Bearer $TOKEN" $FOLDR/api/v1/me

# Which shares can I read?
curl -s -H "Authorization: Bearer $TOKEN" $FOLDR/api/v1/shares

# What's in the top of one of them?
curl -s -H "Authorization: Bearer $TOKEN" \
  "$FOLDR/api/v1/shares/01a11dce-14f0-7f23-b857-c621356097a0/children"

The reference for every operation is the OpenAPI document. The rest of this guide is about the things the document can’t say well: how to get a token, what a person’s organisation can decide about your app, and how to behave when things go wrong.