AI Agent Integration Guide

How to use this GDrive Upload service from an AI agent, automation tool, or script. This guide is optimized for LLM consumption.

Quick Reference

Complete Workflow

Follow these steps in order. Each step depends on the previous one.

Step-by-Step API Calls

Step 1: Login

POST /api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "gdrive2026"
}

Response: {"success": true}
Set-Cookie: session=<token>

Save the session cookie. All subsequent requests must include it.

Step 2: Start Download

POST /api/download
Content-Type: application/json
Cookie: session=<token>

{
  "url": "https://example.com/file.zip",
  "filename": "file.zip",
  "folder": "downloads"
}

Response: {
  "success": true,
  "job_id": "a1b2c3d4",
  "filename": "file.zip",
  "message": "Download started in background"
}

filename and folder are optional. If filename is empty, it's auto-detected from the URL.

Step 3: Check Progress

POST /api/status
Content-Type: application/json
Cookie: session=<token>

{
  "id": "a1b2c3d4"
}

Response: {
  "status": "downloading",
  "filename": "file.zip",
  "percent": 45.2,
  "speed_human": "12.5 MB/s",
  "downloaded_human": "45.2 MB",
  "total_human": "100.0 MB",
  "eta_human": "4m 23s",
  "elapsed": 3,
  "error": ""
}

Step 4: Wait for Completion

Poll /api/status every 1-5 seconds. Stop when status is done, error, or cancelled.

API Reference

Status Values

Prompt Templates

For AI Agents - System Prompt

For AI Agents - Tool Definition (OpenAI Function Calling)

{
  "name": "download_to_gdrive",
  "description": "Download a file from a URL and save it to Google Drive via the GDrive Upload API.",
  "parameters": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "The URL of the file to download"
      },
      "filename": {
        "type": "string",
        "description": "Optional filename. Auto-detected from URL if not provided."
      },
      "folder": {
        "type": "string",
        "description": "Optional subfolder in Google Drive to save to."
      }
    },
    "required": ["url"]
  }
}

For AI Agents - Tool Definition (Anthropic Claude)

{
  "name": "download_to_gdrive",
  "description": "Download a file from any URL to Google Drive. Use this when the user wants to save a file from the internet to their Google Drive. Returns a job_id for tracking progress.",
  "input_schema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "Direct download URL of the file"
      },
      "filename": {
        "type": "string",
        "description": "Desired filename (optional, auto-detected from URL)"
      },
      "folder": {
        "type": "string",
        "description": "Subfolder path in Google Drive (optional)"
      }
    },
    "required": ["url"]
  }
}

Error Handling

Common Errors

Retry Strategy

1. If status returns "Unauthorized" → re-login, get new cookie, retry
2. If download fails with network error → retry with exponential backoff
3. If status returns "error" → log the error, alert user, do not retry

Complete cURL Example (Copy-Paste Ready)

# Step 1: Login
curl -c cookies.txt -X POST https://upload.cobaweb.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"gdrive2026"}'

# Step 2: Start download
curl -b cookies.txt -X POST https://upload.cobaweb.com/api/download \
  -H "Content-Type: application/json" \
  -d '{"url":"https://proof.ovh.net/files/100Mb.dat","filename":"100mb-test.dat","folder":"test"}'

# Step 3: Check status (replace JOB_ID with actual job_id from step 2)
curl -b cookies.txt -X POST https://upload.cobaweb.com/api/status \
  -H "Content-Type: application/json" \
  -d '{"id":"JOB_ID"}'

# Step 4: List files in Google Drive
curl -b cookies.txt -X POST https://upload.cobaweb.com/api/list \
  -H "Content-Type: application/json" \
  -d '{"folder":""}'

# Step 5: Cancel a download (replace JOB_ID)
curl -b cookies.txt -X POST https://upload.cobaweb.com/api/cancel \
  -H "Content-Type: application/json" \
  -d '{"id":"JOB_ID"}'

Python Script (Ready to Use)

#!/usr/bin/env python3
import requests
import time
import sys

BASE = "https://upload.cobaweb.com"

def gdrive_download(url, filename=None, folder=None):
    s = requests.Session()
    
    # Login
    r = s.post(f"{BASE}/api/login", json={"username": "admin", "password": "gdrive2026"})
    if not r.json().get("success"):
        raise Exception("Login failed")
    
    # Start download
    payload = {"url": url}
    if filename: payload["filename"] = filename
    if folder: payload["folder"] = folder
    
    r = s.post(f"{BASE}/api/download", json=payload)
    data = r.json()
    if not data.get("success"):
        raise Exception(data.get("error", "Download failed"))
    
    job_id = data["job_id"]
    print(f"Download started: {job_id}")
    
    # Poll until done
    while True:
        r = s.post(f"{BASE}/api/status", json={"id": job_id})
        status = r.json()
        
        if status["status"] == "done":
            print(f"Done! {status['size_human']} in {status['elapsed']}s")
            return True
        elif status["status"] in ("error", "cancelled"):
            print(f"Failed: {status.get('error', status['status'])}")
            return False
        else:
            print(f"  {status['percent']}% - {status['speed_human']} - ETA {status['eta_human']}")
        
        time.sleep(2)

# Usage
if __name__ == "__main__":
    url = sys.argv[1] if len(sys.argv) > 1 else "https://proof.ovh.net/files/10Mb.dat"
    gdrive_download(url)