API

Team

List members and change their roles, invite people, and gather members into groups for access.

A workspace's people are its members. Each has one role, Owner, Admin, Standard or Accounts, which sets what they may do. An API key or a connected app acts for the member who made or approved it, with no more than that member's role allows now. When the member is removed, their keys stop working.

New people join by invite. invites.create emails a link that works for 7 days; the person accepts it with a code sent to the same address. A pending invite takes a seat like an active member, and the plan's seats limit counts both. You can give, change or take away only a role whose every permission you hold.

Groups gather members so one grant on a folder or document covers them all. members.export returns what Flipbird keeps about one member in this workspace, for answering a data-subject request.

List the members

GET /members members.list

Every member of the workspace, ordered by email address, deactivated members included (their deactivatedAt is set). Pending invites are listed by invites.list.

Scopes
team.manage
MCP tool
members_list

Response

200 OK. A JSON object:

Response fields (7)
NameTypeDescription
members array of objects Every member, ordered by email address.
members[].userId string The member's user id. A person has the same user id in every workspace they belong to.
members[].email string The member's email address.
members[].name string The member's name as they gave it; empty when they gave none.
members[].role string The member's role, which sets what they may do: Owner (everything), Admin (everything but billing, single sign-on, encryption and deleting for good), Standard (makes, edits and publishes documents, links and QR codes) or Accounts (billing only). One of Standard, Admin, Owner, Accounts.
members[].joinedAt number When the person joined this workspace, in epoch milliseconds.
members[].deactivatedAt number When the member was deactivated, in epoch milliseconds; null while active. A deactivated member cannot sign in, their API keys stop working, and they take no seat. Can be null.

Example request

curl https://api.flipbird.io/api/v1/members \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "members": [
    {
      "userId": "…",
      "email": "alex@example.com",
      "name": "Spring catalogue",
      "role": "Standard",
      "joinedAt": 1767225600000,
      "deactivatedAt": 1767225600000
    }
  ]
}

Change a member's role

PATCH /members/{userId} members.setRole

Gives the member a new role and returns them. The caller must hold every permission of both the member's current role and the new one, or the call answers 403 cannot_grant. Demoting the last active Owner answers 409 last_owner. While the workspace allows sign-in by SAML alone, demoting an Owner when no other active Owner is known to sign in with SAML answers 409 last_sso_owner.

Someone who is not a member answers 404 not_found. Giving a member the role they already have changes nothing.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
members_set_role

Path parameters

NameTypeDescription
userId required string The member's user id. An id starting usr_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
role required string The role to give: Owner, Admin, Standard or Accounts. You can give only a role whose every permission you hold. One of Standard, Admin, Owner, Accounts.

Response

200 OK. A JSON object:

Response fields (6)
NameTypeDescription
userId string The member's user id. A person has the same user id in every workspace they belong to.
email string The member's email address.
name string The member's name as they gave it; empty when they gave none.
role string The member's role, which sets what they may do: Owner (everything), Admin (everything but billing, single sign-on, encryption and deleting for good), Standard (makes, edits and publishes documents, links and QR codes) or Accounts (billing only). One of Standard, Admin, Owner, Accounts.
joinedAt number When the person joined this workspace, in epoch milliseconds.
deactivatedAt number When the member was deactivated, in epoch milliseconds; null while active. A deactivated member cannot sign in, their API keys stop working, and they take no seat. Can be null.

Example request

curl -X PATCH https://api.flipbird.io/api/v1/members/usr_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "Standard"
}'
Example response
{
  "userId": "…",
  "email": "alex@example.com",
  "name": "Spring catalogue",
  "role": "Standard",
  "joinedAt": 1767225600000,
  "deactivatedAt": 1767225600000
}

Remove a member and sign them out

DELETE /members/{userId} members.remove

Takes the person out of the workspace and ends their browser sessions here. Their group memberships and the access grants made to them personally are removed; the documents they made stay. API keys they made stop working (403 key_owner_removed). To keep them out but able to come back, deactivate them instead in the admin app. The caller must hold every permission of the member's role (403 cannot_grant).

The last active Owner cannot be removed (409 last_owner), nor, while the workspace allows sign-in by SAML alone, an Owner when no other active Owner is known to sign in with SAML (409 last_sso_owner). Someone who is not a member answers 404 not_found. Returns an empty object.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
members_remove

