API

Folders and access

List, make, rename, move and delete folders, and restrict who may see or change folders and documents.

Documents live in folders, written as paths such as /marketing/2026/. Until anyone grants access, a member's role alone decides what they may see and change.

folders.move renames or moves a folder with everything in it, its grants included, and folders.delete deletes one with no documents left outside the trash. Moving a folder out from under a restricted folder also takes a manage grant on that folder.

A grant gives a member or a group view, edit or manage on a folder or a document. The first grant restricts it: from then on only the members grants name, and Owners, may see it. A document's own grants decide it if it has any; otherwise those of the nearest folder above it that has any. An edit grant lets a member change things only if their role may edit; manage lets them change who has access there.

To change grants, the caller needs a manage grant there, or documents.access.manage while it is still unrestricted, or to be an Owner. Something the caller cannot see answers 404 not_found, so its existence is not confirmed.

List folders the caller can see

GET /folders folders.list

Every folder path in the workspace that the caller may see, sorted, the root / included. A path starts and ends with /, such as /marketing/2026/. Empty folders are included. A restricted folder, or one inside it, is left out unless the grants on the nearest restricted folder name the caller or a group they are in; an Owner sees every folder. restricted names the folders listed that have grants of their own.

Scopes
documents.read
MCP tool
folders_list

Response

200 OK. A JSON object:

Response fields (2)
NameTypeDescription
folders array of strings Folder paths the caller may see, sorted.
restricted array of strings The folders in folders that have grants of their own, sorted: renaming or moving one leaves nothing restricted at its old path.

Example request

curl https://api.flipbird.io/api/v1/folders \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "folders": [
    "string"
  ],
  "restricted": [
    "string"
  ]
}

Create a folder, including its ancestors

POST /folders folders.create

Makes the folder and any folder above it that does not exist yet, and returns the path as stored. A folder that exists already is left as it is. In a restricted folder the caller needs an edit or manage grant: a folder they cannot see answers 404 not_found, one they may only see 403 forbidden. A path that is not a valid folder answers 400 invalid_request.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
folders_create

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
path required string The folder's path: names separated by /, starting with /, such as /marketing/2026/. At most 12 levels, each name up to 80 characters and not . or ... A missing final / is added. 1 to 1,100 characters.

Response

201 Created. A JSON object:

Response fields (1)
NameTypeDescription
path string The folder's path as stored, ending in /.

Example request

curl -X POST https://api.flipbird.io/api/v1/folders \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "string"
}'
Example response
{
  "path": "string"
}

Rename or move a folder, with everything in it

POST /folders/move folders.move

Gives a folder a new path and returns it: renaming is a new last name, moving a new place, and both may change at once. The folders inside it, every document in it or under it (those in the trash too, so restoring one puts it back in the right place), and the grants on all of them go with it, in one step. Documents keep their updatedAt.

The top level / cannot move or be the new path, a folder cannot move into itself or a folder inside it, and a move that would put a folder more than 12 levels deep is refused, all with 400 invalid_request. A folder holding more than 20,000 documents, counting the trash, answers 400 too_many, with details.documents and details.limit: move the folders inside it first.

A path something already uses, a folder, a document or a grant, answers 409 conflict: folders are not merged. So does a document filed under the folder while the move is being decided: nothing moves, and the call can be sent again.

Nothing stays at the old path, grants included: a document or folder made there afterwards (by an upload or a client that still names it) goes into a new folder, without the moved folder's grants. The caller needs edit on the folder and on the place it goes, as folders.create does: a folder or destination they cannot see answers 404 not_found, one they may only see 403 forbidden.

Moving the folder's documents changes them, so a document in it or under it, in the trash or not, that the caller may not change (a colleague's, for a member who may edit only their own; one in a restricted folder they hold no edit grant on) makes it 403 forbidden; the message counts them, documents the caller cannot see included. Grants on the folder and on the folders inside it move with them.

When the folder has no grants of its own and the nearest folder above it that has grants is a different one after the move, the caller also needs a manage grant on the one above it now, or to be an Owner with the documents.access.manage permission (403 forbidden). A folder with grants of its own, a move that stays under the same folder with grants, and a move from where no folder above has grants need edit only.

