REST API

Upload files, list contents, and manage your Drive connections programmatically.

Base URL

https://drivewidget.com/api/drive

Authentication

All API requests require your API key passed as a header:

X-API-Key: dw_live_xxxxxxxxxxxxxxxx

Get your key from Dashboard → Settings → API Keys.

Endpoints

Upload a file

POST /api/drive/{connection_id}/upload

Upload a file to your connected Google Drive folder.

Headers

X-API-Key: dw_live_xxx
Content-Type: multipart/form-data

Body (multipart/form-data)

Field	Type	Required	Description
`file`	File	Yes	The file to upload
`subfolder`	string	No	Upload into a subfolder (created automatically)
`rename_to`	string	No	Override the filename

Example

curl -X POST https://drivewidget.com/api/drive/CONN_ID/upload \
  -H "X-API-Key: dw_live_xxx" \
  -F "file=@report.pdf" \
  -F "subfolder=clients/acme"

Response

{
  "file_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
  "name": "report.pdf",
  "size": 204800,
  "mime_type": "application/pdf",
  "web_view_link": "https://drive.google.com/file/d/1Bxi.../view",
  "created_at": "2026-02-27T14:32:05Z"
}

List files

GET /api/drive/{connection_id}/files

List all files in the connected folder.

Query parameters

Param	Default	Description
`limit`	50	Max files to return (max 200)
`offset`	0	Pagination offset
`q`	—	Search by filename

Example

curl https://drivewidget.com/api/drive/CONN_ID/files?limit=20 \
  -H "X-API-Key: dw_live_xxx"

Response

{
  "files": [
    {
      "file_id": "1Bxi...",
      "name": "report.pdf",
      "size": 204800,
      "mime_type": "application/pdf",
      "web_view_link": "https://drive.google.com/...",
      "created_at": "2026-02-27T14:32:05Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Download a file

GET /api/drive/{connection_id}/files/{file_id}/download

Returns the file as a binary stream with appropriate Content-Type headers.

Example

curl -o report.pdf \
  https://drivewidget.com/api/drive/CONN_ID/files/FILE_ID/download \
  -H "X-API-Key: dw_live_xxx"

Delete a file

DELETE /api/drive/{connection_id}/files/{file_id}

Permanently deletes the file from Google Drive.

Example

curl -X DELETE \
  https://drivewidget.com/api/drive/CONN_ID/files/FILE_ID \
  -H "X-API-Key: dw_live_xxx"

Response

{ "deleted": true }

Error codes

Status	Code	Meaning
`401`	`invalid_api_key`	Missing or invalid API key
`403`	`forbidden`	Connection does not belong to your account
`404`	`not_found`	Connection or file not found
`413`	`file_too_large`	File exceeds your plan's max upload size
`429`	`rate_limited`	Too many requests. Check `Retry-After` header
`500`	`drive_error`	Google Drive returned an error

Rate limits

Plan	Requests/minute
Free	10
Starter	60
Growth	120
Pro	300
Business	1,000

When exceeded, the API returns 429 with a Retry-After header indicating seconds to wait.

SDKs & examples

No official SDK yet — the API is standard REST, easy to call from any language.

Need no-code file collection instead? See Embed Widget → or Client Portals →.

Node.js

const FormData = require("form-data");
const fs = require("fs");
const axios = require("axios");

const form = new FormData();
form.append("file", fs.createReadStream("./report.pdf"));

const res = await axios.post(
  `https://drivewidget.com/api/drive/${CONN_ID}/upload`,
  form,
  { headers: { "X-API-Key": "dw_live_xxx", ...form.getHeaders() } }
);
console.log(res.data.file_id);

Python

import requests

with open("report.pdf", "rb") as f:
    res = requests.post(
        f"https://drivewidget.com/api/drive/{CONN_ID}/upload",
        headers={"X-API-Key": "dw_live_xxx"},
        files={"file": f},
    )
print(res.json()["file_id"])

PHP

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://drivewidget.com/api/drive/{$connId}/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: dw_live_xxx"],
  CURLOPT_POSTFIELDS => ["file" => new CURLFile("report.pdf")],
]);
$response = json_decode(curl_exec($curl), true);
echo $response["file_id"];

Next steps

Webhooks → — React to file uploads in real-time
Embed Widget → — Let users upload files from your website without code
Connections → — Manage Google Drive folders and API key scopes
Quickstart → — New to DriveWidget? Start here