Path parameters

NameTypeDescription
userId required string The member's user id. An id starting usr_.

Response

200 OK. An empty JSON object, {}.

Example request

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

Export a member's data in this workspace

POST /members/{userId}/export members.export

Returns the same JSON export a member can download of their own data, for answering a data-subject request when that person cannot sign in: who they are, their live sessions, the API keys and connected apps they have, up to 200 documents they made, the invites they sent, up to 200 of their own audit entries, and their email preferences with the consent behind them.

It covers this workspace only, and works for a deactivated member too. Secrets, file bytes and the token in their unsubscribe link are left out. Each export is recorded in the audit log as member.export. Someone who is not a member answers 404 not_found.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
members_export

Path parameters

NameTypeDescription
userId required string The member's user id. An id starting usr_.

Request body

Send an empty JSON object, {}.

Response

200 OK. A JSON object:

Response fields (119)
NameTypeDescription
exportedAt number When the export was made, in epoch milliseconds.
workspace object The workspace the export covers. Nothing from other workspaces is in it.
workspace.id string The workspace's id.
workspace.slug string The workspace's slug: the first label of its address on flipbird.io.
workspace.name string The workspace's name.
subject object The person the export is about.
subject.userId string Their user id.
subject.email string Their email address.
subject.name string Their name as they gave it; empty when they gave none.
subject.role string Their role in this workspace. One of Standard, Admin, Owner, Accounts.
subject.joinedAt number When they joined this workspace, in epoch milliseconds.
subject.createdAt number When their Flipbird account was made, in epoch milliseconds.
subject.emailVerifiedAt number When their email address was verified, in epoch milliseconds; null if it has not been. Can be null.
sessions array of objects Their browser sessions in this workspace that are still live, most recently used first.
sessions[].method string How they signed in: otc (a code emailed to them), saml (single sign-on), google or microsoft (that provider's account). One of otc, saml, google, microsoft.
sessions[].userAgent string The browser's User-Agent header when they signed in.
sessions[].createdAt number When they signed in, in epoch milliseconds.
sessions[].lastSeenAt number When the session was last used, in epoch milliseconds.
sessions[].expiresAt number When the session expires, in epoch milliseconds.
apiKeys array of objects The API keys they made in this workspace, newest first, revoked and expired ones included. A key's secret is never included.
apiKeys[].id string The key's id.
apiKeys[].name string The key's name.
apiKeys[].prefix string The start of the key (xbk_ and six more characters), to recognise it by.
apiKeys[].scopes array of strings The permissions the key was given. It uses only those its maker's role still has.
apiKeys[].createdAt number When the key was made, in epoch milliseconds.
apiKeys[].lastUsedAt number When the key was last used, in epoch milliseconds, recorded at most once a minute; null if it never has been. Can be null.
apiKeys[].expiresAt number When the key stops working, in epoch milliseconds; null when it does not expire. Can be null.
apiKeys[].revokedAt number When the key was revoked, in epoch milliseconds; null if it was not. Can be null.
connectedApps array of objects The apps they approved through OAuth in this workspace, newest first, revoked ones included.
connectedApps[].id string The id of the person's approval of the app (its grant).
connectedApps[].clientName string The app's name, as it registered itself.
connectedApps[].scopes array of strings The permissions the person approved for it.
connectedApps[].resource string The address the app's access tokens are for, such as the public API's.
connectedApps[].createdAt number When the person approved the app, in epoch milliseconds.
connectedApps[].expiresAt number When the approval ends, in epoch milliseconds.
connectedApps[].revokedAt number When the approval was revoked, in epoch milliseconds; null if it was not. Can be null.
documents array of objects Up to 200 of the documents they made, newest first, leaving out those in the trash.
documents[].id string The document's id.
documents[].title string The document's title.
documents[].folder string The folder it is in, as a path such as /marketing/2026/.
documents[].createdAt number When the document was made, in epoch milliseconds.
documents[].updatedAt number When the document last changed, in epoch milliseconds.
invitesSent array of objects The invites they sent from this workspace, newest first.
invitesSent[].id string The invite's id.
invitesSent[].email string The address invited.
invitesSent[].role string The role the invite offered. One of Standard, Admin, Owner, Accounts.
invitesSent[].createdAt number When it was sent, in epoch milliseconds.
invitesSent[].expiresAt number When its link stops working, in epoch milliseconds.
invitesSent[].acceptedAt number When it was accepted, in epoch milliseconds; null if it was not. Can be null.
invitesSent[].revokedAt number When it was withdrawn, in epoch milliseconds; null if it was not. Can be null.
signatures array of objects Up to 200 of the signatures they made in this workspace, newest first: as a member, or through a signing request sent to their address.
signatures[].id string The signature's id.
signatures[].documentId string The document it is on.
signatures[].version number The version it made.
signatures[].mode string How it was made: signed in as a member, or through a signing request. One of current, version, copy, request.
signatures[].name string The name they signed with, printed under the signature.
signatures[].email string The address it was recorded under.
signatures[].verifiedBy string How they were identified. One of session, email_code.
signatures[].ip string The address it came from (an IPv6 address by its /64), or null. Can be null.
signatures[].userAgent string The browser it came from, cut to 256 characters, or null. Can be null.
signatures[].createdAt number When they signed, in epoch milliseconds.
signingRequests array of objects Up to 200 of the signing requests they made in this workspace, newest first.
signingRequests[].id string The signing request's id.
signingRequests[].documentId string The document it asked to be signed.
signingRequests[].signers array of strings The addresses it admitted.
signingRequests[].createdAt number When it was made, in epoch milliseconds.
signingRequests[].expiresAt number When its link stops working, in epoch milliseconds.
signingRequests[].completedAt number When everyone had signed, in epoch milliseconds; null if not. Can be null.
signingRequests[].cancelledAt number When it was cancelled, in epoch milliseconds; null if it was not. Can be null.
audit array of objects Up to 200 of the newest audit entries they made themselves, newest first.
audit[].id string The entry's id.
audit[].actorType string Who acted: user (a member, signed in), api_key (an API key), oauth (a connected app), system (Flipbird itself, such as a Stripe update or a scheduled task) or superadmin (Flipbird staff using support access).
audit[].actorId string Who acted, by actorType: a user id, an API key's id, a connected app's grant id or a staff member's id. For system, the name of the process (such as stripe) or null. Can be null.
audit[].action string What was done, as dotted lowercase words such as member.role.set or invite.create.
audit[].targetType string The kind of thing acted on, such as user, document, folder or webhook_endpoint; null when there is none. Can be null.
audit[].targetId string The id of the thing acted on (for a folder, its path); null when there is none. Can be null.
audit[].meta map of anys Details that depend on the action, such as a role's old and new values. Empty when there are none.
audit[].createdAt number When it happened, in epoch milliseconds.
contact object Their email preferences and the consent behind them; null when Flipbird keeps none for their address. Can be null.
contact.email string The address the preferences are for.
contact.firstName string Their first name as given; may be empty.
contact.lastName string Their last name as given; may be empty.
contact.locale string The language email is written to them in, as a primary language subtag such as en.
contact.country string Their country, as an ISO 3166-1 alpha-2 code such as AU; null when it is not known. Can be null.
contact.source string Where the record came from: signup (signing up), checkout (buying), account (their account settings), import (imported by Flipbird) or backfill (made from an account that existed before preferences were kept). One of signup, checkout, account, import, backfill.
contact.promotions boolean Whether they receive special offers and discounts.
contact.productUpdates boolean Whether they receive product and feature updates.
contact.consentAt number When they last opted in to either kind of email, in epoch milliseconds; null if they never have. Can be null.
contact.consentSource string Where that opt-in was given, as recorded at the time; null if they never opted in. Can be null.
contact.unsubscribedAt number When an unsubscribe link in an email last left them receiving neither kind, in epoch milliseconds; null if one never has. Can be null.
contact.unsubscribeReason string What they said when they unsubscribed; null if they said nothing. Can be null.
contact.createdAt number When the record was made, in epoch milliseconds.
marketing object Flipbird's own first-party analytics tied to them: only records made with their consent, as their country's consent profile requires. Records never tied to a person are not theirs and are not listed. An export an Admin or Owner makes of another member covers this workspace only, so it lists just the records tied to this workspace (for an Owner).
marketing.visits array of objects Campaign visits Flipbird's own analytics tied to them, oldest first. Only in their own export.
marketing.visits[].id string The visit's id.
marketing.visits[].at number When they landed, in epoch milliseconds.
marketing.visits[].landingPath string The page on flipbird.io they landed on.
marketing.visits[].device string The kind of device, from the browser's user agent; the user agent itself is never kept. One of mobile, tablet, desktop. Can be null.
marketing.visits[].referrerHost string The site the link was followed from; null when the browser did not say. Can be null.
marketing.visits[].source string What the link belonged to: an ad, an organic post or a Flipbird email; null when only UTM tags said. One of ad, post, email. Can be null.
marketing.visits[].sourceId string The id of that ad, post or email campaign; null when there was none. Can be null.
marketing.visits[].platform string The network the link was on, such as google; null for Flipbird's own emails and unknown links. Can be null.
marketing.visits[].utmSource string The link's utm_source tag; null when it had none. Can be null.
marketing.visits[].utmMedium string The link's utm_medium tag; null when it had none. Can be null.
marketing.visits[].utmCampaign string The link's utm_campaign tag; null when it had none. Can be null.
marketing.visits[].consentBasis string The consent the record was tied to them on: banner (they accepted analytics in the site's banner) or contact_opt_in (they had opted in to Flipbird's email). One of banner, contact_opt_in.
marketing.conversions array of objects Sign-ups, trials and payments tied to them (only in their own export) or, for an Owner, to this workspace, oldest first.
marketing.conversions[].id string The conversion's id.
marketing.conversions[].kind string What happened: a sign-up, a trial started, a first payment or a renewal. One of signup, trial, purchase, renewal.
marketing.conversions[].at number When it happened, in epoch milliseconds.
marketing.conversions[].valueMinor number The amount paid, in the currency's minor units; null for a sign-up or trial. Can be null.
marketing.conversions[].currency string The payment's currency, lower case such as aud; null when nothing was paid. Can be null.
marketing.conversions[].source string What the link belonged to: an ad, an organic post or a Flipbird email; null when only UTM tags said. One of ad, post, email. Can be null.
marketing.conversions[].sourceId string The id of that ad, post or email campaign; null when there was none. Can be null.
marketing.conversions[].platform string The network the link was on, such as google; null for Flipbird's own emails and unknown links. Can be null.
marketing.conversions[].utmSource string The link's utm_source tag; null when it had none. Can be null.
marketing.conversions[].utmMedium string The link's utm_medium tag; null when it had none. Can be null.
marketing.conversions[].utmCampaign string The link's utm_campaign tag; null when it had none. Can be null.
marketing.conversions[].consentBasis string The consent the record was tied to them on: banner (they accepted analytics in the site's banner) or contact_opt_in (they had opted in to Flipbird's email). One of banner, contact_opt_in.

Example request

curl -X POST https://api.flipbird.io/api/v1/members/usr_7m2kq9vx4c8d1r5t6wnb/export \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
Example response
{
  "exportedAt": 1767225600000,
  "workspace": {
    "id": "string",
    "slug": "string",
    "name": "Spring catalogue"
  },
  "subject": {
    "userId": "…",
    "email": "alex@example.com",
    "name": "Spring catalogue",
    "role": "Standard",
    "joinedAt": 1767225600000,
    "createdAt": 1767225600000,
    "emailVerifiedAt": 1767225600000
  },
  "sessions": [
    {
      "method": "otc",
      "userAgent": "string",
      "createdAt": 1767225600000,
      "lastSeenAt": 1767225600000,
      "expiresAt": 1767225600000
    }
  ],
  "apiKeys": [
    {
      "id": "string",
      "name": "Spring catalogue",
      "prefix": "string",
      "scopes": [
        "documents.read"
      ],
      "createdAt": 1767225600000,
      "lastUsedAt": 1767225600000,
      "expiresAt": 1767225600000,
      "revokedAt": 1767225600000
    }
  ],
  "connectedApps": [
    {
      "id": "string",
      "clientName": "string",
      "scopes": [
        "string"
      ],
      "resource": "string",
      "createdAt": 1767225600000,
      "expiresAt": 1767225600000,
      "revokedAt": 1767225600000
    }
  ],
  "documents": [
    {
      "id": "string",
      "title": "Spring catalogue",
      "folder": "/catalogues",
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000
    }
  ],
  "invitesSent": [
    {
      "id": "string",
      "email": "alex@example.com",
      "role": "Standard",
      "createdAt": 1767225600000,
      "expiresAt": 1767225600000,
      "acceptedAt": 1767225600000,
      "revokedAt": 1767225600000
    }
  ],
  "signatures": [
    {
      "id": "string",
      "documentId": "…",
      "version": 1,
      "mode": "current",
      "name": "Spring catalogue",
      "email": "alex@example.com",
      "verifiedBy": "session",
      "ip": "string",
      "userAgent": "string",
      "createdAt": 1767225600000
    }
  ],
  "signingRequests": [
    {
      "id": "string",
      "documentId": "…",
      "signers": [
        "string"
      ],
      "createdAt": 1767225600000,
      "expiresAt": 1767225600000,
      "completedAt": 1767225600000,
      "cancelledAt": 1767225600000
    }
  ],
  "audit": [
    {
      "id": "string",
      "actorType": "string",
      "actorId": "…",
      "action": "string",
      "targetType": "string",
      "targetId": "…",
      "meta": {},
      "createdAt": 1767225600000
    }
  ],
  "contact": {
    "email": "alex@example.com",
    "firstName": "string",
    "lastName": "string",
    "locale": "string",
    "country": "string",
    "source": "signup",
    "promotions": true,
    "productUpdates": true,
    "consentAt": 1767225600000,
    "consentSource": "string",
    "unsubscribedAt": 1767225600000,
    "unsubscribeReason": "string",
    "createdAt": 1767225600000
  },
  "marketing": {
    "visits": [
      {
        "id": "string",
        "at": 1,
        "landingPath": "string",
        "device": "mobile",
        "referrerHost": "string",
        "source": "ad",
        "sourceId": "…",
        "platform": "string",
        "utmSource": "string",
        "utmMedium": "string",
        "utmCampaign": "string",
        "consentBasis": "banner"
      }
    ],
    "conversions": [
      {
        "id": "string",
        "kind": "signup",
        "at": 1,
        "valueMinor": 1,
        "currency": "string",
        "source": "ad",
        "sourceId": "…",
        "platform": "string",
        "utmSource": "string",
        "utmMedium": "string",
        "utmCampaign": "string",
        "consentBasis": "banner"
      }
    ]
  }
}

List invites

GET /invites invites.list

Every invite the workspace has sent, newest first: pending, accepted, withdrawn and expired ones. An invite is pending while acceptedAt and revokedAt are null and expiresAt is still ahead; a pending invite takes a seat. A deleted invite is not listed.

Scopes
team.manage
MCP tool
invites_list

Response

200 OK. A JSON object:

Response fields (9)
NameTypeDescription
invites array of objects Every invite, newest first.
invites[].id string The invite's id.
invites[].email string The address invited.
invites[].role string The role the person gets on accepting: Owner, Admin, Standard or Accounts. One of Standard, Admin, Owner, Accounts.
invites[].invitedBy string The user id of the member who sent it; null when no member did. Can be null.
invites[].createdAt number When it was sent, in epoch milliseconds.
invites[].expiresAt number When its link stops working, in epoch milliseconds: seven days after it was sent.
invites[].acceptedAt number When it was accepted, in epoch milliseconds; null until then. Can be null.
invites[].revokedAt number When it was withdrawn, in epoch milliseconds, by invites.revoke or by a later invite to the same address; null if it was not. Can be null.

Example request

curl https://api.flipbird.io/api/v1/invites \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "invites": [
    {
      "id": "string",
      "email": "alex@example.com",
      "role": "Standard",
      "invitedBy": "string",
      "createdAt": 1767225600000,
      "expiresAt": 1767225600000,
      "acceptedAt": 1767225600000,
      "revokedAt": 1767225600000
    }
  ]
}