This rule is for moving folders: documents.update moves a single document out of a restricted folder with edit access to it.

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
folders_move

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
from required string The folder to rename or move, as a path such as /marketing/2025/. A missing final / is added. 1 to 1,100 characters.
to required string Its new path, such as /marketing/archive/2025/ to move it or /marketing/2025-spring/ to rename it. Each name up to 80 characters, not . or ..; a missing final / is added. The folders above it are made if they do not exist. 1 to 1,100 characters.

Response

200 OK. A JSON object:

Response fields (3)
NameTypeDescription
path string The folder's new path, as stored.
documents number How many documents moved: those in it and in the folders inside it, the trash's included.
folders number How many folders moved: it, when it is stored as a folder, and the folders inside it.

Example request

curl -X POST https://api.flipbird.io/api/v1/folders/move \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "string",
  "to": "string"
}'
Example response
{
  "path": "string",
  "documents": 1,
  "folders": 1
}

Delete an empty folder

DELETE /folders folders.delete

Deletes a folder that holds no documents, with the empty folders inside it and the grants on them, and returns what went. A folder with a document in it or under it, outside the trash, answers 409 folder_not_empty, with details.documents counting them, documents the caller cannot see included. Documents in the trash do not stop it: each keeps the folder it was in, and restoring it makes that folder again.

A trashed document whose access the deleted grants decided keeps it: those grants are copied onto the document itself first. A delete that would make more than 5,000 such copies answers 400 too_many, with details.copies and details.limit, and deletes nothing. The top level / cannot be deleted (400 invalid_request), and a folder that does not exist answers 404 not_found.

The caller needs edit on the folder, as folders.create does (404 not_found when they cannot see it, 403 forbidden when they may only see it), and, for the grants that go with it, a manage grant on each restricted folder among them, or to be an Owner with the documents.access.manage permission (403 forbidden).

Scopes
documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
folders_delete

Query parameters

NameTypeDescription
path required string The folder to delete, as a path such as /marketing/2025/. A missing final / is added. 1 to 1,100 characters.

Response

200 OK. A JSON object:

Response fields (3)
NameTypeDescription
path string The folder deleted, as it was stored.
folders number How many folders went: it and the empty folders inside it.
trashedDocuments number How many documents in the trash still name it, or a folder inside it, as their folder.

Example request

curl -X DELETE "https://api.flipbird.io/api/v1/folders?path=string" \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Example response
{
  "path": "string",
  "folders": 1,
  "trashedDocuments": 1
}

Grants on a folder or a document

GET /grants grants.list

The grants on one folder or one document, whether it is restricted, and every member and group to choose from when granting. Name exactly one of folder and documentId, or the call answers 400 invalid_request. A folder or document is restricted when it, or a folder above it, has any grant: then only the members those grants name, directly or through a group, and Owners may see it.

The caller needs a manage grant there, or the documents.access.manage permission while it is still unrestricted, or to be an Owner with that permission (403 forbidden). A folder or document the caller cannot see answers 404 not_found.

Scopes
documents.read
MCP tool
grants_list

Query parameters

NameTypeDescription
folder string The folder to read the grants of, as a path such as /marketing/2026/. Give this or documentId. 1 to 1,100 characters.
documentId string The document to read the grants of. Give this or folder. An id starting doc_.

Response

200 OK. A JSON object:

Response fields (16)
NameTypeDescription
grants array of objects The grants on exactly this folder or document, oldest first. Grants on folders above it are not listed.
grants[].id string The grant's id. It stays the same when the grant's level is changed.
grants[].folder string The folder the grant is on, as a path such as /marketing/2026/; null for a grant on a document. Can be null.
grants[].documentId string The document the grant is on; null for a grant on a folder. Can be null.
grants[].userId string The member the grant is for; null for a grant to a group. Can be null.
grants[].groupId string The group the grant is for; null for a grant to a member. Can be null.
grants[].level string What the grant allows: view (see it), edit (also change it, for a member whose role may edit documents) or manage (also change who has access to it). One of view, edit, manage.
grants[].createdAt number When the grant was first made, in epoch milliseconds.
restricted boolean Whether a grant on it, or on a folder above it, limits who may see it.
members array of objects Every member of the workspace, ordered by email address, to choose whom to grant to.
members[].userId string The member's user id.
members[].name string The member's name; empty when they gave none.
members[].email string The member's email address.
groups array of objects Every group, ordered by name, to choose from.
groups[].id string The group's id.
groups[].name string The group's name.

