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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
userId required | string | The member's user id. An id starting usr_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
groupId required | string | The group's id. An id starting grp_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
groupId required | string | The group's id. An id starting grp_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
userId required | string | The user id of the member to add. An id starting usr_. |
Response
201 Created. A JSON object:
Response fields (4)
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
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)
| Name | Type | Description |
|---|---|---|
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:
| Status | Code | When |
|---|---|---|
| 400 | invalid | A group name with control or direction characters. |
| 403 | cannot_grant | The caller lacks a permission of the role involved, so may not give, change or remove it. |
| 409 | last_owner | Demoting or removing the last active Owner. |
| 409 | last_sso_owner | Sign-in is by SAML only, and no other active Owner is known to sign in with it. |
| 409 | already_member | The address belongs to a member, active or deactivated. |
| 409 | conflict | A group name already taken, or a person already in the group. |