Invite someone

POST /invites invites.create

Emails the address a link to join the workspace in role, and returns the invite. The link works for seven days. To accept, the person also enters a code emailed to the same address, so a forwarded link alone admits no one. The link's secret is never returned by the API. An earlier pending invite to the same address is withdrawn.

emailSent is false when the email could not be sent; the invite still stands, and inviting the address again sends a new link. A pending invite takes a seat: when active members and pending invites already fill the plan's seats, the call answers 402 plan_required. You can invite only to a role whose every permission you hold (403 cannot_grant).

An address that belongs to a member already, active or deactivated, answers 409 already_member.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
invites_create

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
email required string The address to invite. Surrounding spaces and letter case are ignored. At most 254 characters.
role required string The role they get on accepting. You can invite only to a role whose every permission you hold. One of Standard, Admin, Owner, Accounts.

Response

201 Created. A JSON object:

Response fields (10)
NameTypeDescription
invite object The invite just made.
invite.id string The invite's id.
invite.email string The address invited.
invite.role string The role the person gets on accepting: Owner, Admin, Standard or Accounts. One of Standard, Admin, Owner, Accounts.
invite.invitedBy string The user id of the member who sent it; null when no member did. Can be null.
invite.createdAt number When it was sent, in epoch milliseconds.
invite.expiresAt number When its link stops working, in epoch milliseconds: seven days after it was sent.
invite.acceptedAt number When it was accepted, in epoch milliseconds; null until then. Can be null.
invite.revokedAt number When it was withdrawn, in epoch milliseconds, by invites.revoke or by a later invite to the same address; null if it was not. Can be null.
emailSent boolean Whether the email went out. When false the invite still stands; invite the address again to send a new link.

