Google Drive API

This page documents the public Google Drive API. It follows the Drive action model with 17 operations grouped into drive, file, folder, and fileFolder resources.

Connect

Create a connection ticket:

curl -X POST https://auth.genium.one/api/social/connect-ticket \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"drive"}'

Open the returned connect_url in a browser. The callback is:

https://auth.genium.one/callback/drive

The Drive actions require the full Google Drive permission. Existing Drive connections made with the narrower upload permission must reconnect.

Shared-drive actions also require a Google Workspace account with Shared Drive access. A personal Google account can still use all file, folder, upload, download, share, move, and search actions, but may return an empty shared-drive list and cannot create a new shared drive.

List connected Drive accounts:

curl https://auth.genium.one/api/drive/accounts \
  -H "Authorization: Bearer $USER_API_KEY"

Endpoint

Metadata actions use:

POST https://auth.genium.one/api/google/drive
Authorization: Bearer <USER_API_KEY>
Content-Type: application/json

The upload action uses the same endpoint with query parameters and a raw local file body:

POST https://auth.genium.one/api/google/drive?resource=file&operation=upload

The legacy upload endpoint remains available at POST https://auth.genium.one/api/drive/files.

Common fields

Field	Type	Description
resource	string	drive, file, folder, or fileFolder.
operation	string	Action to execute.
account_id	number	Selects a connected Drive account.
drive_id	string	Shared drive ID.
file_id	string	File ID.
folder_id	string	Folder ID.
name	string	File, folder, or shared drive name.
description	string	File description.
parents	string[]	Parent folder IDs.
mime_type	string	Google MIME type.
fields	string	Google Drive response field projection.
page_size	number	List page size, from 1 to 1,000.
page_token	string	Token returned by a previous list/search response.

Successful JSON actions return:

{
  "resource": "file",
  "operation": "copy",
  "result": {}
}

download returns the file bytes with the Google content type. Invalid input returns 400; a missing account returns 404; Google API failures return 502.

Drive actions

1. Create a shared drive

curl -X POST https://auth.genium.one/api/google/drive \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"drive","operation":"create","name":"Genium Team Drive"}'

2. Delete a shared drive

{
  "resource": "drive",
  "operation": "delete",
  "drive_id": "DRIVE_ID"
}

3. Get a shared drive

curl -X POST https://auth.genium.one/api/google/drive \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"drive","operation":"get","drive_id":"DRIVE_ID"}'

4. List shared drives

curl -X POST https://auth.genium.one/api/google/drive \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"drive","operation":"list","page_size":100,"fields":"drives(id,name),nextPageToken"}'

Use the returned nextPageToken as page_token for the next page.

5. Update a shared drive

{
  "resource": "drive",
  "operation": "update",
  "drive_id": "DRIVE_ID",
  "name": "Renamed Team Drive"
}

File actions

6. Copy a file

curl -X POST https://auth.genium.one/api/google/drive \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"file","operation":"copy","file_id":"FILE_ID","name":"Video copy","parents":["FOLDER_ID"]}'

7. Create a text file

curl -X POST https://auth.genium.one/api/google/drive \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"file","operation":"createFromText","name":"notes.txt","mime_type":"text/plain","content":"Genium notes"}'

8. Download a file

curl -X POST "https://auth.genium.one/api/google/drive" \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"file","operation":"download","file_id":"FILE_ID"}' \
  -o downloaded-file

9. Delete a file

{
  "resource": "file",
  "operation": "delete",
  "file_id": "FILE_ID"
}

10. Move a file

{
  "resource": "file",
  "operation": "move",
  "file_id": "FILE_ID",
  "add_parents": "DESTINATION_FOLDER_ID",
  "remove_parents": "OLD_FOLDER_ID"
}

11. Share a file

curl -X POST https://auth.genium.one/api/google/drive \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"file","operation":"share","file_id":"FILE_ID","type":"user","role":"reader","email_address":"person@example.com","send_notification_email":true}'

Allowed common type values are user, group, domain, and anyone. Common role values are reader, commenter, writer, and organizer.

12. Update file metadata

{
  "resource": "file",
  "operation": "update",
  "file_id": "FILE_ID",
  "name": "new-name.mp4",
  "description": "Updated description"
}

13. Upload a local file

Send the file as the raw request body:

curl -X POST "https://auth.genium.one/api/google/drive?resource=file&operation=upload" \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "X-File-Name: final_video.mp4" \
  -H "X-Folder-Id: FOLDER_ID" \
  -H "Content-Type: video/mp4" \
  --data-binary @final_video.mp4

The response includes file_id, web_view_link, size_bytes, and delete_after. Uploads are tracked and automatically deleted from Drive after one hour. Use the legacy /api/drive/files endpoint when you need its existing idempotency behavior.

Folder actions

14. Create a folder

curl -X POST https://auth.genium.one/api/google/drive \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"folder","operation":"create","name":"Genium Videos","parents":["PARENT_FOLDER_ID"]}'

15. Delete a folder

{
  "resource": "folder",
  "operation": "delete",
  "folder_id": "FOLDER_ID"
}

16. Share a folder

{
  "resource": "folder",
  "operation": "share",
  "folder_id": "FOLDER_ID",
  "type": "user",
  "role": "writer",
  "email_address": "person@example.com"
}

File/folder search

17. Search files or folders

Use a Google Drive query in query:

curl -X POST https://auth.genium.one/api/google/drive \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource":"fileFolder","operation":"search","query":"name contains '\''video'\'' and trashed = false","page_size":100,"fields":"nextPageToken,files(id,name,mimeType,parents,webViewLink,modifiedTime)"}'

If query is omitted, providing name creates a name-contains search.