Bridge

Bridge runs Gmail, Google Drive, Slack, and Granola connections for your users under your own OAuth apps. Your backend calls the API with one organization API key; users consent on Google or Slack and return to your platform.

OAuth setupCopy Anchor Link

Register your apps once per organization under Bridge → Apps in the dashboard. Each card's dialog shows the redirect URI and, for Slack, the manifest to copy. The scopes and events each app needs are listed under Scopes and events and returned by List OAuth Clients as required_scopes.

Gmail and Google Drive are separate apps: enter one Google client on both cards or a different client on each. A shared client needs both redirect URIs authorized. Set the user type and publish the app on Google Auth Platform's Audience page; an app left in Testing gets refresh tokens that expire after 7 days.

Use an existing appCopy Anchor Link

You can register an OAuth app you already operate instead of creating a new one. Configure it at the provider first, keeping everything the app already has, then enter its credentials under Bridge → Apps. Connections made through another app must reconnect afterwards.

Google (Gmail, Google Drive)Copy Anchor Link

SlackCopy Anchor Link

https://api.mixedbread.com/v1/integrations/slack/oauth/callback

https://api.mixedbread.com/v1/integrations/slack/events

Return URLCopy Anchor Link

The page on your platform where users land after consent, for example https://platform.example.com/connected (http://localhost is allowed for development). The callback appends these query parameters:

Scopes and eventsCopy Anchor Link

Consent asks for exactly these scopes. A Google app requests them at authorization time, so nothing is configured on the client, but the consent screen must list them if it is published with a scope list. A Slack app must declare them on the app itself; the manifest does.

Slack is not polled. After the first sync, new and edited messages reach a user's store only through the Slack Events API, so the app must also deliver events to Mixedbread:

An app created from the manifest in the dashboard has the scopes and the events already. See Slack's app manifest guide if you need to review or update the configuration. If you create the app by hand or reuse an existing app, open it in the Slack app dashboard, keep the required scopes and redirect URL under OAuth & Permissions, and keep the request URL and events under Event Subscriptions; Slack verifies the request URL when it is saved. Every event is checked against the signing secret you registered, so after rotating the secret in Slack, update the app under Bridge → Apps or events are rejected and stores stop receiving new messages.

API referenceCopy Anchor Link

OAuth clientsCopy Anchor Link

ConnectCopy Anchor Link

InstallationsCopy Anchor Link

StoresCopy Anchor Link

Stores and installationsCopy Anchor Link

An installation is one connected account feeding one store. Every connect creates an installation; to refresh an existing one, reconnect it. Every connect endpoint takes store_name and new_store.

Shared storesCopy Anchor Link

Stores are shared. store_name may name a store that already exists, including one that other data sources already feed. Connect a user's Gmail and Slack with the same store_name and both ingest into one store, searched with one store id:

curl -s -o /dev/null -w '%{redirect_url}' \
  'https://api.mixedbread.com/v1/integrations/gmail/oauth/authorize?store_name=user-42&reference=user-42' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl -s -o /dev/null -w '%{redirect_url}' \
  'https://api.mixedbread.com/v1/integrations/slack/oauth/authorize?store_name=user-42&reference=user-42' \
  -H 'Authorization: Bearer YOUR_API_KEY'

The one exception: two installations of the same account cannot feed the same store, because every item would be ingested twice. That connect fails with 409, or error=store_in_use on the return URL.

Without store_name, the installation ingests into the account's default store, for example gmail-<email>. Connecting the same account again without store_name numbers the default (gmail-<email>-2, -3, …) past any store another installation of the account feeds.

Several installations of one accountCopy Anchor Link

Each installation has its own store and its own selection, so one account can be split across stores. A Slack user can, for example, keep public channels in one store and direct and group messages in another: connect twice with different store_names, then select the public_channels alias on the first installation and the direct_messages and group_messages aliases on the second (see Replace Resources). Slack events fan out to every installation whose selection covers the conversation, each ingesting into its own store.

The same account can also be connected in several Mixedbread organizations; each organization's installation is its own, with its own store and selection. Disconnecting one installation keeps the provider grant while another installation of the account still uses it, in any organization.

New storesCopy Anchor Link