Example request

curl -X POST https://api.flipbird.io/api/v1/invites \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "alex@example.com",
  "role": "Standard"
}'
Example response
{
  "invite": {
    "id": "string",
    "email": "alex@example.com",
    "role": "Standard",
    "invitedBy": "string",
    "createdAt": 1767225600000,
    "expiresAt": 1767225600000,
    "acceptedAt": 1767225600000,
    "revokedAt": 1767225600000
  },
  "emailSent": true
}

Withdraw a pending invite

DELETE /invites/{inviteId} invites.revoke

Its link stops working and it no longer takes a seat. The invite stays listed, with revokedAt set. An invite that was accepted or withdrawn already, or that does not exist, answers 404 not_found. Returns an empty object.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
invites_revoke

Path parameters

NameTypeDescription
inviteId required string The invite's id. An id starting inv_.

Response

200 OK. An empty JSON object, {}.

Example request

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

Delete an invite

POST /invites/{inviteId}/delete invites.delete

Removes the invite record, whatever its state, so it is no longer listed. A pending link stops working. Someone who accepted it stays a member. You can delete only an invite to a role whose every permission you hold (403 cannot_grant). An unknown invite answers 404 not_found. Returns an empty object.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
invites_delete

Path parameters

NameTypeDescription
inviteId required string The invite's id. An id starting inv_.

