Quick Start

A rapid introduction to Swiftgum’s setup and usage.

Quick Start

This guide walks you through setting up Swiftgum in five simple steps.

1. Sign Up & Retrieve API Key

   1. Sign Up
      Visit Swiftgum and create an account.

   2. Reveal Your API Key

      • Log into your admin dashboard.
      • Access the API Keys section to copy your x-api-key.
2. Activate an Integration

   With your admin account, navigate to Integrations in the Swiftgum dashboard. For example, to enable Google Drive:

   • Toggle the Integration: Switch the integration status to “Enabled”.
   • Enter OAuth Credentials:
     • Client ID and Client Secret (from your Google Developer Console), or leave them blank if already configured.
     • Click Update Integration to save changes.

   

   Once an integration is Enabled, end users can connect personal or team accounts via the Swiftgum Portal.

3. Create a Portal Session

   Next, call the /api/portal/session endpoint to generate a sessionId for a specific user, allowing them to manage their newly enabled integration.

   POST /api/portal/session
   Host: https://api.swiftgum.com
   x-api-key: <YOUR_SWIFTGUM_API_KEY>
   Content-Type: application/json
   
   {
     "uniqueUserId": "[e-mail]",
     "configuration": {
       "userDisplay": "MyUser",
       "returnUrl": "https://example.com"
     }
   }
   

   Response (200): The response contains a signed URL that the developer can directly use in the UI.

     "https://api.swiftgum.com/portal/sess_abc123""
   
4. Redirect User to the Portal

   1. Use the returned sessionId to build a portal link:
      https://api.swiftgum.com/portal/<sessionId>
      
   2. Redirect your user to that link (e.g., from a “Manage Knowledge” button in your app).
   3. The user can now authorize Google Drive (or any other enabled integration) under their account, set permissions, etc.
   4. After finishing, they’ll be sent back to your specified returnUrl.

   This short-lived portal link ensures secure user access to Swiftgum’s integration management without exposing your app’s internal credentials.

5. Configure a Webhook Destination

   By default, Swiftgum functions as an ETL engine—fetching data from the enabled integrations. To receive that data in your system:

   • Navigate to Webhook Destination in your Swiftgum admin dashboard.
   • Specify your Endpoint (e.g., https://api.yourdomain.com/swiftgum-webhook).
   • Swiftgum will send new or updated content to this endpoint after each fetch.
   • Verify Delivery: Swiftgum will send a test POST request to validate connectivity.

   Once configured, your system can automatically receive structured data for storage, AI workflows, or additional processing.

   Example Webhook Response:

   {
     "endUser": [
       {
         "end_user_id": "45d3de52-2e65-4f67-b61e-6f3c768b0224",
         "foreign_id": "[e-mail]",
         "workspace_id": "95b3acd3-d881-4cfc-b53e-4edd9f36230a",
         "created_at": "2025-02-20T11:06:43.281Z",
         "updated_at": "2025-02-20T11:06:43.281Z"
       }
     ],
     "metadata": {
       "tokenId": "1d31beee-8e4e-493a-a717-d7b1fbd9a9ff",
       "fileId": "f9a9a66e-f2ad-4f61-b4a6-01921f3dfe3d",
       "remoteUrl": "https://notion.so/f9a9a66ef2ad4f61b4a601921f3dfe3d",
       "fileName": "Who Will Teach Silicon Valley to Be Ethical?",
       "provider": "notion",
       "mimeType": "text/markdown",
       "sgid": "notion/792e06c944c9adb7e4bfd7b5e023786aa5ede59103cb4f791dd6958ff55f491e"
     },
     "content": "# Who Will Teach Silicon Valley to Be Ethical?
   
   I think we can all agree that Silicon Valley needs more adult supervision right about now.
   ... (truncated for brevity)"
   }
   

   • Navigate to Webhook Destination in your Swiftgum admin dashboard.
   • Specify your Endpoint (e.g., https://api.yourdomain.com/swiftgum-webhook).
     • Swiftgum will send new or updated content to this endpoint after each fetch.
   • Verify Delivery: Swiftgum will send a test POST request to validate connectivity.

   Once configured, your system can automatically receive structured data for storage, AI workflows, or additional processing.

   

   After saving, your system can handle incoming data (e.g., store in Supabase, parse for further AI workflows, etc.).

With these five steps, you have a working integration with Swiftgum—users can manage and authorize their content sources through the portal, and you can automatically receive that data via a webhook. Continue to the Installation guide if you’re exploring local hosting or advanced setups.