new_store=true ingests into a store created for this connection. When store_name names a store that already exists, the connect fails with 409, or error=store_exists on the return URL. Without store_name, the default name is numbered past every store that exists. A reconnect keeps the installation's store, so it cannot set new_store (422, or error=new_store_on_refresh on the return URL) or name another store in store_name (422, or error=store_change_on_refresh).

ReconnectCopy Anchor Link

Reconnecting refreshes one installation's credentials and keeps its store, for example after the installation reports status: "needs_reauth":

curl -s -o /dev/null -w '%{redirect_url}' \
  'https://api.mixedbread.com/v1/integrations/gmail/installations/INSTALLATION_ID/oauth/authorize?reference=user-42' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Google Drive and Slack have the same route under google_drive and slack. The user must authorize the account already connected to the installation; consent for any other account returns error=reconnect_account_mismatch. The installation_id query parameter on Authorize Gmail and Authorize Google Drive still reconnects but is deprecated in favour of this route.

Granola reconnects with a new API key instead of consent; see Reconnect Granola.

GmailCopy Anchor Link

curl -s -o /dev/null -w '%{redirect_url}' \
  'https://api.mixedbread.com/v1/integrations/gmail/oauth/authorize?store_name=mail-42&reference=user-42' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": {
    "installation_id": "2f1c9a8e-6b4d-4e3a-9c1f-7d8e5b6a4c21",
    "provider": "gmail",
    "status": "active",
    "account": { "id": "olivia@example.com", "name": "olivia@example.com", "email": "olivia@example.com", "workspace": null },
    "store_id": "5d3e7f9a-1b2c-4d6e-8f0a-9c8b7a6d5e4f",
    "store_name": "mail-42",
    "sync": { "failed_resource_count": 0, "last_error": null, "last_error_operation": null, "last_error_at": null }
  }
}

curl -X POST https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/sync \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"sync_all": true}'

curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl -X PUT https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"resource_ids": ["INBOX", "Label_12"]}'

# installation status and account-level errors
curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'

# per-resource outcome in resources[].sync.last_run
curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources \
  -H 'Authorization: Bearer YOUR_API_KEY'

# resources whose last job failed
curl https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources/failed \
  -H 'Authorization: Bearer YOUR_API_KEY'

# files ingested so far, in file_counts
curl https://api.mixedbread.com/v1/stores/STORE_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl -X POST https://api.mixedbread.com/v1/stores/search \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"query": "renewal terms", "store_identifiers": ["STORE_ID"], "top_k": 10}'

Google DriveCopy Anchor Link

Same flow as Gmail with /v1/integrations/google_drive/oauth/authorize. Sync the whole Drive:

curl -X POST https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/sync \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"sync_all": true}'

Differences:

• sync_all runs one job over the whole Drive, Shared with me included, and registers push notifications for changes. queued_resource_ids is empty and the root folders keep last_run: null; watch file_counts on the store instead. Shared drives are not part of it: select the Shared drives resource to sync those.
• Resources are hierarchical: list a folder's children with ?parent_id=FOLDER_ID. Selecting a folder syncs its subtree.
• The root listing holds My Drive, Shared with me, and Shared drives when the account is a member of any. The last two are folders like the others: selecting one syncs everything it holds now and later, and selecting a single shared drive under it syncs only that drive. The two do not overlap — a file that lives in a shared drive is synced through that drive, even when it was also shared with the account directly.
• google_drive.folder_path on a store file is the location the user recognises, rooted at the scope the file came from: My Drive/Reports/2026 or Shared drives/Engineering/Specs.
• Files Drive cannot export (unsupported types, empty files) are skipped, not failed.
• Reconnect after needs_reauth through /v1/integrations/google_drive/installations/INSTALLATION_ID/oauth/authorize with the same Google account.

SlackCopy Anchor Link

Same flow with /v1/integrations/slack/oauth/authorize. Sync every conversation the user can read:

curl -X POST https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/sync \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"sync_all": true}'

Differences:

• Users connect as themselves (access_mode=user, the default), each with their own installation and store. account.workspace holds the workspace name. Only user mode is accepted over the API: a request with access_mode=bot is rejected with 403, because a bot installation joins the whole workspace and every selected channel, which your users cannot see or consent to. Workspace bots are installed from the dashboard only.
• sync_all selects all four conversation kinds below. Public channels are ingested whether or not the user has joined them, as the user can read them in Slack.
• New messages arrive only through Slack events; there is no schedule to set.
• Reconnect through /v1/integrations/slack/installations/INSTALLATION_ID/oauth/authorize as the same Slack user.