Response

200 OK. An empty JSON object, {}.

Example request

curl -X POST https://api.flipbird.io/api/v1/invites/inv_7m2kq9vx4c8d1r5t6wnb/delete \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

List groups

GET /groups groups.list

Every group in the workspace, ordered by name, with the user ids of its members. A group lets one grant on a folder or a document cover several members at once (see grants.put).

Scopes
documents.read
MCP tool
groups_list

Response

200 OK. A JSON object:

Response fields (5)
NameTypeDescription
groups array of objects Every group, ordered by name.
groups[].id string The group's id.
groups[].name string The group's name, unique in the workspace.
groups[].members array of strings The user ids of the members in the group, sorted.
groups[].createdAt number When the group was made, in epoch milliseconds.

Example request

curl https://api.flipbird.io/api/v1/groups \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "groups": [
    {
      "id": "string",
      "name": "Spring catalogue",
      "members": [
        "string"
      ],
      "createdAt": 1767225600000
    }
  ]
}

Create a group

POST /groups groups.create

Makes an empty group and returns it. A name another group already has answers 409 conflict; a name with control or direction-override characters, 400 invalid.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
groups_create

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
name required string The group's name, unique in the workspace. Surrounding spaces are removed. 1 to 80 characters.

Response

201 Created. A JSON object:

