{
  "openapi": "3.1.0",
  "info": {
    "title": "MyCloudVault Workspaces REST & Sync API",
    "version": "4.8.2",
    "description": "REST API and background delta synchronization protocol for MyCloudVault Workspaces. Enables desktop clients and web applications to stream, sync, and manage shared corporate files.",
    "contact": {
      "name": "MyCloudVault Systems Engineering",
      "url": "https://mycloudvault.de/docs/",
      "email": "support@mycloudvault.de"
    },
    "license": {
      "name": "MyCloudVault Commercial Business License",
      "url": "https://mycloudvault.de/terms/"
    }
  },
  "servers": [
    {
      "url": "https://mycloudvault.de/api/v1",
      "description": "Primary Corporate Workspace Gateway"
    }
  ],
  "paths": {
    "/workspace/{tenant_id}/profile": {
      "get": {
        "summary": "Retrieve Workspace Configuration & Desktop Drive Mount Settings",
        "description": "Returns storage quotas, departmental drive mount parameters, and offline caching thresholds for enrolled employee endpoints.",
        "operationId": "getWorkspaceProfile",
        "parameters": [
          {
            "name": "tenant_id",
            "in": "path",
            "required": true,
            "description": "Company Tenant Workspace UUID",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "c62544c8-8c33-4f8f-80f5-7c867132890d"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace profile successfully returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceProfile"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — Missing or expired corporate SSO token"
          }
        }
      }
    },
    "/workspace/{tenant_id}/sync": {
      "post": {
        "summary": "Open Desktop Delta Synchronization Stream",
        "description": "Establishes a high-throughput background sync session for streaming document alterations, design files, and spreadsheets.",
        "operationId": "initiateDeltaSync",
        "parameters": [
          {
            "name": "tenant_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SyncRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sync stream connected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncResponse"
                }
              }
            }
          }
        }
      }
    },
    "/storage/chunks/upload": {
      "put": {
        "summary": "Upload File Delta Chunk",
        "description": "Uploads an encrypted delta block for a modified corporate document.",
        "operationId": "uploadFileChunk",
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Block committed to workspace storage"
          }
        }
      }
    },
    "/system/health": {
      "get": {
        "summary": "Workspace Service Health",
        "description": "Returns operational status and availability percentage of regional workspace storage clusters.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "System operational status"
          }
        }
      }
    },
    "/auth/sso": {
      "get": {
        "summary": "Identity Provider (SSO) Discovery",
        "description": "Returns SAML 2.0 and OIDC authentication endpoints for corporate Google Workspace, Microsoft 365, and Okta accounts.",
        "operationId": "getSSOConfig",
        "responses": {
          "200": {
            "description": "SSO configuration"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WorkspaceProfile": {
        "type": "object",
        "properties": {
          "tenant_id": { "type": "string", "format": "uuid" },
          "organization_name": { "type": "string", "example": "Acme Global Logistics" },
          "plan": { "type": "string", "example": "Business Enterprise" },
          "virtual_drive_letter": { "type": "string", "example": "Z:" },
          "storage_quota_bytes": { "type": "integer", "example": 54975581388800 },
          "storage_used_bytes": { "type": "integer", "example": 15612589998080 },
          "delta_sync_enabled": { "type": "boolean", "example": true }
        }
      },
      "SyncRequest": {
        "type": "object",
        "properties": {
          "client_version": { "type": "string", "example": "4.8.2-windows" },
          "hostname": { "type": "string", "example": "LAPTOP-SARAH-PC" },
          "pending_files": { "type": "integer", "example": 3 }
        }
      },
      "SyncResponse": {
        "type": "object",
        "properties": {
          "session_id": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "example": "STREAM_ACTIVE" },
          "allocated_bandwidth_mbps": { "type": "integer", "example": 1000 }
        }
      }
    }
  }
}