Google Sheets Connector¶

Connect and sync Google Sheets to access spreadsheet data with automatic hourly synchronization.

Base URL¶

BASE_URL = "https://api.fermi.dev/public/v1"

All endpoints are relative to this base URL.

Authentication¶

All endpoints require authentication. Use a service actor token:

Authorization: Bearer <service-actor-token>

Required Scopes:

connectors:read - For read endpoints
connectors:write - For write endpoints
connectors:sync - For synchronization endpoints

Connect Google Account¶

POST /connect/integrations/connect-session

Create a connection session to initiate Google Drive OAuth flow.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "integration": "google-drive"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/connect/integrations/connect-session" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "integration": "google-drive"
  }'

Response:

{
  "sessionToken": "session-token-abc123"
}

Use the sessionToken to complete OAuth. The response includes sessionToken only (no connectUrl).

List Google Sheets Connections¶

GET /connect/integrations/connections?providerConfigKey=google-drive

List all Google Drive connections for the authenticated user.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`providerConfigKey`	string	Yes	Must be `google-drive`

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/connections?providerConfigKey=google-drive" \
  --header "Authorization: Bearer <token>"

Response:

{
  "connections": [
    {
      "id": 517,
      "connection_id": "5c096330-fc54-4144-bfec-6bd344da9586",
      "provider_config_key": "google-drive",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Get Connection Metadata (Sheets List)¶

GET /connect/integrations/connection-metadata?connectionId={connectionId}&providerConfigKey=google-drive

Get all connected sheets for a Google Drive connection.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`connectionId`	string	Yes	Connection ID
`providerConfigKey`	string	Yes	Must be `google-drive`

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/connection-metadata?connectionId=5c096330-fc54-4144-bfec-6bd344da9586&providerConfigKey=google-drive" \
  --header "Authorization: Bearer <token>"

Response:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "google-drive",
  "metadata": {
    "selectedSheets": [
      {
        "id": "1abc123xyz",
        "name": "Sales Data",
        "url": "https://docs.google.com/spreadsheets/d/1abc123xyz",
        "type": "application/vnd.google-apps.spreadsheet",
        "addedAt": "2025-01-15T10:30:00Z",
        "addedBy": "user-123",
        "syncStatus": "completed",
        "description": "Quarterly sales data for analysis"
      }
    ]
  },
  "authError": null
}

Add Sheets to Connection¶

POST /connect/integrations/connection-metadata

Add Google Sheets to a connection. Sheets can be added via Google Picker (frontend) or by URL.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "google-drive",
  "metadata": {
    "selectedSheets": [
      {
        "id": "1abc123xyz",
        "name": "Sales Data",
        "url": "https://docs.google.com/spreadsheets/d/1abc123xyz",
        "type": "application/vnd.google-apps.spreadsheet",
        "addedAt": "2025-01-15T10:30:00Z",
        "addedBy": "user-123",
        "syncStatus": "never",
        "description": "Quarterly sales data for analysis"
      }
    ]
  }
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/connect/integrations/connection-metadata" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
    "providerConfigKey": "google-drive",
    "metadata": {
      "selectedSheets": [
        {
          "id": "1abc123xyz",
          "name": "Sales Data",
          "url": "https://docs.google.com/spreadsheets/d/1abc123xyz",
          "type": "application/vnd.google-apps.spreadsheet",
          "addedAt": "2025-01-15T10:30:00Z",
          "addedBy": "user-123",
          "description": "Quarterly sales data"
        }
      ]
    }
  }'

Response:

{
  "success": true,
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "google-drive",
  "metadata": {
    "selectedSheets": [
      {
        "id": "1abc123xyz",
        "name": "Sales Data",
        "url": "https://docs.google.com/spreadsheets/d/1abc123xyz",
        "type": "application/vnd.google-apps.spreadsheet",
        "addedAt": "2025-01-15T10:30:00Z",
        "addedBy": "user-123",
        "description": "Quarterly sales data"
      }
    ]
  }
}

Preview Sheet Data¶

GET /connect/integrations/sheet-preview?connectionId={connectionId}&providerConfigKey=google-drive&spreadsheetId={spreadsheetId}&sheetName={sheetName}

Preview the first 5 rows of a Google Sheet.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`connectionId`	string	Yes	Connection ID
`providerConfigKey`	string	Yes	Must be `google-drive`
`spreadsheetId`	string	Yes	Google Sheet ID
`sheetName`	string	No	Tab name. If omitted, the API uses the first tab in the spreadsheet.

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/sheet-preview?connectionId=5c096330-fc54-4144-bfec-6bd344da9586&providerConfigKey=google-drive&spreadsheetId=1abc123xyz" \
  --header "Authorization: Bearer <token>"

Response:

{
  "spreadsheetId": "1abc123xyz",
  "sheetName": "Q1 Sales",
  "availableSheets": [
    { "title": "Q1 Sales", "sheetId": 0, "index": 0 },
    { "title": "Q2 Sales", "sheetId": 1, "index": 1 }
  ],
  "headers": ["Name", "Email", "Department", "Salary"],
  "sampleRows": [
    ["John Doe", "[email protected]", "Engineering", "100000"],
    ["Jane Smith", "[email protected]", "Marketing", "95000"]
  ],
  "totalColumns": 4,
  "hasMoreRows": true
}

Remove Sheet from Connection¶

POST /connect/integrations/connection-metadata

Remove a sheet from the connection by updating metadata to exclude the sheet.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "google-drive",
  "metadata": {
    "selectedSheets": [
      // Array without the sheet to remove
    ]
  }
}