Response fields (4)
NameTypeDescription
id string The group's id.
name string The group's name, unique in the workspace.
members array of strings The user ids of the members in the group, sorted.
createdAt number When the group was made, in epoch milliseconds.

Example request

curl -X POST https://api.flipbird.io/api/v1/groups \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Spring catalogue"
}'
Example response
{
  "id": "string",
  "name": "Spring catalogue",
  "members": [
    "string"
  ],
  "createdAt": 1767225600000
}

Rename a group

PATCH /groups/{groupId} groups.update

Gives the group a new name and returns it. Its members and grants are unchanged. A name another group already has answers 409 conflict; an unknown group, 404 not_found.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
groups_update

Path parameters

NameTypeDescription
groupId required string The group's id. An id starting grp_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
name required string The group's new name, unique in the workspace. Surrounding spaces are removed. 1 to 80 characters.

Response

200 OK. A JSON object:

Response fields (4)
NameTypeDescription
id string The group's id.
name string The group's name, unique in the workspace.
members array of strings The user ids of the members in the group, sorted.
createdAt number When the group was made, in epoch milliseconds.

Example request

curl -X PATCH https://api.flipbird.io/api/v1/groups/grp_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Spring catalogue"
}'
Example response
{
  "id": "string",
  "name": "Spring catalogue",
  "members": [
    "string"
  ],
  "createdAt": 1767225600000
}

