{
  "openapi": "3.1.0",
  "info": {
    "title": "Bliz Files Integrator API",
    "version": "0.1.0",
    "summary": "Connect customer cloud file workspaces through Bliz Files.",
    "description": "Bliz Files is the cloud file storage middlelayer for customer workspaces. Integrators call this API from their backend with a workspace-scoped API key. To build the connection modal, call the cloud connection start endpoint, open the returned authorizationUrl in a popup, listen for the OAuth postMessage result, then create root grants for the folders the customer approved."
  },
  "servers": [
    {
      "url": "/",
      "description": "Current Bliz Files API host"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Runtime status checks."
    },
    {
      "name": "Tenants",
      "description": "Register the customers (tenants) that will use a workspace."
    },
    {
      "name": "Connection modal",
      "description": "Start and complete the customer cloud connection modal flow."
    },
    {
      "name": "Connections",
      "description": "List provider connections and approved roots for a workspace."
    },
    {
      "name": "Files",
      "description": "Browse, download and mutate files under approved cloud file roots."
    }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Check API health",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "API and BlizDB configuration status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/domains/{domainKey}/tenants": {
      "get": {
        "tags": [
          "Tenants"
        ],
        "summary": "List tenants",
        "operationId": "listWorkspaceTenants",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Tenants currently registered in the workspace.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Tenant"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Tenants"
        ],
        "summary": "Register a tenant",
        "operationId": "registerWorkspaceTenant",
        "description": "Registers a customer (tenant) inside the workspace so cloud connections and files can be scoped to them.",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterTenantInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The registered tenant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tenant"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/tenants/{tenantKey}": {
      "get": {
        "tags": [
          "Tenants"
        ],
        "summary": "Get one tenant",
        "operationId": "getWorkspaceTenant",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          },
          {
            "$ref": "#/components/parameters/TenantKey"
          }
        ],
        "responses": {
          "200": {
            "description": "The tenant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tenant"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/cloud-files/connections/start": {
      "post": {
        "tags": [
          "Connection modal"
        ],
        "summary": "Start cloud connection modal",
        "operationId": "startCloudConnection",
        "description": "Backend endpoint for the customer connection modal. Call it with your workspace API key, open authorizationUrl in a popup, then listen for postMessage events from the callback page. Success messages use type bliz-files.cloud-connection.connected; error messages use type bliz-files.cloud-connection.error.",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartCloudConnectionInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Short-lived provider authorization URL for the popup/modal.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartCloudConnectionResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/cloud-files/connections": {
      "get": {
        "tags": [
          "Connections"
        ],
        "summary": "List workspace cloud connections",
        "operationId": "listCloudConnections",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          },
          {
            "name": "tenantKey",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Provider connections for the workspace or tenant.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CloudConnection"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/cloud-files/root-grants": {
      "post": {
        "tags": [
          "Connections"
        ],
        "summary": "Approve a provider root folder",
        "operationId": "createRootGrant",
        "description": "Stores the provider drive/item root that the integrator may access after a customer connection.",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRootGrantInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created root grant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CloudRootGrant"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/cloud-files/connections/{connectionId}/browse": {
      "get": {
        "tags": [
          "Files"
        ],
        "summary": "Browse files under an approved root",
        "operationId": "browseCloudFiles",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          },
          {
            "$ref": "#/components/parameters/ConnectionId"
          },
          {
            "$ref": "#/components/parameters/RootGrantId"
          },
          {
            "name": "itemId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cloud file children for the requested item or root grant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CloudFilePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/cloud-files/connections/{connectionId}/download": {
      "get": {
        "tags": [
          "Files"
        ],
        "summary": "Create a provider download URL",
        "operationId": "getCloudFileDownloadUrl",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          },
          {
            "$ref": "#/components/parameters/ConnectionId"
          },
          {
            "$ref": "#/components/parameters/RootGrantId"
          },
          {
            "name": "itemId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A temporary provider URL for downloading the requested file.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "downloadUrl"
                  ],
                  "properties": {
                    "downloadUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/cloud-files/connections/{connectionId}/folders": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "Create a folder",
        "operationId": "createCloudFolder",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          },
          {
            "$ref": "#/components/parameters/ConnectionId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateFolderInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created folder item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CloudFileItem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/cloud-files/connections/{connectionId}/upload-small": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "Upload a small file",
        "operationId": "uploadSmallCloudFile",
        "description": "Uploads a base64 encoded file body through the connected provider. Large upload sessions are out of scope for the first implementation.",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          },
          {
            "$ref": "#/components/parameters/ConnectionId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UploadSmallInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Uploaded file item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CloudFileItem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/domains/{domainKey}/cloud-files/connections/{connectionId}/delete": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "Delete a file or folder",
        "operationId": "deleteCloudFileItem",
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "BearerApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DomainKey"
          },
          {
            "$ref": "#/components/parameters/ConnectionId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteItemInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Delete result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "deleted"
                  ],
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-bliz-files-api-key"
      },
      "BearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Bliz Files API key"
      }
    },
    "parameters": {
      "DomainKey": {
        "name": "domainKey",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "customer-workspace"
        }
      },
      "TenantKey": {
        "name": "tenantKey",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "customer-a"
        }
      },
      "ConnectionId": {
        "name": "connectionId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "RootGrantId": {
        "name": "rootGrantId",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid Bliz Files API key."
      },
      "Forbidden": {
        "description": "The API key does not have access to this workspace or scope."
      },
      "NotFound": {
        "description": "The requested resource was not found."
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "required": [
          "service",
          "status",
          "blizDb"
        ],
        "properties": {
          "service": {
            "type": "string",
            "example": "bliz-files-api"
          },
          "status": {
            "type": "string",
            "example": "ok"
          },
          "blizDb": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "RegisterTenantInput": {
        "type": "object",
        "required": [
          "externalTenantKey"
        ],
        "properties": {
          "externalTenantKey": {
            "type": "string",
            "description": "Stable identifier for the tenant in your own system.",
            "example": "customer-a"
          },
          "tenantKey": {
            "type": "string",
            "description": "Optional URL-safe key. Defaults to externalTenantKey.",
            "example": "customer-a"
          },
          "displayName": {
            "type": "string",
            "example": "Customer A"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Tenant": {
        "type": "object",
        "required": [
          "tenantId",
          "externalTenantKey",
          "tenantKey",
          "displayName",
          "status"
        ],
        "properties": {
          "tenantId": {
            "type": "string",
            "format": "uuid"
          },
          "externalTenantKey": {
            "type": "string"
          },
          "tenantKey": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "createdAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "StartCloudConnectionInput": {
        "type": "object",
        "properties": {
          "tenantKey": {
            "type": "string",
            "example": "customer-a"
          },
          "permissionLevel": {
            "type": "string",
            "enum": [
              "read",
              "read_write"
            ],
            "default": "read"
          },
          "returnOrigin": {
            "type": "string",
            "format": "uri",
            "example": "https://app.example.com"
          }
        }
      },
      "StartCloudConnectionResult": {
        "type": "object",
        "required": [
          "authorizationUrl",
          "expiresAt",
          "providerKey"
        ],
        "properties": {
          "authorizationUrl": {
            "type": "string",
            "format": "uri"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "providerKey": {
            "type": "string",
            "description": "Opaque provider key returned by Bliz Files."
          }
        }
      },
      "CloudConnection": {
        "type": "object",
        "required": [
          "connectionId",
          "connectionName",
          "providerKey",
          "status",
          "grantedScopes"
        ],
        "properties": {
          "connectionId": {
            "type": "string",
            "format": "uuid"
          },
          "connectionName": {
            "type": "string"
          },
          "tenantId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "externalAccountLabel": {
            "type": [
              "string",
              "null"
            ]
          },
          "externalTenantId": {
            "type": [
              "string",
              "null"
            ]
          },
          "grantedScopes": {
            "type": "string"
          },
          "providerKey": {
            "type": "string",
            "description": "Opaque provider key returned by Bliz Files."
          },
          "status": {
            "type": "string"
          },
          "tokenExpiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "CreateRootGrantInput": {
        "type": "object",
        "required": [
          "connectionId",
          "displayName",
          "driveId",
          "itemId",
          "permissionLevel"
        ],
        "properties": {
          "connectionId": {
            "type": "string",
            "format": "uuid"
          },
          "displayName": {
            "type": "string",
            "example": "Finance folder"
          },
          "driveId": {
            "type": "string"
          },
          "itemId": {
            "type": "string"
          },
          "itemPath": {
            "type": "string"
          },
          "permissionLevel": {
            "type": "string",
            "enum": [
              "read",
              "read_write"
            ]
          }
        }
      },
      "CloudRootGrant": {
        "type": "object",
        "required": [
          "rootGrantId",
          "connectionId",
          "displayName",
          "driveId",
          "itemId",
          "permissionLevel",
          "status"
        ],
        "properties": {
          "rootGrantId": {
            "type": "string",
            "format": "uuid"
          },
          "connectionId": {
            "type": "string",
            "format": "uuid"
          },
          "displayName": {
            "type": "string"
          },
          "driveId": {
            "type": "string"
          },
          "itemId": {
            "type": "string"
          },
          "itemPath": {
            "type": [
              "string",
              "null"
            ]
          },
          "permissionLevel": {
            "type": "string",
            "enum": [
              "read",
              "read_write"
            ]
          },
          "status": {
            "type": "string"
          }
        }
      },
      "CloudFilePage": {
        "type": "object",
        "required": [
          "items",
          "nextLink"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CloudFileItem"
            }
          },
          "nextLink": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CloudFileItem": {
        "type": "object",
        "required": [
          "id",
          "driveId",
          "name",
          "itemType"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "driveId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "itemType": {
            "type": "string",
            "enum": [
              "file",
              "folder"
            ]
          },
          "parentId": {
            "type": [
              "string",
              "null"
            ]
          },
          "size": {
            "type": [
              "integer",
              "null"
            ]
          },
          "mimeType": {
            "type": [
              "string",
              "null"
            ]
          },
          "etag": {
            "type": [
              "string",
              "null"
            ]
          },
          "webUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "lastModifiedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "CreateFolderInput": {
        "type": "object",
        "required": [
          "rootGrantId",
          "name"
        ],
        "properties": {
          "rootGrantId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "Invoices"
          },
          "parentItemId": {
            "type": "string"
          }
        }
      },
      "UploadSmallInput": {
        "type": "object",
        "required": [
          "rootGrantId",
          "name",
          "base64Content"
        ],
        "properties": {
          "rootGrantId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "invoice.pdf"
          },
          "parentItemId": {
            "type": "string"
          },
          "base64Content": {
            "type": "string",
            "contentEncoding": "base64"
          }
        }
      },
      "DeleteItemInput": {
        "type": "object",
        "required": [
          "rootGrantId",
          "itemId"
        ],
        "properties": {
          "rootGrantId": {
            "type": "string",
            "format": "uuid"
          },
          "itemId": {
            "type": "string"
          }
        }
      }
    }
  }
}