Example request

curl https://api.flipbird.io/api/v1/grants \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "grants": [
    {
      "id": "string",
      "folder": "/catalogues",
      "documentId": "…",
      "userId": "…",
      "groupId": "…",
      "level": "view",
      "createdAt": 1767225600000
    }
  ],
  "restricted": true,
  "members": [
    {
      "userId": "…",
      "name": "Spring catalogue",
      "email": "alex@example.com"
    }
  ],
  "groups": [
    {
      "id": "string",
      "name": "Spring catalogue"
    }
  ]
}

Grant view, edit or manage on a folder or a document

PUT /grants grants.put

Gives a member or a group view, edit or manage on a folder or a document, and returns the grant. Name exactly one of folder and documentId, and exactly one of userId and groupId, or the call answers 400 invalid_request. If that member or group has a grant there already, its level is replaced and its id kept.

The first grant on a folder or document restricts it: from then on only the members grants name, directly or through a group, and Owners may see it. What decides a document is its own grants if it has any, otherwise those of the nearest folder above it that has any.

An edit grant lets a member change things only if their role may edit documents; a manage grant lets them change who has access there even without the documents.access.manage permission. Granting on a folder that does not exist yet makes it. The caller needs a manage grant there, or the documents.access.manage permission while it is still unrestricted, or to be an Owner with that permission (403 forbidden).

A read-only key never changes access, whatever its member's role or grants (403 forbidden). A folder or document the caller cannot see, an unknown group, or someone who is not a member answers 404 not_found.

Scopes
documents.read, documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
grants_put

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
folder string The folder to grant on, as a path such as /marketing/2026/. Give this or documentId. 1 to 1,100 characters.
documentId string The document to grant on. Give this or folder. An id starting doc_.
userId string The member to grant to. Give this or groupId. An id starting usr_.
groupId string The group to grant to. Give this or userId. An id starting grp_.
level required string What to allow: view (see it), edit (also change it) or manage (also change who has access to it). One of view, edit, manage.

Response

200 OK. A JSON object:

Response fields (7)
NameTypeDescription
id string The grant's id. It stays the same when the grant's level is changed.
folder string The folder the grant is on, as a path such as /marketing/2026/; null for a grant on a document. Can be null.
documentId string The document the grant is on; null for a grant on a folder. Can be null.
userId string The member the grant is for; null for a grant to a group. Can be null.
groupId string The group the grant is for; null for a grant to a member. Can be null.
level string What the grant allows: view (see it), edit (also change it, for a member whose role may edit documents) or manage (also change who has access to it). One of view, edit, manage.
createdAt number When the grant was first made, in epoch milliseconds.

Example request

curl -X PUT https://api.flipbird.io/api/v1/grants \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "level": "view"
}'
Example response
{
  "id": "string",
  "folder": "/catalogues",
  "documentId": "…",
  "userId": "…",
  "groupId": "…",
  "level": "view",
  "createdAt": 1767225600000
}

Remove a grant

DELETE /grants/{grantId} grants.delete

Removes the grant and returns an empty object. Once a folder or document has no grants left, the nearest folder above it with grants decides who may see it, or, when there is none, the members' roles alone. The caller needs a manage grant on that folder or document, or to be an Owner with the documents.access.manage permission (403 forbidden).

An unknown grant, or one on a folder or document the caller cannot see, answers 404 not_found.

Scopes
documents.read, documents.edit
Retries
Safe with an Idempotency-Key
MCP tool
grants_delete

Path parameters

NameTypeDescription
grantId required string The grant's id. An id starting grt_.

Response

200 OK. An empty JSON object, {}.

Example request

curl -X DELETE https://api.flipbird.io/api/v1/grants/grt_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Errors

Besides the errors any endpoint can answer, these endpoints answer:

StatusCodeWhen
409conflictTwo requests made the same grant at the same moment, or a folder is moved to a path a folder, document or grant already uses. A grant sent again replaces its level.
400too_manyMoving a folder that holds too many documents, or deleting one that would copy its grants onto too many in the trash, in one call. details.limit says how many one call takes.
409folder_not_emptyDeleting a folder with documents in it or under it, outside the trash. details.documents counts them.