# Storage

Base URL `https://api.sniphunter.com`

素材存取和文件操作。

# Storage


## GET /api/v1/storage

List Files And Folders


```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "category",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Category"
      }
    },
    {
      "name": "asset_type",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Asset Type"
      }
    },
    {
      "name": "parent_id",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ],
        "title": "Parent Id"
      }
    },
    {
      "name": "is_favorite",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "boolean"
          },
          {
            "type": "null"
          }
        ],
        "title": "Is Favorite"
      }
    },
    {
      "name": "search",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Search"
      }
    },
    {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "default": 1,
        "title": "Page"
      }
    },
    {
      "name": "page_size",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "maximum": 100,
        "minimum": 1,
        "default": 20,
        "title": "Page Size"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/storage/batch-move

Batch Move Assets


```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BatchMoveRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "410": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "type": "boolean",
            "title": "Response Batch Move Assets Api V1 Storage Batch Move Post"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/storage/files/{path}

Get File
获取本地存储的文件，支持 Range 请求和 CORS（工具处理产物，非用户云盘）

```json
{
  "parameters": [
    {
      "name": "path",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "title": "Path"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/storage/upload

Upload Tool File
工具侧文件上传（鉴权）。

不创建 user_assets、不占用用户云存储配额。
返回 URL 供后续工具处理；兼容旧客户端对 asset.file_url 的解析。
匿名工具上传请走 /api/v1/upload/minio。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "multipart/form-data": {
        "schema": {
          "$ref": "#/components/schemas/Body_upload_tool_file_api_v1_storage_upload_post"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## DELETE /api/v1/storage/{asset_id}

Delete Asset


```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "asset_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "integer",
        "title": "Asset Id"
      }
    }
  ],
  "responses": {
    "410": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


# Components

```json
{
  "schemas": {
    "BatchMoveRequest": {
      "properties": {
        "asset_ids": {
          "items": {
            "type": "integer"
          },
          "type": "array",
          "minItems": 1,
          "title": "Asset Ids",
          "description": "资源ID列表"
        },
        "target_folder_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Target Folder Id",
          "description": "目标文件夹ID"
        }
      },
      "type": "object",
      "required": [
        "asset_ids"
      ],
      "title": "BatchMoveRequest",
      "description": "批量移动请求"
    },
    "Body_upload_tool_file_api_v1_storage_upload_post": {
      "properties": {
        "file": {
          "type": "string",
          "format": "binary",
          "title": "File"
        },
        "category": {
          "type": "string",
          "title": "Category",
          "default": "all"
        },
        "folder": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Folder"
        },
        "parent_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Parent Id"
        }
      },
      "type": "object",
      "required": [
        "file"
      ],
      "title": "Body_upload_tool_file_api_v1_storage_upload_post"
    },
    "HTTPValidationError": {
      "properties": {
        "detail": {
          "items": {
            "$ref": "#/components/schemas/ValidationError"
          },
          "type": "array",
          "title": "Detail"
        }
      },
      "type": "object",
      "title": "HTTPValidationError"
    },
    "ValidationError": {
      "properties": {
        "loc": {
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "type": "array",
          "title": "Location"
        },
        "msg": {
          "type": "string",
          "title": "Message"
        },
        "type": {
          "type": "string",
          "title": "Error Type"
        }
      },
      "type": "object",
      "required": [
        "loc",
        "msg",
        "type"
      ],
      "title": "ValidationError"
    }
  },
  "securitySchemes": {
    "HTTPBearer": {
      "type": "http",
      "scheme": "bearer"
    }
  }
}
```