Aıon

Documentation

Cloud Storage API Reference

Google Drive integration for importing and exporting files

Cloud Provider Integration

Connect cloud storage providers (Google Drive) to import and export files. Uses OAuth 2.0 for secure access. Large operations run as background jobs.

OAuth Authentication

POST/api/v2/cloud-storage/auth/{provider}

Initiate OAuth flow for cloud storage connection. Returns an authorization URL to redirect the user to.

Request

{
  "provider": "google_drive",
  "redirect_uri": "https://your-app.com/callback"  // optional
}

Response

{
  "authorization_url": "https://accounts.google.com/o/oauth2/auth?...",
  "state": "csrf_state_token_abc123",
  "provider": "google_drive"
}
GET/api/v2/cloud-storage/auth/{provider}/callback

OAuth callback redirect handler. Google redirects here after user authorization. Returns HTML that posts a message to the popup opener window via postMessage.

Request

// Query parameters (set by Google redirect):
?code=authorization_code_from_google
&state=csrf_state_token_abc123
&error=access_denied           // optional, present on failure
&error_description=User+denied // optional

Response

// Returns HTML (not JSON). On success, posts to opener:
{
  "type": "oauth-complete",
  "success": true,
  "connection": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "provider": "google_drive",
    "provider_email": "user@gmail.com",
    "provider_user_id": "1234567890",
    "display_name": "John Doe",
    "is_token_expired": false
  }
}


// On failure, posts to opener:
{
  "type": "oauth-complete",
  "success": false,
  "error": "User denied access"
}
POST/api/v2/cloud-storage/auth/{provider}/callback

Complete OAuth flow and create connection. Called programmatically after user authorizes the application.

Request

{
  "code": "authorization_code_from_google",
  "state": "csrf_state_token_abc123",
  "redirect_uri": "https://your-app.com/callback"  // optional
}

Response

{
  "connection": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "provider": "google_drive",
    "provider_email": "user@gmail.com",
    "provider_display_name": "John Doe",
    "is_active": true,
    "created_at": "2025-01-15T10:30:00Z",
    "last_used_at": null
  },
  "is_new": true
}

Connection Management

GET/api/v2/cloud-storage/connections

List cloud storage connections for the authenticated user

Request

// Query parameters:
?provider=google_drive  // optional, filter by provider
&active_only=true       // optional, defaults to true

Response

{
  "connections": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "provider": "google_drive",
      "provider_email": "user@gmail.com",
      "provider_display_name": "John Doe",
      "is_active": true,
      "created_at": "2025-01-15T10:30:00Z",
      "last_used_at": "2025-01-15T11:00:00Z"
    }
  ],
  "total_count": 1
}
DELETE/api/v2/cloud-storage/connections/{connection_id}

Disconnect a cloud storage account. Revokes OAuth tokens and removes the connection.

Response

{
  "success": true,
  "message": "Connection disconnected successfully"
}

File Picker

Server-Side Token Security

The picker token endpoint returns a session ID along with credentials for the Google Picker UI. The picker proxy endpoint lets you make Google Drive API calls server-side using the session ID, keeping access tokens secure and not directly exposed to frontend JavaScript.

GET/api/v2/cloud-storage/connections/{connection_id}/picker-token

Get a picker session for the Google Picker file selection UI. Returns credentials needed to initialize the picker component.

Response

{
  "session": {
    "session_id": "picker_sess_abc123",
    "access_token": "ya29...",
    "app_id": "1234567890",
    "developer_key": "AIza...",
    "expires_at": "2025-01-15T11:30:00Z"
  }
}
POST/api/v2/cloud-storage/picker-proxy

Proxy Google Drive API calls server-side. Uses the session from picker-token to make authenticated requests without exposing tokens to the frontend.

Request

{
  "session_id": "picker_sess_abc123",
  "endpoint": "files/abc123",
  "params": {                          // optional
    "fields": "id,name,mimeType,size"
  }
}


// Allowed endpoint patterns:
//   files              - List files
//   files/{id}         - Get file by ID
//   files/{id}/export  - Export file
//   about              - Account/quota info

Response

{
  "data": {
    "id": "abc123",
    "name": "photo.jpg",
    "mimeType": "image/jpeg",
    "size": "2048576"
  }
}

Import & Export

POST/api/v2/cloud-storage/import

Import files from cloud storage. Small imports are processed synchronously; large imports create an async background job.

Request

{
  "connection_id": "550e8400-e29b-41d4-a716-446655440000",
  "files": [
    {
      "id": "gdrive_file_id_1",
      "name": "photo1.jpg",
      "mime_type": "image/jpeg",       // optional
      "size_bytes": 2048576            // optional
    }
  ],
  "auto_describe": true,               // optional, defaults to true
  "tags": ["imported", "drive"],        // optional, defaults to []
  "collection_id": "col_550e8400"      // optional, target collection
}

Response

// Sync response (small imports):
{
  "image_ids": ["img_001", "img_002"],
  "job_id": null,
  "status": null,
  "total_files": 2,
  "is_async": false,
  "message": "2 files imported successfully"
}


// Async response (large imports):
{
  "image_ids": null,
  "job_id": "job_550e8400",
  "status": "pending",
  "total_files": 50,
  "is_async": true,
  "message": "Import job created"
}
POST/api/v2/cloud-storage/export

Export files to cloud storage. Uploads images to the user's connected cloud storage account.

Request

{
  "connection_id": "550e8400-e29b-41d4-a716-446655440000",
  "image_ids": ["img_001", "img_002"],
  "folder_id": "gdrive_folder_id",     // optional, existing folder in cloud
  "folder_name": "Aionvision Export"    // optional, create new folder
}

Response

{
  "cloud_file_ids": null,
  "job_id": "job_660f9500",
  "job_status": "pending",
  "is_async": true,
  "message": "Export job created"
}

Job Status

Status Value Mapping

The API maps internal backend statuses to frontend-friendly values. Backend "processing" is returned as "in_progress", and backend "completed_with_errors" is returned as "partial". All other statuses are returned as-is.

GET/api/v2/cloud-storage/jobs/{job_id}

Get status of an import or export job. Use this to track progress of async operations.

Response

{
  "job": {
    "job_id": "job_550e8400",
    "type": "import",
    "status": "in_progress",
    "connection_id": "550e8400-e29b-41d4-a716-446655440000",
    "provider": "google_drive",
    "total_files": 50,
    "completed_files": 30,
    "failed_files": 2,
    "error": null,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:35:00Z",
    "completed_at": null
  }
}


// Status values: pending | in_progress | completed | partial | failed | cancelled
// Job type values: import | export

Related

Files Reference

Managing imported files

Settings Reference

Custom S3 storage (BYOB)