Delete a group and its grants

DELETE /groups/{groupId} groups.delete

Deletes the group, its list of members and every grant made to it, so its members lose the access those grants gave them. The members stay in the workspace. An unknown group answers 404 not_found. Returns an empty object.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
groups_delete

Path parameters

NameTypeDescription
groupId required string The group's id. An id starting grp_.

Response

200 OK. An empty JSON object, {}.

Example request

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

Add a member to a group

POST /groups/{groupId}/members groups.addMember

Adds a member of the workspace to the group and returns the group. They gain the access the group's grants give. Someone who is not a member, or an unknown group, answers 404 not_found; someone already in the group, 409 conflict.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
groups_add_member

Path parameters

NameTypeDescription
groupId required string The group's id. An id starting grp_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
userId required string The user id of the member to add. An id starting usr_.

Response

201 Created. A JSON object:

Response fields (4)
NameTypeDescription
id string The group's id.
name string The group's name, unique in the workspace.
members array of strings The user ids of the members in the group, sorted.
createdAt number When the group was made, in epoch milliseconds.

Example request

curl -X POST https://api.flipbird.io/api/v1/groups/grp_7m2kq9vx4c8d1r5t6wnb/members \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "usr_7m2kq9vx4c8d1r5t6wnb"
}'
Example response
{
  "id": "string",
  "name": "Spring catalogue",
  "members": [
    "string"
  ],
  "createdAt": 1767225600000
}

Remove a member from a group

DELETE /groups/{groupId}/members/{userId} groups.removeMember

Takes the member out of the group and returns the group. They lose the access the group's grants gave them, and stay in the workspace. Someone not in the group answers 404 not_found.

Scopes
team.manage
Retries
Safe with an Idempotency-Key
MCP tool
groups_remove_member

Path parameters

NameTypeDescription
groupId required string The group's id. An id starting grp_.
userId required string The member's user id. An id starting usr_.

Response

200 OK. A JSON object:

Response fields (4)
NameTypeDescription
id string The group's id.
name string The group's name, unique in the workspace.
members array of strings The user ids of the members in the group, sorted.
createdAt number When the group was made, in epoch milliseconds.

Example request

curl -X DELETE https://api.flipbird.io/api/v1/groups/grp_7m2kq9vx4c8d1r5t6wnb/members/usr_7m2kq9vx4c8d1r5t6wnb \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Example response
{
  "id": "string",
  "name": "Spring catalogue",
  "members": [
    "string"
  ],
  "createdAt": 1767225600000
}

Errors

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

StatusCodeWhen
400invalidA group name with control or direction characters.
403cannot_grantThe caller lacks a permission of the role involved, so may not give, change or remove it.
409last_ownerDemoting or removing the last active Owner.
409last_sso_ownerSign-in is by SAML only, and no other active Owner is known to sign in with it.
409already_memberThe address belongs to a member, active or deactivated.
409conflictA group name already taken, or a person already in the group.