{
  "openapi": "3.1.0",
  "info": {
    "title": "Zbwine Delivery API",
    "version": "2.4.1",
    "description": "Asset storage, signed delivery links and multipart upload sessions.",
    "contact": { "name": "Zbwine API support", "url": "https://api.zbwine.site/" }
  },
  "servers": [
    { "url": "https://api.zbwine.site/v2", "description": "Production" },
    { "url": "https://api.zbwine.site/v2-sandbox", "description": "Sandbox" }
  ],
  "security": [ { "bearerAuth": [] } ],
  "tags": [
    { "name": "assets", "description": "Asset records and metadata" },
    { "name": "delivery", "description": "Signed links and file delivery" },
    { "name": "uploads", "description": "Multipart upload sessions" }
  ],
  "paths": {
    "/assets": {
      "get": {
        "tags": ["assets"],
        "summary": "List assets in a project",
        "operationId": "listAssets",
        "parameters": [
          { "name": "project", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
          { "name": "kind", "in": "query", "schema": { "type": "string", "enum": ["video", "image", "archive", "other"] } }
        ],
        "responses": {
          "200": {
            "description": "A page of assets",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetPage" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["assets"],
        "summary": "Register an asset record",
        "operationId": "createAsset",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreate" } } }
        },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/assets/{id}": {
      "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ],
      "get": {
        "tags": ["assets"],
        "summary": "Retrieve a single asset",
        "operationId": "getAsset",
        "responses": {
          "200": { "description": "The asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "delete": {
        "tags": ["assets"],
        "summary": "Delete an asset and its renditions",
        "operationId": "deleteAsset",
        "responses": {
          "204": { "description": "Deleted" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/links/sign": {
      "post": {
        "tags": ["delivery"],
        "summary": "Issue a time-limited delivery token",
        "operationId": "signLink",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["asset"],
            "properties": {
              "asset": { "type": "string" },
              "expires_in": { "type": "integer", "default": 3600, "maximum": 604800 },
              "ip_lock": { "type": "boolean", "default": false }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Signed token", "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "token": { "type": "string", "examples": ["dl_9f31c7"] },
              "url": { "type": "string", "format": "uri" },
              "expires_at": { "type": "string", "format": "date-time" }
            }
          } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/uploads": {
      "post": {
        "tags": ["uploads"],
        "summary": "Open a multipart upload session",
        "operationId": "createUpload",
        "responses": {
          "201": { "description": "Session opened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/uploads/{id}": {
      "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ],
      "put": {
        "tags": ["uploads"],
        "summary": "Upload a part",
        "operationId": "uploadPart",
        "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } },
        "responses": {
          "202": { "description": "Part accepted" },
          "409": { "description": "Part already committed" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Environment-scoped API key, e.g. live_sk_…" }
    },
    "schemas": {
      "Asset": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "examples": ["ast_7f2c91ba"] },
          "kind": { "type": "string", "enum": ["video", "image", "archive", "other"] },
          "filename": { "type": "string" },
          "bytes": { "type": "integer" },
          "duration_ms": { "type": ["integer", "null"] },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "AssetCreate": {
        "type": "object",
        "required": ["project", "kind", "filename"],
        "properties": {
          "project": { "type": "string" },
          "kind": { "type": "string", "enum": ["video", "image", "archive", "other"] },
          "filename": { "type": "string" },
          "retention_days": { "type": "integer", "minimum": 1, "maximum": 3650 }
        }
      },
      "AssetPage": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } },
          "has_more": { "type": "boolean" },
          "next_cursor": { "type": ["string", "null"] }
        }
      },
      "UploadSession": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "examples": ["upl_2b81ee"] },
          "part_size": { "type": "integer", "examples": [8388608] },
          "parts_expected": { "type": "integer" },
          "expires_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "request_id": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "InvalidRequest": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Plan limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}