Conversation kindsCopy Anchor Link

A Slack selection is made of aliases, one per kind of conversation, plus any individual conversations. An alias covers every conversation of its kind the user can read, including ones that appear later. The listing's aliases names them:

To sync only private conversations, plus one public channel the user cares about:

curl -X PUT https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/resources \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "resource_aliases": ["private_channels", "direct_messages", "group_messages"],
    "resource_ids": ["C0123ABC"]
  }'

The request replaces the whole selection: aliases and conversations not listed stop syncing, and what was already imported stays in the store. The listing reports the result as selected_resource_aliases, flags each alias with is_selected, and sets sync_all to true only while all four are selected:

{
  "aliases": [
    { "id": "public_channels", "name": "Public channels", "kind": "channel", "is_selected": false },
    { "id": "private_channels", "name": "Private channels", "kind": "private_channel", "is_selected": true },
    { "id": "direct_messages", "name": "Direct messages", "kind": "direct_message", "is_selected": true },
    { "id": "group_messages", "name": "Group messages", "kind": "group_message", "is_selected": true }
  ],
  "selected_resource_aliases": ["private_channels", "direct_messages", "group_messages"],
  "selected_resource_ids": ["C0123ABC"],
  "sync_all": false
}

How conversations enter a selected alias:

• Right after connecting, the conversation catalog is still being built: the listing reports listing_status: "loading", and a selection saved meanwhile is applied when the walk completes.
• Channels the user creates, joins, or unarchives are added from Slack events, their history is imported, and they stay current. A private channel the user leaves stops syncing the same way.
• A public channel the user has not joined is imported in full and kept current from Slack events, like any other selected conversation.
• Slack sends no event when a direct message or group message is opened, so one is added when its first message arrives. That message and the rest of the conversation are imported with it.
• A channel that turns private or public moves to the other kind: it starts syncing if that alias is selected and stops if not. A conversation selected by ID keeps syncing whatever its kind.
• Refresh Resources rebuilds the whole catalog on demand, for example after a long outage of your events endpoint.

GranolaCopy Anchor Link

No OAuth. Connect with the user's API key and state who it belongs to:

curl -X POST https://api.mixedbread.com/v1/integrations/granola/connect \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "api_key": "GRANOLA_API_KEY",
    "account_name": "Olivia Chen",
    "account_email": "olivia@example.com",
    "store_name": "notes-42"
  }'

The response has the shape of Get Installation: data.installation_id and data.store_id. An invalid key returns 422. Sync every note:

curl -X POST https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID/sync \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"sync_all": true}'

Then monitor and search as in steps 4 and 5 of the Gmail flow. Differences:

• sync_all imports every note the key can see. Mixedbread registers and manages a Granola webhook for each installation, so generated and edited notes arrive as Granola sends them; your platform configures nothing. Deleted notes, which Granola sends no event for, are caught by polling every ten minutes by default; change the cadence with Update Installation Schedule: off, ten_minutes, hourly, daily, or weekly.
• Resources are folders, listed hierarchically like Drive.
• Personal keys expire on Granola's side. The installation then records sync.last_error until it is reconnected with a new key.

Reconnect GranolaCopy Anchor Link

Replace an installation's API key, for example after the user's personal key expired:

curl -X POST https://api.mixedbread.com/v1/integrations/granola/installations/INSTALLATION_ID/reconnect \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"api_key": "NEW_GRANOLA_API_KEY"}'

The installation keeps its store, folder selection and sync schedule, and the response has the shape of Get Installation. Granola cannot tell whose key it is, so the new key is not checked against the old one: pass the key of the user the installation belongs to. An invalid key returns 422, and an unknown installation 404. Connecting the new key through Connect Granola instead creates a second installation next to the old one.

DisconnectCopy Anchor Link

curl -X DELETE https://api.mixedbread.com/v1/integrations/installations/INSTALLATION_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'

Stops the sync and revokes the grant at the provider. Google revokes the whole authorization for a client, so a Google grant is kept while another installation of the same account uses the same OAuth client, for example Gmail and Drive on one client. The store and its files remain; delete the store separately if the data should go too.