mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-10 22:32:16 +02:00
feat: docs and ui tweaks
This commit is contained in:
DESKTOP-RTLN3BA\$punk
parent
64f2b4a6eb
commit
271a21aee6
103 changed files with 2161 additions and 2625 deletions
|
|
@ -1,103 +0,0 @@
|
|||
---
|
||||
title: Airtable
|
||||
description: Connect your Airtable bases to SurfSense
|
||||
---
|
||||
|
||||
# Airtable OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up an Airtable OAuth integration for SurfSense.
|
||||
|
||||
## Step 1: Access Airtable OAuth Integrations
|
||||
|
||||
1. Navigate to [airtable.com/create/oauth](https://airtable.com/create/oauth)
|
||||
2. In the **Builder Hub**, under **Developers**, click **"OAuth integrations"**
|
||||
3. Click **"Register an OAuth integration"**
|
||||
|
||||
|
||||
|
||||
## Step 2: Register an Integration
|
||||
|
||||
Fill in the basic integration details:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Name** | `SurfSense` |
|
||||
| **OAuth redirect URL** | `http://localhost:8000/api/v1/auth/airtable/connector/callback` |
|
||||
|
||||
Click **"Register integration"**
|
||||
|
||||
|
||||
|
||||
## Step 3: Configure Scopes
|
||||
|
||||
After registration, configure the required scopes (permissions) for your integration:
|
||||
|
||||
### Record data and comments
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `data.recordComments:read` | See comments in records |
|
||||
| `data.records:read` | See the data in records |
|
||||
|
||||
### Base schema
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `schema.bases:read` | See the structure of a base, like table names or field types |
|
||||
|
||||
### User metadata
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `user.email:read` | See the user's email address |
|
||||
|
||||
|
||||
|
||||
## Step 4: Configure Support Information
|
||||
|
||||
Scroll down to configure the support information and authorization preview:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Support email** | Your support email address |
|
||||
| **Privacy policy URL** | Your privacy policy URL |
|
||||
| **Terms of service URL** | Your terms of service URL |
|
||||
|
||||
The preview shows what users will see when authorizing SurfSense:
|
||||
- The data in your records
|
||||
- Comments in your records
|
||||
- The structure of your base, like table names or field types
|
||||
- Your email address
|
||||
|
||||
Click **"Save changes"**
|
||||
|
||||
|
||||
|
||||
## Step 5: Get OAuth Credentials
|
||||
|
||||
After saving, you'll find your OAuth credentials on the integration page:
|
||||
|
||||
1. Copy your **Client ID**
|
||||
2. Copy your **Client Secret**
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Airtable Connector
|
||||
|
||||
Add the Airtable credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
AIRTABLE_CLIENT_ID=your_airtable_client_id
|
||||
AIRTABLE_CLIENT_SECRET=your_airtable_client_secret
|
||||
AIRTABLE_REDIRECT_URI=http://localhost:8000/api/v1/auth/airtable/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
---
|
||||
title: ClickUp
|
||||
description: Connect your ClickUp workspace to SurfSense
|
||||
---
|
||||
|
||||
# ClickUp OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a ClickUp OAuth integration for SurfSense.
|
||||
|
||||
## Step 1: Access ClickUp API Settings
|
||||
|
||||
1. Open your ClickUp workspace
|
||||
2. Navigate to **Settings** (gear icon) → **ClickUp API**
|
||||
3. You'll see the **ClickUp API Settings** page
|
||||
|
||||
|
||||
|
||||
## Step 2: Create an App
|
||||
|
||||
1. Click **"+ Create an App"** in the top-right corner
|
||||
2. Fill in the app details:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **App Name** | `SurfSense` |
|
||||
| **Redirect URL(s)** | `localhost:8000` |
|
||||
|
||||
3. Click **"Save"** to create the app
|
||||
|
||||
|
||||
|
||||
## Step 3: Get OAuth Credentials
|
||||
|
||||
After creating the app, you'll see your credentials:
|
||||
|
||||
1. Copy your **Client ID**
|
||||
2. Copy your **Client Secret** (click "Show" to reveal, or "Regenerate" if needed)
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with ClickUp Connector
|
||||
|
||||
Add the ClickUp credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
CLICKUP_CLIENT_ID=your_clickup_client_id
|
||||
CLICKUP_CLIENT_SECRET=your_clickup_client_secret
|
||||
CLICKUP_REDIRECT_URI=http://localhost:8000/api/v1/auth/clickup/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
---
|
||||
title: Confluence
|
||||
description: Connect your Confluence spaces to SurfSense
|
||||
---
|
||||
|
||||
# Confluence OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration for SurfSense to connect your Confluence spaces.
|
||||
|
||||
## Step 1: Access the Developer Console
|
||||
|
||||
1. Navigate to [developer.atlassian.com](https://developer.atlassian.com)
|
||||
2. Click your profile icon in the top-right corner
|
||||
3. Select **"Developer console"** from the dropdown
|
||||
|
||||
|
||||
|
||||
## Step 2: Create a New OAuth 2.0 Integration
|
||||
|
||||
1. In the Developer Console, under **My apps**, click the **"Create"** button
|
||||
2. Select **"OAuth 2.0 integration"** from the dropdown
|
||||
|
||||
|
||||
|
||||
## Step 3: Name Your Integration
|
||||
|
||||
1. Enter **Name**: `SurfSense`
|
||||
2. Check the box to agree to Atlassian's developer terms
|
||||
3. Click **"Create"**
|
||||
|
||||
<Callout type="info">
|
||||
New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Step 4: Configure Callback URL
|
||||
|
||||
1. In the left sidebar, click **"Authorization"**
|
||||
2. Under **Callback URLs**, enter the redirect URI:
|
||||
```
|
||||
http://localhost:8000/api/v1/auth/confluence/connector/callback
|
||||
```
|
||||
3. Click **"Save changes"**
|
||||
|
||||
<Callout type="info">
|
||||
You can enter up to 10 redirect URIs, one per line.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Step 5: Configure API Permissions
|
||||
|
||||
1. In the left sidebar, click **"Permissions"**
|
||||
2. You'll see a list of available APIs including Confluence API
|
||||
|
||||
|
||||
|
||||
## Step 6: Configure Confluence API Scopes
|
||||
|
||||
1. Click **"Configure"** next to **Confluence API**
|
||||
|
||||
### Classic Scopes
|
||||
|
||||
Select the **"Classic scopes"** tab and enable:
|
||||
|
||||
| Scope Name | Code | Description |
|
||||
|------------|------|-------------|
|
||||
| Read user | `read:confluence-user` | View user information in Confluence that you have access to, including usernames, email addresses and profile pictures |
|
||||
|
||||
|
||||
|
||||
### Granular Scopes
|
||||
|
||||
Select the **"Granular scopes"** tab and enable:
|
||||
|
||||
| Scope Name | Code | Description |
|
||||
|------------|------|-------------|
|
||||
| View pages | `read:page:confluence` | View page content |
|
||||
| View comments | `read:comment:confluence` | View comments on pages or blogposts |
|
||||
| View spaces | `read:space:confluence` | View space details |
|
||||
| Write pages | `write:page:confluence` | Create and update page content |
|
||||
| Delete pages | `delete:page:confluence` | Delete pages |
|
||||
|
||||
4. Click **"Save"**
|
||||
|
||||
|
||||
|
||||
## Step 7: Get OAuth Credentials
|
||||
|
||||
1. In the left sidebar, click **"Settings"**
|
||||
2. Copy your **Client ID** and **Client Secret**
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Confluence Connector
|
||||
|
||||
Add the Atlassian credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
ATLASSIAN_CLIENT_ID=your_atlassian_client_id
|
||||
ATLASSIAN_CLIENT_SECRET=your_atlassian_client_secret
|
||||
CONFLUENCE_REDIRECT_URI=http://localhost:8000/api/v1/auth/confluence/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -5,6 +5,10 @@ description: Connect your Discord servers to SurfSense
|
|||
|
||||
# Discord OAuth Integration Setup Guide
|
||||
|
||||
<Callout type="warn" title="Deprecated">
|
||||
The Discord connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Existing connections remain manageable. The guide below is retained for reference only.
|
||||
</Callout>
|
||||
|
||||
This guide walks you through setting up a Discord OAuth integration for SurfSense.
|
||||
|
||||
## Step 1: Create a New Discord Application
|
||||
|
|
@ -64,7 +68,7 @@ You'll also see your **Application ID** and **Public Key** on this page.
|
|||
|
||||
## Running SurfSense with Discord Connector
|
||||
|
||||
Add the Discord credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
Add the Discord credentials to your `.env` file (created during [Docker installation](/docs/docker-installation)):
|
||||
|
||||
```bash
|
||||
DISCORD_CLIENT_ID=your_discord_client_id
|
||||
|
|
@ -5,6 +5,10 @@ description: Connect your Elasticsearch cluster to SurfSense
|
|||
|
||||
# Elasticsearch Integration Setup Guide
|
||||
|
||||
<Callout type="warn" title="Deprecated">
|
||||
The Elasticsearch connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Existing connections remain manageable. The guide below is retained for reference only.
|
||||
</Callout>
|
||||
|
||||
This guide walks you through connecting your Elasticsearch cluster to SurfSense.
|
||||
|
||||
## How it works
|
||||
|
|
@ -5,6 +5,10 @@ description: Connect your Luma events to SurfSense
|
|||
|
||||
# Luma Integration Setup Guide
|
||||
|
||||
<Callout type="warn" title="Deprecated">
|
||||
The Luma connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Existing connections remain manageable. The guide below is retained for reference only.
|
||||
</Callout>
|
||||
|
||||
This guide walks you through connecting your Luma events to SurfSense for event search and AI-powered insights.
|
||||
|
||||
## How it works
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"title": "Deprecated",
|
||||
"pages": ["discord", "microsoft-teams", "luma", "baidu-search", "elasticsearch", "web-crawler"],
|
||||
"defaultOpen": false
|
||||
}
|
||||
|
|
@ -7,8 +7,12 @@ description: Connect your Microsoft Teams to SurfSense
|
|||
|
||||
This guide walks you through setting up a Microsoft Teams OAuth integration for SurfSense using Azure App Registration.
|
||||
|
||||
<Callout type="warn" title="Deprecated">
|
||||
The Microsoft Teams connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Existing connections remain manageable. The guide below is retained for reference only.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info">
|
||||
Microsoft Teams and [Microsoft OneDrive](/docs/connectors/microsoft-onedrive) share the same Azure App Registration. If you have already created an app for OneDrive, you can reuse the same Client ID and Client Secret. Just make sure both redirect URIs are added (see Step 3).
|
||||
Microsoft Teams and [Microsoft OneDrive](/docs/connectors/external/onedrive) share the same Azure App Registration. If you have already created an app for OneDrive, you can reuse the same Client ID and Client Secret. Just make sure both redirect URIs are added (see Step 3).
|
||||
</Callout>
|
||||
|
||||
## Step 1: Access Azure App Registrations
|
||||
|
|
@ -101,7 +105,7 @@ After registration, you will be taken to the app's **Overview** page. Here you w
|
|||
|
||||
## Running SurfSense with Microsoft Teams Connector
|
||||
|
||||
Add the Microsoft OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
Add the Microsoft OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation)):
|
||||
|
||||
```bash
|
||||
MICROSOFT_CLIENT_ID=your_microsoft_client_id
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
title: Web Crawler
|
||||
description: The web crawler connector is deprecated
|
||||
---
|
||||
|
||||
# Web Crawler
|
||||
|
||||
<Callout type="warn" title="Deprecated">
|
||||
The web crawler connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Crawling is now built into the platform as the [Web Crawl native scraper](/docs/connectors/native/web-crawl). To save individual webpages, you can also use the [SurfSense browser extension](https://github.com/MODSetter/SurfSense/tree/main/surfsense_browser_extension), which captures pages behind authentication.
|
||||
</Callout>
|
||||
|
|
@ -1,79 +0,0 @@
|
|||
---
|
||||
title: Dropbox
|
||||
description: Connect your Dropbox to SurfSense
|
||||
---
|
||||
|
||||
# Dropbox OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a Dropbox OAuth integration for SurfSense using the Dropbox App Console.
|
||||
|
||||
## Step 1: Access the Dropbox App Console
|
||||
|
||||
1. Navigate to [dropbox.com/developers/apps](https://www.dropbox.com/developers/apps)
|
||||
2. Sign in with your Dropbox account
|
||||
|
||||
## Step 2: Create a New App
|
||||
|
||||
1. Click **"Create app"**
|
||||
2. Fill in the app details:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Choose an API** | Select **"Scoped access"** |
|
||||
| **Choose the type of access** | Select **"Full Dropbox"** |
|
||||
| **Name your app** | `SurfSense` (or any unique name) |
|
||||
|
||||
3. Click **"Create app"**
|
||||
|
||||
## Step 3: Configure Redirect URI
|
||||
|
||||
1. On your app's **Settings** page, scroll to the **OAuth 2** section
|
||||
2. Under **Redirect URIs**, add: `http://localhost:8000/api/v1/auth/dropbox/connector/callback`
|
||||
3. Click **"Add"**
|
||||
|
||||
## Step 4: Get App Key and Secret
|
||||
|
||||
On the same **Settings** page, you will find:
|
||||
|
||||
1. **App key** - this is your `DROPBOX_APP_KEY`
|
||||
2. **App secret** - click **"Show"** to reveal, then copy. This is your `DROPBOX_APP_SECRET`
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your app secret publicly or include it in code repositories.
|
||||
</Callout>
|
||||
|
||||
## Step 5: Configure Permissions
|
||||
|
||||
1. Go to the **Permissions** tab of your app
|
||||
2. Enable the following scopes:
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `files.metadata.read` | View information about files and folders |
|
||||
| `files.content.read` | View and download file content |
|
||||
| `files.content.write` | Create, modify, and delete files |
|
||||
| `account_info.read` | View basic account information |
|
||||
|
||||
3. Click **"Submit"** to save the permissions
|
||||
|
||||
<Callout type="warn">
|
||||
All four permissions listed above are required. The connector will not authenticate successfully if any are missing.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Dropbox Connector
|
||||
|
||||
Add the Dropbox OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
DROPBOX_APP_KEY=your_dropbox_app_key
|
||||
DROPBOX_APP_SECRET=your_dropbox_app_secret
|
||||
DROPBOX_REDIRECT_URI=http://localhost:8000/api/v1/auth/dropbox/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
69
surfsense_web/content/docs/connectors/external/airtable.mdx
vendored
Normal file
69
surfsense_web/content/docs/connectors/external/airtable.mdx
vendored
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
title: Airtable
|
||||
description: Let the SurfSense agent browse your Airtable bases, tables, and records
|
||||
---
|
||||
|
||||
The Airtable connector connects SurfSense to Airtable's hosted MCP server, giving the agent live tools to list your bases, browse tables, and read records. Nothing is indexed in the background.
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just click **Connect**.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Register an OAuth Integration
|
||||
|
||||
1. Navigate to [airtable.com/create/oauth](https://airtable.com/create/oauth)
|
||||
2. In the **Builder Hub**, under **Developers**, click **"OAuth integrations"**
|
||||
3. Click **"Register an OAuth integration"**
|
||||
|
||||
|
||||
|
||||
Fill in the details:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Name** | `SurfSense` |
|
||||
| **OAuth redirect URL** | `http://localhost:3929/api/v1/auth/mcp/airtable/connector/callback` |
|
||||
|
||||
<Callout type="info">
|
||||
`http://localhost:3929` is the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain.
|
||||
</Callout>
|
||||
|
||||
Click **"Register integration"**
|
||||
|
||||
|
||||
|
||||
## Step 2: Configure Scopes
|
||||
|
||||
Enable the scopes SurfSense requests:
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `data.records:read` | See the data in records |
|
||||
| `schema.bases:read` | See the structure of a base, like table names or field types |
|
||||
|
||||
|
||||
|
||||
## Step 3: Fill in Support Information
|
||||
|
||||
Add a support email (plus privacy policy and terms URLs if you have them) and click **"Save changes"**.
|
||||
|
||||
|
||||
|
||||
## Step 4: Add the Credentials to SurfSense
|
||||
|
||||
Copy the **Client ID** and **Client Secret** from the integration page and add them to your `.env` file:
|
||||
|
||||
```bash
|
||||
AIRTABLE_CLIENT_ID=your_airtable_client_id
|
||||
AIRTABLE_CLIENT_SECRET=your_airtable_client_secret
|
||||
```
|
||||
|
||||
Restart SurfSense, open the **Connectors** dialog, and click **Connect** on Airtable:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
|
@ -5,6 +5,10 @@ description: Connect your Bookstack instance to SurfSense
|
|||
|
||||
# BookStack Integration Setup Guide
|
||||
|
||||
<Callout type="warn" title="Indexing deprecated">
|
||||
The BookStack indexing pipeline is currently deprecated — the knowledge base now stores files, notes, and uploads only. Existing BookStack connectors remain manageable, but new indexing runs are refused by the backend.
|
||||
</Callout>
|
||||
|
||||
This guide walks you through connecting your BookStack instance to SurfSense.
|
||||
|
||||
## How it works
|
||||
71
surfsense_web/content/docs/connectors/external/dropbox.mdx
vendored
Normal file
71
surfsense_web/content/docs/connectors/external/dropbox.mdx
vendored
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
title: Dropbox
|
||||
description: Import your Dropbox files into the SurfSense knowledge base
|
||||
---
|
||||
|
||||
The Dropbox connector lets you pick files from Dropbox and index them into your knowledge base. It lives in the Documents sidebar's **Import** menu, not the connector catalog.
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just use **Import → Dropbox**.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Create a Dropbox App
|
||||
|
||||
1. Navigate to [dropbox.com/developers/apps](https://www.dropbox.com/developers/apps) and sign in
|
||||
2. Click **"Create app"** and fill in:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Choose an API** | **"Scoped access"** |
|
||||
| **Choose the type of access** | **"Full Dropbox"** |
|
||||
| **Name your app** | `SurfSense` (or any unique name) |
|
||||
|
||||
3. Click **"Create app"**
|
||||
|
||||
## Step 2: Configure the Redirect URI
|
||||
|
||||
1. On your app's **Settings** page, scroll to the **OAuth 2** section
|
||||
2. Under **Redirect URIs**, add:
|
||||
|
||||
```
|
||||
http://localhost:3929/api/v1/auth/dropbox/connector/callback
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
`http://localhost:3929` is the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain.
|
||||
</Callout>
|
||||
|
||||
## Step 3: Configure Permissions
|
||||
|
||||
1. Go to the **Permissions** tab of your app
|
||||
2. Enable all of the following scopes and click **"Submit"**:
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `files.metadata.read` | View information about files and folders |
|
||||
| `files.content.read` | View and download file content |
|
||||
| `files.content.write` | Create, modify, and delete files |
|
||||
| `account_info.read` | View basic account information |
|
||||
|
||||
<Callout type="warn">
|
||||
All four permissions are required. The connector will not authenticate successfully if any are missing.
|
||||
</Callout>
|
||||
|
||||
## Step 4: Add the Credentials to SurfSense
|
||||
|
||||
On the **Settings** page, copy the **App key** and **App secret** (click "Show" to reveal), and add them to your `.env` file:
|
||||
|
||||
```bash
|
||||
DROPBOX_APP_KEY=your_dropbox_app_key
|
||||
DROPBOX_APP_SECRET=your_dropbox_app_secret
|
||||
```
|
||||
|
||||
Restart SurfSense, open **Documents → Import → Dropbox**, and authorize:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your app secret publicly or include it in code repositories.
|
||||
</Callout>
|
||||
|
|
@ -5,6 +5,10 @@ description: Connect your GitHub repositories to SurfSense
|
|||
|
||||
# GitHub Integration Setup Guide
|
||||
|
||||
<Callout type="warn" title="Indexing deprecated">
|
||||
The GitHub indexing pipeline is currently deprecated — the knowledge base now stores files, notes, and uploads only. Existing GitHub connectors remain manageable, but new indexing runs are refused by the backend.
|
||||
</Callout>
|
||||
|
||||
This guide walks you through connecting your GitHub repositories to SurfSense for code search and AI-powered insights.
|
||||
|
||||
## How it works
|
||||
97
surfsense_web/content/docs/connectors/external/google.mdx
vendored
Normal file
97
surfsense_web/content/docs/connectors/external/google.mdx
vendored
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
---
|
||||
title: Google (Drive, Gmail, Calendar)
|
||||
description: Set up one Google OAuth app for the Drive, Gmail, and Calendar connectors
|
||||
---
|
||||
|
||||
One Google Cloud OAuth app powers Google login and all three Google connectors:
|
||||
|
||||
- **Google Drive** — import Drive files into your knowledge base via the Documents sidebar's **Import** menu
|
||||
- **Gmail** — the agent can search, read, draft, and send emails
|
||||
- **Google Calendar** — the agent can search and manage your events
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just click **Connect**.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info">
|
||||
The redirect URIs below use `http://localhost:3929` — the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Create a Google Cloud Project
|
||||
|
||||
1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Select an existing project or create a new one
|
||||
|
||||
## Step 2: Enable the APIs
|
||||
|
||||
1. Go to **APIs & Services** > **Library**
|
||||
2. Search for and enable:
|
||||
- **People API** (required for Google OAuth itself)
|
||||
- **Google Drive API** (for the Drive connector)
|
||||
- **Gmail API** (for the Gmail connector)
|
||||
- **Google Calendar API** (for the Calendar connector)
|
||||
|
||||
You only need to enable the APIs for the connectors you plan to use — the People API is always required.
|
||||
|
||||
|
||||
|
||||
## Step 3: Configure the OAuth Consent Screen
|
||||
|
||||
1. Go to **APIs & Services** > **OAuth consent screen**
|
||||
2. Select **External** user type (or Internal if using Google Workspace)
|
||||
3. Fill in the required information:
|
||||
- **App name**: `SurfSense`
|
||||
- **User support email**: Your email address
|
||||
- **Developer contact information**: Your email address
|
||||
4. Click **Save and Continue**
|
||||
|
||||
|
||||
|
||||
### Add Scopes
|
||||
|
||||
Click **Add or Remove Scopes** and add:
|
||||
|
||||
| Scope | Used by |
|
||||
|-------|---------|
|
||||
| `openid`, `.../auth/userinfo.email`, `.../auth/userinfo.profile` | All (basic OAuth) |
|
||||
| `https://www.googleapis.com/auth/drive` | Drive connector |
|
||||
| `https://www.googleapis.com/auth/gmail.modify` | Gmail connector |
|
||||
| `https://www.googleapis.com/auth/calendar.events` | Calendar connector |
|
||||
|
||||
<Callout type="info">
|
||||
The write-capable scopes (`drive`, `gmail.modify`, `calendar.events`) are what let the agent create files, send emails, and manage events — always with your confirmation in chat. If you only want read access, use `drive.readonly`, `gmail.readonly`, and `calendar.readonly` instead; the write tools then won't work.
|
||||
</Callout>
|
||||
|
||||
## Step 4: Create the OAuth Client
|
||||
|
||||
1. Go to **APIs & Services** > **Credentials**
|
||||
2. Click **Create Credentials** > **OAuth client ID**
|
||||
3. Select **Web application** as the application type
|
||||
4. Enter **Name**: `SurfSense`
|
||||
5. Under **Authorized redirect URIs**, add one URI per connector you plan to use:
|
||||
|
||||
```
|
||||
http://localhost:3929/api/v1/auth/google/drive/connector/callback
|
||||
http://localhost:3929/api/v1/auth/google/gmail/connector/callback
|
||||
http://localhost:3929/api/v1/auth/google/calendar/connector/callback
|
||||
```
|
||||
|
||||
6. Click **Create**
|
||||
|
||||
|
||||
|
||||
## Step 5: Add the Credentials to SurfSense
|
||||
|
||||
Copy the **Client ID** and **Client Secret** from the confirmation dialog, then add them to your `.env` file (see the Google section of `.env.example` for the exact variable names — the same client ID and secret are shared by Google login and all three connectors, plus one redirect URI variable per connector).
|
||||
|
||||
|
||||
|
||||
Restart SurfSense and the Google connectors are ready to connect:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
101
surfsense_web/content/docs/connectors/external/index.mdx
vendored
Normal file
101
surfsense_web/content/docs/connectors/external/index.mdx
vendored
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
title: External Connectors
|
||||
description: Connect third-party services like Notion, Slack, Google, GitHub, and Obsidian
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'fumadocs-ui/components/card';
|
||||
|
||||
External connectors link SurfSense to third-party services. Open the **Connectors** dialog in your workspace, pick a service, and connect — via OAuth, an API token, a webhook, or a companion plugin, depending on the service. You can connect multiple accounts of the same service.
|
||||
|
||||
Most of them act as **live tools for the AI agent** — when you chat, the agent can search your Notion pages, read Slack threads, or create Jira issues in real time. File sources (Google Drive, OneDrive, Dropbox) instead show up in the Documents sidebar's **Import** menu, where you pick files to index into your knowledge base.
|
||||
|
||||
## One-click connectors (no setup)
|
||||
|
||||
These work out of the box on every deployment — SurfSense connects to the service's hosted MCP server and the service issues credentials automatically. Just click **Connect**:
|
||||
|
||||
| Connector | What the agent can do |
|
||||
|-----------|----------------------|
|
||||
| **Notion** | Search, read, create, and update pages |
|
||||
| **Linear** | Search, read, and manage issues and projects |
|
||||
| **Jira** | Search issues with JQL, browse projects, create and edit issues |
|
||||
| **Confluence** | Search and read spaces, create and update pages |
|
||||
| **ClickUp** | Search and read tasks |
|
||||
|
||||
Write actions (creating a page, editing an issue) always ask for your confirmation in chat before they run.
|
||||
|
||||
## Connectors that need OAuth credentials (self-hosted)
|
||||
|
||||
For these, a self-hosted deployment needs its own OAuth app registered with the provider. Create the app once, put the credentials in your `.env` (each variable is documented in `.env.example`), restart, and the **Connect** button works for everyone on your instance:
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="Google (Drive, Gmail, Calendar)"
|
||||
description="One Google Cloud OAuth app powers all three connectors"
|
||||
href="/docs/connectors/external/google"
|
||||
/>
|
||||
<Card
|
||||
title="Slack"
|
||||
description="Search and read channels and threads"
|
||||
href="/docs/connectors/external/slack"
|
||||
/>
|
||||
<Card
|
||||
title="Airtable"
|
||||
description="Browse bases, tables, and records"
|
||||
href="/docs/connectors/external/airtable"
|
||||
/>
|
||||
<Card
|
||||
title="Microsoft OneDrive"
|
||||
description="Import your OneDrive files into the knowledge base"
|
||||
href="/docs/connectors/external/onedrive"
|
||||
/>
|
||||
<Card
|
||||
title="Dropbox"
|
||||
description="Import your Dropbox files into the knowledge base"
|
||||
href="/docs/connectors/external/dropbox"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
<Callout type="info">
|
||||
On SurfSense Cloud these are already configured — just click **Connect**. The setup guides above only apply to self-hosted deployments.
|
||||
</Callout>
|
||||
|
||||
## Token, webhook, and plugin connectors
|
||||
|
||||
These you configure yourself with an API token, a webhook, or a companion plugin:
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="GitHub"
|
||||
description="Index repositories into your knowledge base"
|
||||
href="/docs/connectors/external/github"
|
||||
/>
|
||||
<Card
|
||||
title="BookStack"
|
||||
description="Index your BookStack documentation"
|
||||
href="/docs/connectors/external/bookstack"
|
||||
/>
|
||||
<Card
|
||||
title="Circleback"
|
||||
description="Receive meeting notes and transcripts via webhook"
|
||||
href="/docs/connectors/external/circleback"
|
||||
/>
|
||||
<Card
|
||||
title="Obsidian"
|
||||
description="Sync your vault with the SurfSense Obsidian plugin"
|
||||
href="/docs/connectors/external/obsidian"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
There's also a generic **Custom MCP** connector in the catalog that lets you plug any MCP server into the agent — including API-key-based services like Tavily or Linkup.
|
||||
|
||||
## Importing files from Drive, OneDrive, and Dropbox
|
||||
|
||||
Google Drive, OneDrive, and Dropbox are file sources, so they don't appear in the connector catalog. Instead, open the **Documents** sidebar, click **Import**, and pick the service. After authorizing, browse and select the files you want — they're indexed into your knowledge base and kept searchable alongside your uploads and notes.
|
||||
|
||||
## Managing connections
|
||||
|
||||
Everything happens in the **Connectors** dialog:
|
||||
|
||||
- **Active** tab — see connected accounts, live status, and document counts.
|
||||
- **Reconnect** — if a token expires, the connector card prompts you to re-authorize.
|
||||
- **Disconnect** — removes the connection. For knowledge-base connectors this also removes the documents it indexed.
|
||||
15
surfsense_web/content/docs/connectors/external/meta.json
vendored
Normal file
15
surfsense_web/content/docs/connectors/external/meta.json
vendored
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
{
|
||||
"title": "External Connectors",
|
||||
"pages": [
|
||||
"google",
|
||||
"slack",
|
||||
"airtable",
|
||||
"onedrive",
|
||||
"dropbox",
|
||||
"github",
|
||||
"bookstack",
|
||||
"circleback",
|
||||
"obsidian"
|
||||
],
|
||||
"defaultOpen": false
|
||||
}
|
||||
78
surfsense_web/content/docs/connectors/external/onedrive.mdx
vendored
Normal file
78
surfsense_web/content/docs/connectors/external/onedrive.mdx
vendored
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
title: Microsoft OneDrive
|
||||
description: Import your OneDrive files into the SurfSense knowledge base
|
||||
---
|
||||
|
||||
The OneDrive connector lets you pick files from OneDrive and index them into your knowledge base. It lives in the Documents sidebar's **Import** menu, not the connector catalog.
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just use **Import → OneDrive**.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Create an Azure App Registration
|
||||
|
||||
1. Navigate to [portal.azure.com](https://portal.azure.com)
|
||||
2. Search for **"App registrations"** and open it
|
||||
3. Click **"+ New registration"** and fill in:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Name** | `SurfSense` |
|
||||
| **Supported account types** | **"Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts"** |
|
||||
| **Redirect URI** | Platform: `Web`, URI: `http://localhost:3929/api/v1/auth/onedrive/connector/callback` |
|
||||
|
||||
<Callout type="info">
|
||||
`http://localhost:3929` is the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain.
|
||||
</Callout>
|
||||
|
||||
4. Click **"Register"**
|
||||
|
||||
## Step 2: Get the Application (Client) ID
|
||||
|
||||
On the app's **Overview** page, copy the **Application (client) ID** — this is your Client ID.
|
||||
|
||||
## Step 3: Create a Client Secret
|
||||
|
||||
1. Under **Manage**, click **"Certificates & secrets"**
|
||||
2. On the **"Client secrets"** tab, click **"+ New client secret"**
|
||||
3. Enter a description (e.g., `SurfSense`) and pick an expiration period
|
||||
4. Click **"Add"**
|
||||
5. **Important**: Copy the secret **Value** immediately — it will not be shown again!
|
||||
|
||||
## Step 4: Configure API Permissions
|
||||
|
||||
1. Under **Manage**, click **"API permissions"** > **"+ Add a permission"**
|
||||
2. Select **"Microsoft Graph"** > **"Delegated permissions"**
|
||||
3. Add all of the following:
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `Files.Read.All` | Read all files the user can access |
|
||||
| `Files.ReadWrite.All` | Read and write all files the user can access |
|
||||
| `offline_access` | Maintain access to granted data |
|
||||
| `User.Read` | Sign in and read user profile |
|
||||
|
||||
4. Click **"Add permissions"**
|
||||
|
||||
<Callout type="warn">
|
||||
All four permissions are required. The connector will not authenticate successfully if any are missing.
|
||||
</Callout>
|
||||
|
||||
## Step 5: Add the Credentials to SurfSense
|
||||
|
||||
Add the credentials to your `.env` file:
|
||||
|
||||
```bash
|
||||
MICROSOFT_CLIENT_ID=your_microsoft_client_id
|
||||
MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret
|
||||
```
|
||||
|
||||
Restart SurfSense, open **Documents → Import → OneDrive**, and authorize:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly or include it in code repositories.
|
||||
</Callout>
|
||||
98
surfsense_web/content/docs/connectors/external/slack.mdx
vendored
Normal file
98
surfsense_web/content/docs/connectors/external/slack.mdx
vendored
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
---
|
||||
title: Slack
|
||||
description: Let the SurfSense agent search and read your Slack workspace
|
||||
---
|
||||
|
||||
The Slack connector connects SurfSense to Slack's hosted MCP server, giving the agent live tools to search channels and read threads on your behalf. Nothing is indexed in the background — the agent queries Slack in real time when you ask.
|
||||
|
||||
<Callout type="info">
|
||||
This setup is only needed on **self-hosted** deployments. On SurfSense Cloud, just click **Connect**.
|
||||
</Callout>
|
||||
|
||||
## Step 1: Create a New Slack App
|
||||
|
||||
1. Navigate to [api.slack.com/apps](https://api.slack.com/apps)
|
||||
2. Click **"Create New App"**
|
||||
3. Select **"From scratch"**
|
||||
|
||||
|
||||
|
||||
## Step 2: Name App & Choose Workspace
|
||||
|
||||
1. Enter **App Name**: `SurfSense`
|
||||
2. Select the workspace to develop your app in
|
||||
3. Click **"Create App"**
|
||||
|
||||
<Callout type="warn">
|
||||
You won't be able to change the workspace later. The workspace will control the app even if you leave it.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Step 3: Get App Credentials
|
||||
|
||||
On the **Basic Information** page:
|
||||
|
||||
1. Copy your **Client ID**
|
||||
2. Copy your **Client Secret** (click Show to reveal)
|
||||
|
||||
|
||||
|
||||
## Step 4: Configure the Redirect URL
|
||||
|
||||
1. In the left sidebar, click **"OAuth & Permissions"**
|
||||
2. Under **Redirect URLs**, click **"Add New Redirect URL"**
|
||||
3. Enter your SurfSense callback URL:
|
||||
|
||||
```
|
||||
http://localhost:3929/api/v1/auth/mcp/slack/connector/callback
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
`http://localhost:3929` is the default public URL of a Docker install. If you run SurfSense [manually](/docs/manual-installation), use your backend URL (`http://localhost:8000`); in production, use your public domain. Note that Slack requires HTTPS redirect URLs for production apps.
|
||||
</Callout>
|
||||
|
||||
4. Click **"Add"**, then **"Save URLs"**
|
||||
|
||||
|
||||
|
||||
## Step 5: Configure User Token Scopes
|
||||
|
||||
On the same **OAuth & Permissions** page, scroll to **Scopes**. The connector acts on behalf of the connecting user, so add these under **User Token Scopes**:
|
||||
|
||||
| OAuth Scope | Description |
|
||||
|-------------|-------------|
|
||||
| `search:read.public` | Search public channels |
|
||||
| `search:read.private` | Search private channels the user is in |
|
||||
| `search:read.mpim` | Search group direct messages |
|
||||
| `search:read.im` | Search direct messages |
|
||||
| `channels:history` | Read messages in public channels |
|
||||
| `groups:history` | Read messages in private channels |
|
||||
| `mpim:history` | Read group direct messages |
|
||||
| `im:history` | Read direct messages |
|
||||
|
||||
## Step 6: Enable Public Distribution
|
||||
|
||||
1. In the left sidebar, click **"Manage Distribution"**
|
||||
2. Under **Share Your App with Other Workspaces**, enable distribution so users can authorize the app in their own workspaces
|
||||
|
||||
|
||||
|
||||
## Step 7: Add the Credentials to SurfSense
|
||||
|
||||
Add the Client ID and Client Secret to your `.env` file:
|
||||
|
||||
```bash
|
||||
SLACK_CLIENT_ID=your_slack_client_id
|
||||
SLACK_CLIENT_SECRET=your_slack_client_secret
|
||||
```
|
||||
|
||||
Restart SurfSense, open the **Connectors** dialog, and click **Connect** on Slack:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your app credentials publicly.
|
||||
</Callout>
|
||||
|
|
@ -1,91 +0,0 @@
|
|||
---
|
||||
title: Gmail
|
||||
description: Connect your Gmail to SurfSense
|
||||
---
|
||||
|
||||
# Gmail OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a Google OAuth 2.0 integration for SurfSense to connect your Gmail account.
|
||||
|
||||
## Step 1: Access the Google Cloud Console
|
||||
|
||||
1. Navigate to [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Select an existing project or create a new one
|
||||
|
||||
## Step 2: Enable Required APIs
|
||||
|
||||
1. Go to **APIs & Services** > **Library**
|
||||
2. Search for and enable the following APIs:
|
||||
- **People API** (required for Google OAuth)
|
||||
- **Gmail API** (required for Gmail connector)
|
||||
|
||||
|
||||
|
||||
## Step 3: Configure OAuth Consent Screen
|
||||
|
||||
1. Go to **APIs & Services** > **OAuth consent screen**
|
||||
2. Select **External** user type (or Internal if using Google Workspace)
|
||||
3. Fill in the required information:
|
||||
- **App name**: `SurfSense`
|
||||
- **User support email**: Your email address
|
||||
- **Developer contact information**: Your email address
|
||||
4. Click **Save and Continue**
|
||||
|
||||
|
||||
|
||||
### Add Scopes
|
||||
|
||||
1. Click **Add or Remove Scopes**
|
||||
2. Add the following scopes:
|
||||
- `https://www.googleapis.com/auth/gmail.modify` - Read, compose, send, and permanently delete Gmail messages
|
||||
- `https://www.googleapis.com/auth/userinfo.email` - View user email address
|
||||
- `https://www.googleapis.com/auth/userinfo.profile` - View user profile info
|
||||
- `openid` - OpenID Connect authentication
|
||||
3. Click **Update** and then **Save and Continue**
|
||||
|
||||
<Callout type="info">
|
||||
The `gmail.modify` scope is required for HITL (Human-in-the-Loop) tools like sending emails, creating drafts, and trashing messages. If you only need read access, you can use `gmail.readonly` instead, but HITL tools will not work.
|
||||
</Callout>
|
||||
|
||||
## Step 4: Create OAuth Client ID
|
||||
|
||||
1. Go to **APIs & Services** > **Credentials**
|
||||
2. Click **Create Credentials** > **OAuth client ID**
|
||||
3. Select **Web application** as the application type
|
||||
4. Enter **Name**: `SurfSense`
|
||||
5. Under **Authorized redirect URIs**, add:
|
||||
```
|
||||
http://localhost:8000/api/v1/auth/google/gmail/connector/callback
|
||||
```
|
||||
6. Click **Create**
|
||||
|
||||
|
||||
|
||||
## Step 5: Get OAuth Credentials
|
||||
|
||||
1. After creating the OAuth client, you'll see a dialog with your credentials
|
||||
2. Copy your **Client ID** and **Client Secret**
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Gmail Connector
|
||||
|
||||
Add the Google OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
GOOGLE_OAUTH_CLIENT_ID=your_google_client_id
|
||||
GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret
|
||||
GOOGLE_GMAIL_REDIRECT_URI=http://localhost:8000/api/v1/auth/google/gmail/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -1,88 +0,0 @@
|
|||
---
|
||||
title: Google Calendar
|
||||
description: Connect your Google Calendar to SurfSense
|
||||
---
|
||||
|
||||
# Google Calendar OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a Google OAuth 2.0 integration for SurfSense to connect your Google Calendar.
|
||||
|
||||
## Step 1: Access the Google Cloud Console
|
||||
|
||||
1. Navigate to [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Select an existing project or create a new one
|
||||
|
||||
## Step 2: Enable Required APIs
|
||||
|
||||
1. Go to **APIs & Services** > **Library**
|
||||
2. Search for and enable the following APIs:
|
||||
- **People API** (required for Google OAuth)
|
||||
- **Google Calendar API** (required for Calendar connector)
|
||||
|
||||
|
||||
|
||||
## Step 3: Configure OAuth Consent Screen
|
||||
|
||||
1. Go to **APIs & Services** > **OAuth consent screen**
|
||||
2. Select **External** user type (or Internal if using Google Workspace)
|
||||
3. Fill in the required information:
|
||||
- **App name**: `SurfSense`
|
||||
- **User support email**: Your email address
|
||||
- **Developer contact information**: Your email address
|
||||
4. Click **Save and Continue**
|
||||
|
||||
|
||||
|
||||
### Add Scopes
|
||||
|
||||
1. Click **Add or Remove Scopes**
|
||||
2. Add the following scope:
|
||||
- `https://www.googleapis.com/auth/calendar.events` - Read, create, update, and delete Google Calendar events
|
||||
3. Click **Update** and then **Save and Continue**
|
||||
|
||||
<Callout type="info">
|
||||
The `calendar.events` scope is required for HITL (Human-in-the-Loop) tools like creating, updating, and deleting calendar events. If you only need read access, you can use `calendar.readonly` instead, but HITL tools will not work.
|
||||
</Callout>
|
||||
|
||||
## Step 4: Create OAuth Client ID
|
||||
|
||||
1. Go to **APIs & Services** > **Credentials**
|
||||
2. Click **Create Credentials** > **OAuth client ID**
|
||||
3. Select **Web application** as the application type
|
||||
4. Enter **Name**: `SurfSense`
|
||||
5. Under **Authorized redirect URIs**, add:
|
||||
```
|
||||
http://localhost:8000/api/v1/auth/google/calendar/connector/callback
|
||||
```
|
||||
6. Click **Create**
|
||||
|
||||
|
||||
|
||||
## Step 5: Get OAuth Credentials
|
||||
|
||||
1. After creating the OAuth client, you'll see a dialog with your credentials
|
||||
2. Copy your **Client ID** and **Client Secret**
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Google Calendar Connector
|
||||
|
||||
Add the Google OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
GOOGLE_OAUTH_CLIENT_ID=your_google_client_id
|
||||
GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret
|
||||
GOOGLE_CALENDAR_REDIRECT_URI=http://localhost:8000/api/v1/auth/google/calendar/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -1,91 +0,0 @@
|
|||
---
|
||||
title: Google Drive
|
||||
description: Connect your Google Drive to SurfSense
|
||||
---
|
||||
|
||||
# Google Drive OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a Google OAuth 2.0 integration for SurfSense to connect your Google Drive.
|
||||
|
||||
## Step 1: Access the Google Cloud Console
|
||||
|
||||
1. Navigate to [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Select an existing project or create a new one
|
||||
|
||||
## Step 2: Enable Required APIs
|
||||
|
||||
1. Go to **APIs & Services** > **Library**
|
||||
2. Search for and enable the following APIs:
|
||||
- **People API** (required for Google OAuth)
|
||||
- **Google Drive API** (required for Drive connector)
|
||||
|
||||
|
||||
|
||||
## Step 3: Configure OAuth Consent Screen
|
||||
|
||||
1. Go to **APIs & Services** > **OAuth consent screen**
|
||||
2. Select **External** user type (or Internal if using Google Workspace)
|
||||
3. Fill in the required information:
|
||||
- **App name**: `SurfSense`
|
||||
- **User support email**: Your email address
|
||||
- **Developer contact information**: Your email address
|
||||
4. Click **Save and Continue**
|
||||
|
||||
|
||||
|
||||
### Add Scopes
|
||||
|
||||
1. Click **Add or Remove Scopes**
|
||||
2. Add the following scopes:
|
||||
- `https://www.googleapis.com/auth/drive` - Full access to Google Drive (read, create, and trash files)
|
||||
- `https://www.googleapis.com/auth/userinfo.email` - View user email address
|
||||
- `https://www.googleapis.com/auth/userinfo.profile` - View user profile info
|
||||
- `openid` - OpenID Connect authentication
|
||||
3. Click **Update** and then **Save and Continue**
|
||||
|
||||
<Callout type="info">
|
||||
The `drive` scope is required for HITL (Human-in-the-Loop) tools like creating and trashing files. If you only need read access, you can use `drive.readonly` instead, but HITL tools will not work.
|
||||
</Callout>
|
||||
|
||||
## Step 4: Create OAuth Client ID
|
||||
|
||||
1. Go to **APIs & Services** > **Credentials**
|
||||
2. Click **Create Credentials** > **OAuth client ID**
|
||||
3. Select **Web application** as the application type
|
||||
4. Enter **Name**: `SurfSense`
|
||||
5. Under **Authorized redirect URIs**, add:
|
||||
```
|
||||
http://localhost:8000/api/v1/auth/google/drive/connector/callback
|
||||
```
|
||||
6. Click **Create**
|
||||
|
||||
|
||||
|
||||
## Step 5: Get OAuth Credentials
|
||||
|
||||
1. After creating the OAuth client, you'll see a dialog with your credentials
|
||||
2. Copy your **Client ID** and **Client Secret**
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Google Drive Connector
|
||||
|
||||
Add the Google OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
GOOGLE_OAUTH_CLIENT_ID=your_google_client_id
|
||||
GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret
|
||||
GOOGLE_DRIVE_REDIRECT_URI=http://localhost:8000/api/v1/auth/google/drive/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -1,121 +1,36 @@
|
|||
---
|
||||
title: Connectors
|
||||
description: Integrate with third-party services
|
||||
description: Connect SurfSense to your tools and services
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'fumadocs-ui/components/card';
|
||||
import { Zap, Cable } from 'lucide-react';
|
||||
|
||||
Connect SurfSense to your favorite tools and services. Browse the available integrations below to sync data from productivity apps, communication platforms, knowledge bases, and more.
|
||||
Connectors bring data into SurfSense — either as searchable knowledge or as live tools the AI agent can use during chat. There are two kinds:
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="Google Drive"
|
||||
description="Connect your Google Drive to SurfSense"
|
||||
href="/docs/connectors/google-drive"
|
||||
icon={<Zap />}
|
||||
title="Native Connectors"
|
||||
description="SurfSense's built-in scraper APIs: Reddit, YouTube, Google Maps, Google Search, and Web Crawl — usable in chat, the API Playground, or via REST"
|
||||
href="/docs/connectors/native"
|
||||
/>
|
||||
<Card
|
||||
title="Gmail"
|
||||
description="Connect your Gmail to SurfSense"
|
||||
href="/docs/connectors/gmail"
|
||||
/>
|
||||
<Card
|
||||
title="Google Calendar"
|
||||
description="Connect your Google Calendar to SurfSense"
|
||||
href="/docs/connectors/google-calendar"
|
||||
/>
|
||||
<Card
|
||||
title="Dropbox"
|
||||
description="Connect your Dropbox to SurfSense"
|
||||
href="/docs/connectors/dropbox"
|
||||
/>
|
||||
<Card
|
||||
title="Notion"
|
||||
description="Connect your Notion workspaces to SurfSense"
|
||||
href="/docs/connectors/notion"
|
||||
/>
|
||||
<Card
|
||||
title="Slack"
|
||||
description="Connect your Slack workspace to SurfSense"
|
||||
href="/docs/connectors/slack"
|
||||
/>
|
||||
<Card
|
||||
title="Discord"
|
||||
description="Connect your Discord servers to SurfSense"
|
||||
href="/docs/connectors/discord"
|
||||
/>
|
||||
<Card
|
||||
title="Jira"
|
||||
description="Connect your Jira projects to SurfSense"
|
||||
href="/docs/connectors/jira"
|
||||
/>
|
||||
<Card
|
||||
title="Linear"
|
||||
description="Connect your Linear workspace to SurfSense"
|
||||
href="/docs/connectors/linear"
|
||||
/>
|
||||
<Card
|
||||
title="Microsoft Teams"
|
||||
description="Connect your Microsoft Teams to SurfSense"
|
||||
href="/docs/connectors/microsoft-teams"
|
||||
/>
|
||||
<Card
|
||||
title="Microsoft OneDrive"
|
||||
description="Connect your Microsoft OneDrive to SurfSense"
|
||||
href="/docs/connectors/microsoft-onedrive"
|
||||
/>
|
||||
<Card
|
||||
title="Confluence"
|
||||
description="Connect your Confluence spaces to SurfSense"
|
||||
href="/docs/connectors/confluence"
|
||||
/>
|
||||
<Card
|
||||
title="Airtable"
|
||||
description="Connect your Airtable bases to SurfSense"
|
||||
href="/docs/connectors/airtable"
|
||||
/>
|
||||
<Card
|
||||
title="ClickUp"
|
||||
description="Connect your ClickUp workspace to SurfSense"
|
||||
href="/docs/connectors/clickup"
|
||||
/>
|
||||
<Card
|
||||
title="GitHub"
|
||||
description="Connect your GitHub repositories to SurfSense"
|
||||
href="/docs/connectors/github"
|
||||
/>
|
||||
<Card
|
||||
title="Baidu Search"
|
||||
description="Search the Chinese web with Baidu AI Search"
|
||||
href="/docs/connectors/baidu-search"
|
||||
/>
|
||||
<Card
|
||||
title="Luma"
|
||||
description="Connect your Luma events to SurfSense"
|
||||
href="/docs/connectors/luma"
|
||||
/>
|
||||
<Card
|
||||
title="Circleback"
|
||||
description="Connect your Circleback meetings to SurfSense"
|
||||
href="/docs/connectors/circleback"
|
||||
/>
|
||||
<Card
|
||||
title="Elasticsearch"
|
||||
description="Connect your Elasticsearch cluster to SurfSense"
|
||||
href="/docs/connectors/elasticsearch"
|
||||
/>
|
||||
<Card
|
||||
title="Bookstack"
|
||||
description="Connect your Bookstack instance to SurfSense"
|
||||
href="/docs/connectors/bookstack"
|
||||
/>
|
||||
<Card
|
||||
title="Obsidian"
|
||||
description="Sync your Obsidian vault using the SurfSense plugin"
|
||||
href="/docs/connectors/obsidian"
|
||||
/>
|
||||
<Card
|
||||
title="Web Crawler"
|
||||
description="Crawl and index any website into SurfSense"
|
||||
href="/docs/connectors/web-crawler"
|
||||
icon={<Cable />}
|
||||
title="External Connectors"
|
||||
description="Third-party integrations: Notion, Slack, Linear, Jira, Google, GitHub, Obsidian, and more"
|
||||
href="/docs/connectors/external"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
## How connectors surface in SurfSense
|
||||
|
||||
- **Native scrapers** — the AI agent uses them as tools automatically in chat, and you can run them yourself from the **API Playground** or your own code via the REST API.
|
||||
- **Tools & Live Sources** — external connectors like Notion, Slack, Jira, or Linear give the agent real-time tools. Ask a question in chat and the agent searches or acts on the connected service directly; nothing is copied into SurfSense in the background.
|
||||
- **Knowledge Base** — file sources like Google Drive, OneDrive, and Dropbox are imported through the Documents sidebar's **Import** menu and indexed into your knowledge base alongside uploads and notes.
|
||||
|
||||
To manage external connectors, open the **Connectors** dialog inside your workspace. Connected accounts, sync status, and disconnect options all live there.
|
||||
|
||||
## Deprecated connectors
|
||||
|
||||
Some older connectors (Discord, Microsoft Teams, Luma, Elasticsearch, the old web crawler, and standalone search APIs) have been retired. Existing connections remain manageable, but new ones can't be added. Their docs are kept for reference under [Deprecated](/docs/connectors/deprecated/discord). Public web search and crawling are now built in as [native scrapers](/docs/connectors/native), and other search APIs can still be wired up through a custom MCP server.
|
||||
|
|
|
|||
|
|
@ -1,100 +0,0 @@
|
|||
---
|
||||
title: Jira
|
||||
description: Connect your Jira projects to SurfSense
|
||||
---
|
||||
|
||||
# Jira OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration for SurfSense to connect your Jira projects.
|
||||
|
||||
## Step 1: Access the Developer Console
|
||||
|
||||
1. Navigate to [developer.atlassian.com](https://developer.atlassian.com)
|
||||
2. Click your profile icon in the top-right corner
|
||||
3. Select **"Developer console"** from the dropdown
|
||||
|
||||
|
||||
|
||||
## Step 2: Create a New OAuth 2.0 Integration
|
||||
|
||||
1. In the Developer Console, under **My apps**, click the **"Create"** button
|
||||
2. Select **"OAuth 2.0 integration"** from the dropdown
|
||||
|
||||
|
||||
|
||||
## Step 3: Name Your Integration
|
||||
|
||||
1. Enter **Name**: `SurfSense`
|
||||
2. Check the box to agree to Atlassian's developer terms
|
||||
3. Click **"Create"**
|
||||
|
||||
<Callout type="info">
|
||||
New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Step 4: Configure Callback URL
|
||||
|
||||
1. In the left sidebar, click **"Authorization"**
|
||||
2. Under **Callback URLs**, enter the redirect URI:
|
||||
```
|
||||
http://localhost:8000/api/v1/auth/jira/connector/callback
|
||||
```
|
||||
3. Click **"Save changes"**
|
||||
|
||||
<Callout type="info">
|
||||
You can enter up to 10 redirect URIs, one per line.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Step 5: Configure API Permissions
|
||||
|
||||
1. In the left sidebar, click **"Permissions"**
|
||||
2. You'll see a list of available APIs including Jira API
|
||||
|
||||
|
||||
|
||||
## Step 6: Configure Jira API Scopes
|
||||
|
||||
1. Click **"Configure"** next to **Jira API**
|
||||
2. Select the **"Classic scopes"** tab
|
||||
3. Under **Jira platform REST API**, select the following scopes:
|
||||
|
||||
| Scope Name | Code | Description |
|
||||
|------------|------|-------------|
|
||||
| View Jira issue data | `read:jira-work` | Read Jira project and issue data, search for issues, and objects associated with issues like attachments and worklogs |
|
||||
| View user profiles | `read:jira-user` | View user information in Jira that the user has access to, including usernames, email addresses, and avatars |
|
||||
| Create and manage issues | `write:jira-work` | Create, edit, and delete issues, comments, worklogs, and other Jira data the user has access to |
|
||||
|
||||
4. Click **"Save"**
|
||||
|
||||
|
||||
|
||||
## Step 7: Get OAuth Credentials
|
||||
|
||||
1. In the left sidebar, click **"Settings"**
|
||||
2. Copy your **Client ID** and **Client Secret**
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Jira Connector
|
||||
|
||||
Add the Atlassian credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
ATLASSIAN_CLIENT_ID=your_atlassian_client_id
|
||||
ATLASSIAN_CLIENT_SECRET=your_atlassian_client_secret
|
||||
JIRA_REDIRECT_URI=http://localhost:8000/api/v1/auth/jira/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
---
|
||||
title: Linear
|
||||
description: Connect your Linear workspace to SurfSense
|
||||
---
|
||||
|
||||
# Linear OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a Linear OAuth integration for SurfSense.
|
||||
|
||||
## Step 1: Access Linear API Settings
|
||||
|
||||
1. Navigate to your workspace's API settings at `linear.app/<your-workspace>/settings/api`
|
||||
2. Under **OAuth Applications**, click **"+ New OAuth application"**
|
||||
|
||||
|
||||
|
||||
## Step 2: Create New Application
|
||||
|
||||
Fill in the application details:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Application icon** | Upload an icon (at least 256x256px) |
|
||||
| **Application name** | `SurfSense` |
|
||||
| **Developer name** | `SurfSense` |
|
||||
| **Developer URL** | `https://www.surfsense.com/` |
|
||||
| **Description** | Connect any LLM to your internal knowledge sources and chat with it in real time alongside your team. |
|
||||
| **Callback URLs** | `http://localhost:8000/api/v1/auth/linear/connector/callback` |
|
||||
| **GitHub username** | Your GitHub username (optional) |
|
||||
|
||||
### Settings
|
||||
|
||||
- **Public** - Enable this to allow the application to be installed by other workspaces
|
||||
|
||||
Click **Create** to create the application.
|
||||
|
||||
|
||||
|
||||
## Step 3: Get OAuth Credentials
|
||||
|
||||
After creating the application, you'll see your OAuth credentials:
|
||||
|
||||
1. Copy your **Client ID**
|
||||
2. Copy your **Client Secret**
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Linear Connector
|
||||
|
||||
Add the Linear credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
LINEAR_CLIENT_ID=your_linear_client_id
|
||||
LINEAR_CLIENT_SECRET=your_linear_client_secret
|
||||
LINEAR_REDIRECT_URI=http://localhost:8000/api/v1/auth/linear/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
|
|
@ -1,28 +1,6 @@
|
|||
{
|
||||
"title": "Connectors",
|
||||
"icon": "Unplug",
|
||||
"pages": [
|
||||
"google-drive",
|
||||
"gmail",
|
||||
"google-calendar",
|
||||
"dropbox",
|
||||
"notion",
|
||||
"slack",
|
||||
"discord",
|
||||
"jira",
|
||||
"linear",
|
||||
"microsoft-teams",
|
||||
"microsoft-onedrive",
|
||||
"confluence",
|
||||
"airtable",
|
||||
"clickup",
|
||||
"github",
|
||||
"baidu-search",
|
||||
"luma",
|
||||
"circleback",
|
||||
"elasticsearch",
|
||||
"bookstack",
|
||||
"obsidian"
|
||||
],
|
||||
"pages": ["native", "external", "deprecated"],
|
||||
"defaultOpen": false
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,104 +0,0 @@
|
|||
---
|
||||
title: Microsoft OneDrive
|
||||
description: Connect your Microsoft OneDrive to SurfSense
|
||||
---
|
||||
|
||||
# Microsoft OneDrive OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a Microsoft OneDrive OAuth integration for SurfSense using Azure App Registration.
|
||||
|
||||
<Callout type="info">
|
||||
Microsoft OneDrive and [Microsoft Teams](/docs/connectors/microsoft-teams) share the same Azure App Registration. If you have already created an app for Teams, you can reuse the same Client ID and Client Secret. Just make sure both redirect URIs are added (see Step 3).
|
||||
</Callout>
|
||||
|
||||
## Step 1: Access Azure App Registrations
|
||||
|
||||
1. Navigate to [portal.azure.com](https://portal.azure.com)
|
||||
2. In the search bar, type **"app reg"**
|
||||
3. Select **"App registrations"** from the Services results
|
||||
|
||||
## Step 2: Create New Registration
|
||||
|
||||
1. On the **App registrations** page, click **"+ New registration"**
|
||||
|
||||
## Step 3: Register the Application
|
||||
|
||||
Fill in the application details:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Name** | `SurfSense` |
|
||||
| **Supported account types** | Select **"Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts"** |
|
||||
| **Redirect URI** | Platform: `Web`, URI: `http://localhost:8000/api/v1/auth/onedrive/connector/callback` |
|
||||
|
||||
Click **"Register"**
|
||||
|
||||
After registration, add the Teams redirect URI as well (if you plan to use the Teams connector):
|
||||
|
||||
1. Go to **Authentication** in the left sidebar
|
||||
2. Under **Platform configurations** > **Web** > **Redirect URIs**, click **Add URI**
|
||||
3. Add: `http://localhost:8000/api/v1/auth/teams/connector/callback`
|
||||
4. Click **Save**
|
||||
|
||||
## Step 4: Get Application (Client) ID
|
||||
|
||||
After registration, you will be taken to the app's **Overview** page. Here you will find:
|
||||
|
||||
1. Copy the **Application (client) ID** - this is your Client ID
|
||||
2. Note the **Directory (tenant) ID** if needed
|
||||
|
||||
## Step 5: Create Client Secret
|
||||
|
||||
1. In the left sidebar under **Manage**, click **"Certificates & secrets"**
|
||||
2. Select the **"Client secrets"** tab
|
||||
3. Click **"+ New client secret"**
|
||||
4. Enter a description (e.g., `SurfSense`) and select an expiration period
|
||||
5. Click **"Add"**
|
||||
6. **Important**: Copy the secret **Value** immediately. It will not be shown again!
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly or include it in code repositories.
|
||||
</Callout>
|
||||
|
||||
## Step 6: Configure API Permissions
|
||||
|
||||
1. In the left sidebar under **Manage**, click **"API permissions"**
|
||||
2. Click **"+ Add a permission"**
|
||||
3. Select **"Microsoft Graph"**
|
||||
4. Select **"Delegated permissions"**
|
||||
5. Add the following permissions:
|
||||
|
||||
| Permission | Type | Description | Admin Consent |
|
||||
|------------|------|-------------|---------------|
|
||||
| `Files.Read.All` | Delegated | Read all files the user can access | No |
|
||||
| `Files.ReadWrite.All` | Delegated | Read and write all files the user can access | No |
|
||||
| `offline_access` | Delegated | Maintain access to data you have given it access to | No |
|
||||
| `User.Read` | Delegated | Sign in and read user profile | No |
|
||||
|
||||
6. Click **"Add permissions"**
|
||||
|
||||
<Callout type="warn">
|
||||
All four permissions listed above are required. The connector will not authenticate successfully if any are missing.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Microsoft OneDrive Connector
|
||||
|
||||
Add the Microsoft OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
MICROSOFT_CLIENT_ID=your_microsoft_client_id
|
||||
MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret
|
||||
ONEDRIVE_REDIRECT_URI=http://localhost:8000/api/v1/auth/onedrive/connector/callback
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
The `MICROSOFT_CLIENT_ID` and `MICROSOFT_CLIENT_SECRET` are shared between the OneDrive and Teams connectors. You only need to set them once.
|
||||
</Callout>
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
64
surfsense_web/content/docs/connectors/native/google-maps.mdx
Normal file
64
surfsense_web/content/docs/connectors/native/google-maps.mdx
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
---
|
||||
title: Google Maps
|
||||
description: Scrape public Google Maps places and reviews
|
||||
---
|
||||
|
||||
The Google Maps scraper has two verbs: **scrape** for place data and **reviews** for a place's review feed.
|
||||
|
||||
## Scrape places
|
||||
|
||||
```bash
|
||||
POST /api/v1/workspaces/{workspace_id}/scrapers/google_maps/scrape
|
||||
```
|
||||
|
||||
Give it search queries (optionally scoped by location), Google Maps URLs, or place IDs. Returns structured place items — name, address, category, phone, website, rating, review count, coordinates, and opening hours.
|
||||
|
||||
At least one of `search_queries`, `urls`, or `place_ids` is required.
|
||||
|
||||
| Field | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `search_queries` | — | Search terms, e.g. `"coffee shops"` (max 20 sources per call, combined with URLs and place IDs) |
|
||||
| `urls` | — | Place page (`/maps/place/...`) or search-results URLs |
|
||||
| `place_ids` | — | Known Google place IDs (`ChIJ...`) |
|
||||
| `location` | — | Scope for search queries, e.g. `"New York, USA"` |
|
||||
| `max_places` | `10` | Max places per search query (max 1000) |
|
||||
| `include_details` | `false` | Also fetch each place's detail page: opening hours, popular times, extra contact info (slower) |
|
||||
| `max_reviews` | `0` | Reviews to attach per place |
|
||||
| `max_images` | `0` | Images to attach per place |
|
||||
| `language` | `en` | Result language code |
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/google_maps/scrape" \
|
||||
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"search_queries": ["specialty coffee"],
|
||||
"location": "Amsterdam, Netherlands",
|
||||
"max_places": 20,
|
||||
"include_details": true
|
||||
}'
|
||||
```
|
||||
|
||||
This verb is dual-metered: billed per returned place, plus per attached review when `max_reviews > 0`.
|
||||
|
||||
## Fetch reviews
|
||||
|
||||
```bash
|
||||
POST /api/v1/workspaces/{workspace_id}/scrapers/google_maps/reviews
|
||||
```
|
||||
|
||||
Give it place URLs or place IDs; returns review items with author, text, star rating, like count, owner response, and timestamps.
|
||||
|
||||
At least one of `urls` or `place_ids` is required.
|
||||
|
||||
| Field | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `urls` / `place_ids` | — | Up to 20 places per call |
|
||||
| `max_reviews` | `20` | Max reviews per place (max 100,000) |
|
||||
| `sort_by` | `newest` | `newest`, `mostRelevant`, `highestRanking`, or `lowestRanking` |
|
||||
| `start_date` | — | Only reviews on/after this ISO date |
|
||||
| `language` | `en` | Review language code |
|
||||
|
||||
Billing is per returned review.
|
||||
|
||||
For the full input and output JSON schemas and generated code snippets in your language, open **API Playground → Google Maps** in your workspace.
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
title: Google Search
|
||||
description: Search Google and get structured SERP results
|
||||
---
|
||||
|
||||
The Google Search scraper runs searches and returns structured SERP data: organic results (title, URL, description), related queries, people-also-ask questions, and any AI overview.
|
||||
|
||||
## Endpoint
|
||||
|
||||
```bash
|
||||
POST /api/v1/workspaces/{workspace_id}/scrapers/google_search/scrape
|
||||
```
|
||||
|
||||
## Inputs
|
||||
|
||||
| Field | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `queries` | required | 1–20 search terms or full Google Search URLs — terms are searched, URLs are scraped as-is |
|
||||
| `max_pages_per_query` | `1` | Result pages to fetch per query (max 10) |
|
||||
| `country_code` | — | Two-letter country to search from, e.g. `us`, `fr` |
|
||||
| `language_code` | — | Result language code (blank = Google default) |
|
||||
| `site` | — | Restrict results to a single domain, e.g. `example.com` |
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/google_search/scrape" \
|
||||
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"queries": ["open source notebooklm alternative"],
|
||||
"max_pages_per_query": 2,
|
||||
"country_code": "us"
|
||||
}'
|
||||
```
|
||||
|
||||
The response is `{ "items": [...] }` — one item per fetched SERP page. Billing is per SERP page.
|
||||
|
||||
For the full input and output JSON schemas and generated code snippets in your language, open **API Playground → Google Search → Scrape** in your workspace.
|
||||
91
surfsense_web/content/docs/connectors/native/index.mdx
Normal file
91
surfsense_web/content/docs/connectors/native/index.mdx
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
title: Native Connectors
|
||||
description: SurfSense's built-in scraper APIs for Reddit, YouTube, Google Maps, Google Search, and the web
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'fumadocs-ui/components/card';
|
||||
|
||||
Native connectors are SurfSense's own scraper APIs — built into the platform, no third-party account or OAuth app required. They pull structured, public data from the platforms below and return clean JSON.
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="Reddit"
|
||||
description="Posts, comments, subreddits, and users — by URL or search"
|
||||
href="/docs/connectors/native/reddit"
|
||||
/>
|
||||
<Card
|
||||
title="YouTube"
|
||||
description="Videos, channels, playlists, subtitles, and comments"
|
||||
href="/docs/connectors/native/youtube"
|
||||
/>
|
||||
<Card
|
||||
title="Google Maps"
|
||||
description="Places with details, ratings, photos, and reviews"
|
||||
href="/docs/connectors/native/google-maps"
|
||||
/>
|
||||
<Card
|
||||
title="Google Search"
|
||||
description="Structured SERPs: organic results, people-also-ask, AI overviews"
|
||||
href="/docs/connectors/native/google-search"
|
||||
/>
|
||||
<Card
|
||||
title="Web Crawl"
|
||||
description="Scrape any page or spider a whole site into clean markdown"
|
||||
href="/docs/connectors/native/web-crawl"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
## Three ways to use them
|
||||
|
||||
Every scraper is available through the same three doors:
|
||||
|
||||
1. **In chat** — the AI agent uses these scrapers as tools automatically. Ask "what is r/selfhosted saying about SurfSense?" and the agent runs the Reddit scraper for you.
|
||||
2. **API Playground** — open **API Playground** in your workspace sidebar, pick a scraper, fill in the form, and run it interactively. Great for exploring what a scraper returns before writing code.
|
||||
3. **REST API** — call the scrapers from your own code. Each one is a single `POST`:
|
||||
|
||||
```bash
|
||||
POST /api/v1/workspaces/{workspace_id}/scrapers/{platform}/{verb}
|
||||
Authorization: Bearer <your-api-key>
|
||||
```
|
||||
|
||||
The playground's **API reference** section on every scraper page generates ready-to-paste snippets (cURL, Python, JavaScript, Go, and more) with your workspace ID already filled in, plus the full input and output JSON schemas.
|
||||
|
||||
## API keys
|
||||
|
||||
To call the REST API you need two things, both under **API Playground → API Keys**:
|
||||
|
||||
1. Toggle **API key access** on for the workspace.
|
||||
2. Create a personal API key and send it as an `Authorization: Bearer` header.
|
||||
|
||||
## Sync and async runs
|
||||
|
||||
By default a `POST` blocks until the scrape finishes and returns the results. For long scrapes, append `?mode=async` — you get a `202` with a `run_id` immediately, then:
|
||||
|
||||
- **Stream progress**: `GET .../scrapers/runs/{run_id}/events` (Server-Sent Events, ends with a `run.finished` event)
|
||||
- **Fetch the result**: `GET .../scrapers/runs/{run_id}`
|
||||
- **Cancel**: `POST .../scrapers/runs/{run_id}/cancel`
|
||||
|
||||
## Avoiding blocks with a proxy (self-hosted)
|
||||
|
||||
Scrapers make real requests to the target platforms, and heavy use from a single server IP will eventually get rate-limited or blocked. If you self-host, we recommend routing scraper traffic through a proxy — any HTTP proxy or rotating residential/datacenter gateway you already use works; SurfSense doesn't require a specific vendor.
|
||||
|
||||
Set it up in your backend `.env` and restart:
|
||||
|
||||
```bash
|
||||
# A single endpoint (user:pass@host:port), used for all scraper traffic
|
||||
PROXY_URL=http://username:password@proxy.example.com:8080
|
||||
|
||||
# Or a comma-separated pool that SurfSense rotates through per request.
|
||||
# Gateways that rotate server-side just need the single PROXY_URL above.
|
||||
PROXY_URLS=http://user:pass@host1:port,http://user:pass@host2:port
|
||||
```
|
||||
|
||||
Leave both unset and requests go out directly from your server's IP — fine for light use. See the proxy section of `.env.example` for the full details, including `PROXY_PROVIDER` if your vendor has a built-in integration.
|
||||
|
||||
<Callout type="info">
|
||||
On SurfSense Cloud, proxying is already handled — nothing to configure.
|
||||
</Callout>
|
||||
|
||||
## Runs and pricing
|
||||
|
||||
Every run — from chat, the playground, or the API — is recorded under **API Playground → Runs** with its input, output, duration, and cost. Scrapers are metered per item returned (per post, video, comment, place, review, SERP page, or crawled page); the current rate is shown on each scraper's playground card, and pricing is returned by the capabilities API (`GET .../scrapers/capabilities`).
|
||||
5
surfsense_web/content/docs/connectors/native/meta.json
Normal file
5
surfsense_web/content/docs/connectors/native/meta.json
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"title": "Native Connectors",
|
||||
"pages": ["reddit", "youtube", "google-maps", "google-search", "web-crawl"],
|
||||
"defaultOpen": false
|
||||
}
|
||||
49
surfsense_web/content/docs/connectors/native/reddit.mdx
Normal file
49
surfsense_web/content/docs/connectors/native/reddit.mdx
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: Reddit
|
||||
description: Scrape public Reddit posts, comments, subreddits, and users
|
||||
---
|
||||
|
||||
The Reddit scraper pulls structured public data from Reddit. Give it URLs (a post, a subreddit, a user page, or a search URL) and/or search terms, and it returns posts (title, body, score, comment count, subreddit, author), their comment trees, and community/user metadata.
|
||||
|
||||
## Endpoint
|
||||
|
||||
```bash
|
||||
POST /api/v1/workspaces/{workspace_id}/scrapers/reddit/scrape
|
||||
```
|
||||
|
||||
## Inputs
|
||||
|
||||
At least one of `urls`, `search_queries`, or `community` is required.
|
||||
|
||||
| Field | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `urls` | — | Reddit URLs: a post, `/r/<subreddit>`, `/user/<name>`, or a search URL (max 20 sources per call, combined with queries) |
|
||||
| `search_queries` | — | Search terms to run on Reddit |
|
||||
| `community` | — | Subreddit name (without `r/`) to scope searches to; with no queries, its listing is scraped |
|
||||
| `sort` | `new` | `relevance`, `hot`, `top`, `new`, `rising`, or `comments` |
|
||||
| `time_filter` | — | Window for `top`/`controversial`: `hour`, `day`, `week`, `month`, `year`, `all` |
|
||||
| `max_items` | `10` | Max total items returned across all sources (hard cap 100) |
|
||||
| `max_posts` | `10` | Max posts per subreddit/user/search target |
|
||||
| `max_comments` | `10` | Max comments per post (`0` = none) |
|
||||
| `skip_comments` | `false` | Skip comment trees entirely (faster) |
|
||||
| `include_nsfw` | `true` | Include over-18 posts |
|
||||
| `post_date_limit` / `comment_date_limit` | — | ISO dates for incremental scrapes: only return newer content |
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/reddit/scrape" \
|
||||
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"search_queries": ["self-hosted AI research agent"],
|
||||
"community": "selfhosted",
|
||||
"sort": "top",
|
||||
"time_filter": "month",
|
||||
"max_items": 25
|
||||
}'
|
||||
```
|
||||
|
||||
The response is `{ "items": [...] }` — one item per post, comment, community, or user. Billing is per returned item.
|
||||
|
||||
For the full input and output JSON schemas and generated code snippets in your language, open **API Playground → Reddit → Scrape** in your workspace.
|
||||
58
surfsense_web/content/docs/connectors/native/web-crawl.mdx
Normal file
58
surfsense_web/content/docs/connectors/native/web-crawl.mdx
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
title: Web Crawl
|
||||
description: Scrape any page or crawl a whole site into clean markdown
|
||||
---
|
||||
|
||||
The web crawler fetches one or more pages — or spiders a whole site — and returns each page as clean markdown, plus metadata, every link with its anchor text, and harvested contact signals (emails, phone numbers, social profiles). JS-rendered pages are loaded in a real browser and auto-scrolled, so lazy-loaded listings are captured too.
|
||||
|
||||
## Endpoint
|
||||
|
||||
```bash
|
||||
POST /api/v1/workspaces/{workspace_id}/scrapers/web/crawl
|
||||
```
|
||||
|
||||
## Inputs
|
||||
|
||||
| Field | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `startUrls` | required | 1–20 seed URLs |
|
||||
| `maxCrawlDepth` | `0` | Link-hops to follow from each seed. `0` = fetch only the seeds; `1` = also the pages they link to; up to 5. The spider stays on the seed's site |
|
||||
| `maxCrawlPages` | `10` | Total pages fetched per call, seeds included (max 200) |
|
||||
| `maxLength` | `50000` | Max characters of markdown kept per page |
|
||||
| `includeUrlPatterns` | — | Regexes a discovered link must match to be followed (empty = follow every same-site link) |
|
||||
| `excludeUrlPatterns` | — | Regexes that exclude links from being followed (wins over include) |
|
||||
|
||||
## Example
|
||||
|
||||
Scrape a single page:
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/web/crawl" \
|
||||
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{ "startUrls": ["https://example.com/pricing"] }'
|
||||
```
|
||||
|
||||
Crawl a site's blog, two hops deep:
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/web/crawl" \
|
||||
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"startUrls": ["https://example.com/blog"],
|
||||
"maxCrawlDepth": 2,
|
||||
"maxCrawlPages": 50,
|
||||
"includeUrlPatterns": ["/blog/"]
|
||||
}'
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
One item per fetched page (in crawl order) with its markdown, metadata (title, description), crawl provenance (depth, referrer), links classified as internal/external/social/email/tel, and page-level contacts. The response also includes a site-wide `contacts` summary that deduplicates every email, phone, and social profile found — `siteWide: true` marks header/footer values (the company's own contacts) versus page-local finds like individual team members.
|
||||
|
||||
Contact details often live on about/contact/privacy pages, so crawl with `maxCrawlDepth >= 1` to surface them — useful for lead generation and competitive intelligence.
|
||||
|
||||
Billing is per successfully fetched page.
|
||||
|
||||
For the full input and output JSON schemas and generated code snippets in your language, open **API Playground → Web → Crawl** in your workspace.
|
||||
54
surfsense_web/content/docs/connectors/native/youtube.mdx
Normal file
54
surfsense_web/content/docs/connectors/native/youtube.mdx
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: YouTube
|
||||
description: Scrape public YouTube videos, channels, playlists, and comments
|
||||
---
|
||||
|
||||
The YouTube scraper has two verbs: **scrape** for video metadata (and optionally subtitles) and **comments** for a video's comment threads.
|
||||
|
||||
## Scrape videos
|
||||
|
||||
```bash
|
||||
POST /api/v1/workspaces/{workspace_id}/scrapers/youtube/scrape
|
||||
```
|
||||
|
||||
Give it YouTube URLs (video, channel `/@handle`, playlist, shorts, or hashtag pages) and/or search queries. Returns structured video items — title, views, likes, publish date, channel info, description, and optionally subtitles.
|
||||
|
||||
At least one of `urls` or `search_queries` is required.
|
||||
|
||||
| Field | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `urls` | — | Video, channel, playlist, shorts, or hashtag URLs (max 20 sources per call, combined with queries) |
|
||||
| `search_queries` | — | Search terms; each returns up to `max_results` videos |
|
||||
| `max_results` | `10` | Max items per source and per content type (a channel's videos, shorts, and streams are capped independently; max 1000) |
|
||||
| `download_subtitles` | `false` | Also fetch each video's subtitle track (slower) |
|
||||
| `subtitles_language` | `en` | Subtitle language code |
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/youtube/scrape" \
|
||||
-H "Authorization: Bearer $SURFSENSE_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"urls": ["https://www.youtube.com/@surfsense"],
|
||||
"max_results": 20
|
||||
}'
|
||||
```
|
||||
|
||||
Billing is per returned video/short/stream.
|
||||
|
||||
## Fetch comments
|
||||
|
||||
```bash
|
||||
POST /api/v1/workspaces/{workspace_id}/scrapers/youtube/comments
|
||||
```
|
||||
|
||||
Give it video URLs; returns comment items with author, text, like count, reply relationships, and timestamps — useful for gauging sentiment on specific videos.
|
||||
|
||||
| Field | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `urls` | required | 1–20 video URLs |
|
||||
| `max_comments` | `20` | Max items per video, counting top-level comments and replies (max 100,000) |
|
||||
| `sort_by` | `NEWEST_FIRST` | `TOP_COMMENTS` or `NEWEST_FIRST` |
|
||||
|
||||
Billing is per returned comment or reply.
|
||||
|
||||
For the full input and output JSON schemas and generated code snippets in your language, open **API Playground → YouTube** in your workspace.
|
||||
|
|
@ -1,106 +0,0 @@
|
|||
---
|
||||
title: Notion
|
||||
description: Connect your Notion workspaces to SurfSense
|
||||
---
|
||||
|
||||
# Notion OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a Notion OAuth integration for SurfSense.
|
||||
|
||||
## Step 1: Access Notion Integrations
|
||||
|
||||
1. Navigate to [notion.so/profile/integrations](https://notion.so/profile/integrations)
|
||||
2. Click the **"New integration"** button
|
||||
|
||||
|
||||
|
||||
## Step 2: Configure New Integration
|
||||
|
||||
Fill in the integration details:
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Integration Name** | `SurfSense` |
|
||||
| **Associated workspace** | Select your workspace |
|
||||
| **Type** | `Public` |
|
||||
| **Company name** | Your company name |
|
||||
| **Website** | Your website URL |
|
||||
| **Tagline** | Brief description |
|
||||
| **Privacy Policy URL** | Your privacy policy URL |
|
||||
| **Terms of Use URL** | Your terms of use URL |
|
||||
| **Email** | Your developer email |
|
||||
| **Logo** | Upload a 512x512 logo |
|
||||
|
||||
### OAuth Redirect URI
|
||||
|
||||
Under **OAuth domains & URIs**, set the **Redirect URI** to:
|
||||
|
||||
```
|
||||
http://localhost:8000/api/v1/auth/notion/connector/callback
|
||||
```
|
||||
|
||||
Click **Save** to create the integration.
|
||||
|
||||
|
||||
|
||||
## Step 3: Get OAuth Credentials & Configure Capabilities
|
||||
|
||||
After creating the integration, you'll see the configuration page with your credentials:
|
||||
|
||||
1. Copy your **OAuth Client ID**
|
||||
2. Copy your **OAuth Client Secret** (click Refresh if needed)
|
||||
|
||||
### Set Required Capabilities
|
||||
|
||||
Enable the following capabilities:
|
||||
|
||||
| Capability Type | Required Setting |
|
||||
|----------------|------------------|
|
||||
| **Content Capabilities** | Read content |
|
||||
| **Comment Capabilities** | Read comments |
|
||||
| **User Capabilities** | Read user information including email addresses |
|
||||
|
||||
Click **Save** to apply the capabilities.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Limitations & Unsupported Content
|
||||
|
||||
Notion's API has limitations on certain block types that cannot be retrieved. SurfSense will automatically skip these unsupported blocks and continue syncing all other content.
|
||||
|
||||
### Unsupported Block Types
|
||||
|
||||
The following Notion features are **not accessible via the Notion API** and will be skipped during sync:
|
||||
|
||||
- **Transcription blocks** - Audio/video transcriptions from Notion AI
|
||||
- **AI blocks** - AI-generated content blocks
|
||||
|
||||
### Learn More
|
||||
|
||||
The Notion API only supports specific block types for retrieval. The official list of **supported block types** is documented in Notion's Block reference:
|
||||
|
||||
- **[Block Object Reference](https://developers.notion.com/reference/block)** - Official documentation listing all supported block types. Any block type not listed here (such as `transcription` and `ai_block`) is not accessible via the Notion API.
|
||||
|
||||
For additional information:
|
||||
- [Working with Page Content](https://developers.notion.com/docs/working-with-page-content) - Guide on how the Notion API handles page content
|
||||
- [Notion API Reference](https://developers.notion.com/reference) - Complete API documentation
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Notion Connector
|
||||
|
||||
Add the Notion credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
NOTION_OAUTH_CLIENT_ID=your_notion_client_id
|
||||
NOTION_OAUTH_CLIENT_SECRET=your_notion_client_secret
|
||||
NOTION_REDIRECT_URI=http://localhost:8000/api/v1/auth/notion/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
---
|
||||
title: Slack
|
||||
description: Connect your Slack workspace to SurfSense
|
||||
---
|
||||
|
||||
# Slack OAuth Integration Setup Guide
|
||||
|
||||
This guide walks you through setting up a Slack OAuth integration for SurfSense.
|
||||
|
||||
## Step 1: Create a New Slack App
|
||||
|
||||
1. Navigate to [api.slack.com/apps](https://api.slack.com/apps)
|
||||
2. Click **"Create New App"**
|
||||
3. Select **"From scratch"** to manually configure your app
|
||||
|
||||
|
||||
|
||||
## Step 2: Name App & Choose Workspace
|
||||
|
||||
1. Enter **App Name**: `SurfSense`
|
||||
2. Select the workspace to develop your app in
|
||||
3. Click **"Create App"**
|
||||
|
||||
<Callout type="warn">
|
||||
You won't be able to change the workspace later. The workspace will control the app even if you leave it.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Step 3: Get App Credentials
|
||||
|
||||
After creating the app, you'll be taken to the **Basic Information** page. Here you'll find your credentials:
|
||||
|
||||
1. Copy your **Client ID**
|
||||
2. Copy your **Client Secret** (click Show to reveal)
|
||||
|
||||
<Callout type="warn">
|
||||
Never share your app credentials publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Step 4: Configure Redirect URLs
|
||||
|
||||
1. In the left sidebar, click **"OAuth & Permissions"**
|
||||
2. Scroll down to **Redirect URLs**
|
||||
3. Click **"Add New Redirect URL"**
|
||||
4. Enter: `https://localhost:8000/api/v1/auth/slack/connector/callback`
|
||||
5. Click **"Add"**, then **"Save URLs"**
|
||||
|
||||
|
||||
|
||||
## Step 5: Configure Bot Token Scopes
|
||||
|
||||
On the same **OAuth & Permissions** page, scroll to **Scopes** and add the following **Bot Token Scopes**:
|
||||
|
||||
| OAuth Scope | Description |
|
||||
|-------------|-------------|
|
||||
| `channels:history` | View messages and other content in public channels |
|
||||
| `channels:read` | View basic information about public channels |
|
||||
| `groups:history` | View messages and other content in private channels |
|
||||
| `groups:read` | View basic information about private channels |
|
||||
| `im:history` | View messages and other content in direct messages |
|
||||
| `mpim:history` | View messages and other content in group direct messages |
|
||||
| `users:read` | View people in a workspace |
|
||||
|
||||
Click **"Add an OAuth Scope"** to add each scope.
|
||||
|
||||
|
||||
|
||||
## Step 6: Enable Public Distribution
|
||||
|
||||
1. In the left sidebar, click **"Manage Distribution"**
|
||||
2. Under **Share Your App with Other Workspaces**, ensure distribution is enabled
|
||||
3. You can use the **"Add to Slack"** button or **Sharable URL** to install the app
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Running SurfSense with Slack Connector
|
||||
|
||||
Add the Slack credentials to your `.env` file (created during [Docker installation](/docs/docker-installation/docker-compose)):
|
||||
|
||||
```bash
|
||||
SLACK_CLIENT_ID=your_slack_client_id
|
||||
SLACK_CLIENT_SECRET=your_slack_client_secret
|
||||
SLACK_REDIRECT_URI=http://localhost:8000/api/v1/auth/slack/connector/callback
|
||||
```
|
||||
|
||||
Then restart the services:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
title: Web Crawler
|
||||
description: Crawl and index websites with SurfSense
|
||||
---
|
||||
|
||||
# Documentation in progress
|
||||
Loading…
Add table
Add a link
Reference in a new issue