Start Sheets Sync¶

POST /sync/enqueue

Queue selected sheets that have not been synced yet (syncStatus missing or never). providerKey must be google-drive.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerKey": "google-drive"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/sync/enqueue" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
    "providerKey": "google-drive"
  }'

Response:

{
  "success": true,
  "enqueuedCount": 1,
  "jobs": [
    {
      "jobId": "8f2c1a4e-9d3b-4c12-a7e6-1b0f3d9e2a11",
      "name": "Sales Data"
    }
  ]
}

If every selected sheet is already queued or synced, the API returns { "success": true, "message": "No sheets to queue", "enqueuedCount": 0 }.

Disconnect Google Account¶

DELETE /connect/integrations/connection/{connectionId}?integration=google-drive

Disconnect a Google Drive account and remove all associated sheets. This DELETE currently returns 502 on the public path.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`integration`	string	Yes	Must be `google-drive`

cURL Example:

curl --request DELETE \
  --url "${BASE_URL}/connect/integrations/connection/5c096330-fc54-4144-bfec-6bd344da9586?integration=google-drive" \
  --header "Authorization: Bearer <token>"

Response:

{
  "success": true,
  "alertingLifecycle": {
    "alerting_stopped": true
  }
}

Endpoints Summary¶

Method	Endpoint	Description
POST	`/connect/integrations/connect-session`	Create connection session
GET	`/connect/integrations/connections`	List connections
GET	`/connect/integrations/connection-metadata`	Get connected sheets
POST	`/connect/integrations/connection-metadata`	Add/update sheets
GET	`/connect/integrations/sheet-preview`	Preview sheet data
POST	`/sync/enqueue`	Start sheets sync (`providerKey: google-drive`)
DELETE	`/connect/integrations/connection/{connectionId}`	Disconnect account

Features¶

OAuth Authentication - Secure Google account connection via OAuth 2.0
Multiple Accounts - Connect and manage multiple Google accounts
Google Picker Integration - Select sheets from Google Drive
Add by URL - Connect sheets using Google Sheets URL
Automatic Sync - Sheets sync hourly automatically
Sheet Preview - Preview sheet data before syncing
LLM Context - Add descriptions to help AI understand your data
Multi-Sheet Support - Manage multiple sheets per account

Sync Status¶

Sheets are automatically synced every hour. Sync status values:

never - Not yet synced
in_progress - Currently syncing
completed - Successfully synced
data_cleaning - Data cleaning in progress
relationship_building - Building relationships
knowledge_graph_sync - Syncing to knowledge graph
failed - Sync failed
paused - Sync paused

Next Steps¶

Data Connectors Overview - Return to data connectors overview
API Reference Overview - Return to API reference index
Scopes and Permissions - Learn about connector scopes
Code Examples - Examples (coming soon)