Google Drive Connector¶

Connect and manage Google Drive files (excluding spreadsheets which use Google Sheets connector).

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 Drive 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-files"
}

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-files"
  }'

Response:

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

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

List Google Drive Connections¶

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

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-files`

cURL Example:

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

Response:

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

Get Connected Files¶

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

Get all connected files 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-files`

cURL Example:

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

Response:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "google-drive-files",
  "metadata": {
    "selectedFiles": [
      {
        "id": "1abc123xyz",
        "name": "Project Report.pdf",
        "url": "https://drive.google.com/file/d/1abc123xyz",
        "mimeType": "application/pdf",
        "type": "file",
        "addedAt": "2025-01-15T10:30:00Z",
        "addedBy": "user-123",
        "description": "Quarterly project report",
        "syncStatus": "completed"
      }
    ]
  },
  "authError": null
}

Add Files to Connection¶

POST /connect/integrations/connection-metadata

Add Google Drive files to a connection. Files 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-files",
  "metadata": {
    "selectedFiles": [
      {
        "id": "1abc123xyz",
        "name": "Project Report.pdf",
        "url": "https://drive.google.com/file/d/1abc123xyz",
        "mimeType": "application/pdf",
        "type": "file",
        "addedAt": "2025-01-15T10:30:00Z",
        "addedBy": "user-123",
        "description": "Quarterly project report",
        "addedVia": "picker"
      }
    ]
  }
}

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-files",
    "metadata": {
      "selectedFiles": [
        {
          "id": "1abc123xyz",
          "name": "Project Report.pdf",
          "url": "https://drive.google.com/file/d/1abc123xyz",
          "mimeType": "application/pdf",
          "type": "file",
          "description": "Quarterly project report"
        }
      ]
    }
  }'

Response:

{
  "success": true,
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "google-drive-files",
  "metadata": {
    "selectedFiles": [
      {
        "id": "1abc123xyz",
        "name": "Project Report.pdf",
        "url": "https://drive.google.com/file/d/1abc123xyz",
        "mimeType": "application/pdf",
        "type": "file",
        "description": "Quarterly project report"
      }
    ]
  }
}

Remove File from Connection¶

POST /connect/integrations/connection-metadata

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

Headers:

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

Request Body:

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

List Drive Files¶

GET /connect/integrations/drive-files?connectionId={connectionId}&providerConfigKey={providerConfigKey}

List files in the connected Google Drive account via the Google Drive API (proxied). Returns the Google Drive files payload as-is.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`connectionId`	string	Yes	Connection ID
`providerConfigKey`	string	No	Integration key. Defaults to `google-drive`. Use `google-drive-files` for this connector.
`pageSize`	string	No	Page size passed to Drive (default: `100`)
`pageToken`	string	No	Pagination token from a previous response

cURL Example:

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

Response:

{
  "files": [
    {
      "id": "1abc123xyz",
      "name": "Project Report.pdf",
      "mimeType": "application/pdf",
      "webViewLink": "https://drive.google.com/file/d/1abc123xyz/view",
      "createdTime": "2025-01-10T08:00:00.000Z",
      "modifiedTime": "2025-01-15T10:30:00.000Z",
      "size": "245760",
      "iconLink": "https://drive-thirdparty.googleusercontent.com/..."
    }
  ],
  "nextPageToken": "CAEQAA"
}

nextPageToken is present only when more pages exist.

Start Drive File Sync¶

POST /sync/enqueue

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

Headers:

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

Request Body:

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

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-files"
  }'

Response:

{
  "success": true,
  "enqueuedCount": 1,
  "jobs": [
    {
      "jobId": "8f2c1a4e-9d3b-4c12-a7e6-1b0f3d9e2a11",
      "name": "Project Report.pdf"
    }
  ]
}

If there are no eligible files to queue, the API returns { "success": true, "message": "No files to queue", "enqueuedCount": 0 }.

Get User Info¶

GET /connect/integrations/user-info?connectionId={connectionId}&providerConfigKey=google-drive-files

Get user information 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-files`

cURL Example:

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

Response:

{
  "email": "[email protected]",
  "name": "John Doe",
  "picture": "https://lh3.googleusercontent.com/..."
}

Disconnect Google Drive Account¶

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

Disconnect a Google Drive account and remove all associated files. 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-files`

cURL Example:

curl --request DELETE \
  --url "${BASE_URL}/connect/integrations/connection/5c096330-fc54-4144-bfec-6bd344da9586?integration=google-drive-files" \
  --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 files
POST	`/connect/integrations/connection-metadata`	Add/update files
GET	`/connect/integrations/drive-files`	List files in Drive
POST	`/sync/enqueue`	Start file sync (`providerKey: google-drive-files`)
GET	`/connect/integrations/user-info`	Get user information
DELETE	`/connect/integrations/connection/{connectionId}`	Disconnect account

Supported File Types¶

The Google Drive connector supports the following file types (spreadsheets are handled by Google Sheets connector):

Documents - Google Docs, Word documents
Presentations - Google Slides, PowerPoint
Images - JPG, PNG, GIF, etc.
PDFs - PDF documents
Text Files - Plain text files
Folders - Google Drive folders
Other - Other file types

Features¶

OAuth Authentication - Secure Google account connection via OAuth 2.0
Multiple Accounts - Connect and manage multiple Google accounts
Google Picker Integration - Select files from Google Drive
Add by URL - Connect files using Google Drive URL
File Management - Add, view, and remove files
LLM Context - Add descriptions to help AI understand your files
Sync Status - Track file synchronization status

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)