### Install gowebdav

Source: https://github.com/alistgo/alist/blob/main/pkg/gowebdav/cmd/gowebdav/README.md

Install the gowebdav command line tool using the go get command. Ensure you have Go version 1.x and Git installed.

```sh
go get -u github.com/studio-b12/gowebdav/cmd/gowebdav
```

--------------------------------

### Example Reader Interface Implementation

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/driver-interface.md

Provides an example implementation for the List and Link methods of the Reader interface. It demonstrates how to interact with an external client to fetch file data and generate download URLs.

```Go
func (d *MyDriver) List(ctx context.Context, dir model.Obj, args model.ListArgs) ([]model.Obj, error) {
    items, err := d.client.ListFiles(ctx, dir.GetID())
    if err != nil {
        return nil, err
    }
    
    objs := make([]model.Obj, 0, len(items))
    for _, item := range items {
        objs = append(objs, &model.Object{
            ID:       item.ID,
            Name:     item.Name,
            Size:     item.Size,
            Modified: item.ModTime,
            IsFolder: item.IsDir,
        })
    }
    return objs, nil
}

func (d *MyDriver) Link(ctx context.Context, file model.Obj, args model.LinkArgs) (*model.Link, error) {
    url, err := d.client.GetDownloadURL(ctx, file.GetID())
    if err != nil {
        return nil, err
    }
    return &model.Link{URL: url}, nil
}
```

--------------------------------

### Put Example Implementation

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/driver-interface.md

An example implementation of the Put interface, demonstrating how to calculate hash, apply rate limiting, and upload a file with context and progress.

```go
func (d *MyDriver) Put(ctx context.Context, dstDir model.Obj, file model.FileStreamer, up driver.UpdateProgress) error {
    // Calculate hash and prepare upload
    hashInfo, err := utils.CalcHash(ctx, file, up)
    if err != nil {
        return err
    }
    
    // Apply rate limiting after hash is calculated
    limiter := driver.RateLimitReader(file, stream.ServerUploadLimit)
    
    // Upload with context and progress
    err = d.client.Upload(ctx, dstDir.GetID(), file.GetName(), limiter, up)
    return err
}
```

--------------------------------

### Progress Callback Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/driver-interface.md

Example implementation of a progress callback function that logs the upload progress.

```go
func progressCallback(percentage float64) {
    log.Printf("Upload progress: %.1f%%", percentage)
}
```

--------------------------------

### Configuration and Deployment Guide

Source: https://github.com/alistgo/alist/blob/main/_autodocs/SUMMARY.txt

Guide for configuring and deploying the AList system, including environment variables, TOML/YAML settings, and runtime API settings.

```APIDOC
## Configuration and Deployment Guide

Guide for configuring and deploying the AList system, including environment variables, TOML/YAML settings, and runtime API settings.

### Documentation Location
`configuration.md`
```

--------------------------------

### GoogleDriveAddition Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/driver-interface.md

Example struct for Google Drive driver-specific configuration, using JSON tags for field mapping.

```go
type GoogleDriveAddition struct {
    ClientID     string `json:"client_id"`
    ClientSecret string `json:"client_secret"`
    RefreshToken string `json:"refresh_token"`
    RootID       string `json:"root_id"`
}

func (g *GoogleDriver) GetAddition() driver.Additional {
    return &GoogleDriveAddition{
        ClientID: g.addition.ClientID,
        // ... other fields
    }
}
```

--------------------------------

### WebDAV Operations Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

Examples of interacting with Alist's WebDAV interface for listing, uploading, and downloading files. Requires username and password authentication.

```bash
# List files via WebDAV
curl -u username:password http://localhost:5244/dav/mount/path

# Upload file
curl -u username:password -T file.txt http://localhost:5244/dav/mount/path/file.txt

# Download file
curl -u username:password http://localhost:5244/dav/mount/path/file.txt -o file.txt
```

--------------------------------

### Configuration Example: TOML/YAML

Source: https://github.com/alistgo/alist/blob/main/_autodocs/SUMMARY.txt

This snippet shows an example of AList configuration using TOML or YAML format. It is used for deploying and configuring AList instances.

```toml
[server]
listen = ":5244"

[database]
type = "sqlite"
path = "./alist.db"

```

--------------------------------

### Get Setting

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/operations-layer.md

Retrieves an application setting by its key.

```go
func GetSetting(key string) (*model.Setting, error)
```

--------------------------------

### PostgreSQL DSN Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/configuration.md

Example of a Data Source Name (DSN) string for connecting to a PostgreSQL database.

```sql
user=alist password=password dbname=alist port=5432 sslmode=disable
```

--------------------------------

### MySQL DSN Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/configuration.md

Example of a Data Source Name (DSN) string for connecting to a MySQL database.

```sql
root:password@tcp(localhost:3306)/alist?charset=utf8mb4&parseTime=True&loc=Local
```

--------------------------------

### Storage Model Usage Examples

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/model-structures.md

Demonstrates common operations with the Storage model, such as retrieving, listing, and creating storage configurations.

```go
// Retrieve storage by mount path
storage, err := op.GetStorageAndActualPath("/mount/path")
```

```go
// List all storages
storages, err := op.GetAllStorages()
```

```go
// Create new storage
newStorage := &model.Storage{
    MountPath:       "/backup",
    Driver:          "local",
    CacheExpiration: 300,
    Addition:        `{"root_path":"/data/backup"}`,
}
```

--------------------------------

### Get User with Role using GORM

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/model-structures.md

Example of querying a user and preloading their associated role using the GORM ORM. Assumes `db` is an initialized GORM database instance.

```go
var user model.User
err := db.Preload("Role").First(&user, userID).Error
```

--------------------------------

### Preview Backend Changes

Source: https://github.com/alistgo/alist/blob/main/CONTRIBUTING.md

Run the Alist backend server using the Go command. This command starts the development server for the backend.

```shell
go run main.go
```

--------------------------------

### Request/Response Examples

Source: https://github.com/alistgo/alist/blob/main/_autodocs/SUMMARY.txt

Provides examples for HTTP requests and responses, useful for understanding API interactions and data formats.

```APIDOC
## Request/Response Examples

Provides examples for HTTP requests and responses, useful for understanding API interactions and data formats.

### Documentation Location
`api-reference/request-response-examples.md`
```

--------------------------------

### GET /api/admin/setting/list

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

List all settings.

```APIDOC
## GET /api/admin/setting/list

### Description
List all settings.

### Method
GET

### Endpoint
/api/admin/setting/list
```

--------------------------------

### Get Option

Source: https://github.com/alistgo/alist/blob/main/pkg/aria2/rpc/README.md

Retrieves the specific configuration options for a given download.

```APIDOC
## aria2.getOption

### Description
Retrieves the specific configuration options applied to the download identified by `gid`.

### Method
`aria2.getOption(gid)`

### Parameters
- **gid** (string) - The identifier of the download.

### Response
- **map[string]interface{}** - A map where keys are option names and values are their string representations. Note: Options without defaults or not explicitly set are omitted.
```

--------------------------------

### Authentication and File Listing Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

Demonstrates how to authenticate with the AList API to obtain a token and then use that token to list files in a directory.

```APIDOC
## Authentication and File Listing

### Description
This section provides examples for interacting with the AList API, including obtaining an authentication token and listing directory contents.

### Authentication Endpoint

#### Method
POST

#### Endpoint
`/api/auth/login`

#### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Filesystem List Endpoint

#### Method
POST

#### Endpoint
`/api/fs/list`

#### Parameters
#### Query Parameters
- **path** (string) - Required - The path of the directory to list.
- **page** (integer) - Optional - The page number for pagination.
- **per_page** (integer) - Optional - The number of items per page.

#### Request Example (Login)
```bash
curl -s -X POST http://localhost:5244/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' \
| jq -r '.data.token'
```

#### Request Example (List Files)
```bash
TOKEN=$(curl -s -X POST http://localhost:5244/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.data.token')

curl -s -X POST http://localhost:5244/api/fs/list \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"path":"/","page":1,"per_page":30}' \
| jq
```

### Download Endpoint

#### Method
GET

#### Endpoint
`/d/{mount}/{path}/file.txt`

### Description
Allows downloading files directly. Authentication may not be required if the link is signed.

#### Request Example
```bash
curl -O "http://localhost:5244/d/mount/path/file.txt?sign=..."
```
```

--------------------------------

### Go Example: Storage Driver Interface

Source: https://github.com/alistgo/alist/blob/main/_autodocs/SUMMARY.txt

This snippet shows a pattern for developing storage drivers. It is intended for developers implementing custom storage backends for AList.

```Go
package main

import (
	"fmt"
	"github.com/alist-org/alist/v3/internal/driver"
	"github.com/alist-org/alist/v3/internal/model"
)

type MyCustomDriver struct {
	driver.Driver
	// Add custom fields here
}

func (d *MyCustomDriver) GetFile(path string) (*model.File, error) {
	// Implement logic to retrieve file information from your custom storage
	fmt.Printf("MyCustomDriver: Getting file info for %s\n", path)
	// Return a model.File object or an error
	return &model.File{
		Name: "custom_file.txt",
		Size: 1024,
		Type: "file",
	},
	nil
}

func main() {
	// Example usage of the custom driver
	customDriver := &MyCustomDriver{}
	file, err := customDriver.GetFile("/some/path/in/custom/storage")
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	fmt.Printf("Retrieved file: %s\n", file.Name)
}

```

--------------------------------

### Go Example: Filesystem Operations

Source: https://github.com/alistgo/alist/blob/main/_autodocs/SUMMARY.txt

This snippet demonstrates core filesystem package API usage. It is intended for Go developers working with the AList library.

```Go
package main

import (
	"fmt"
	"github.com/alist-org/alist/v3/internal/fs"
	"github.com/alist-org/alist/v3/internal/model"
)

func main() {
	// Example: List files in a directory
	path := "/"
	files, err := fs.List(path)
	if err != nil {
		fmt.Printf("Error listing files: %v\n", err)
		return
	}

	fmt.Printf("Files in %s:\n", path)
	for _, file := range files {
		fmt.Printf("- %s (Type: %s)\n", file.Name, file.Type)
	}

	// Example: Get file information
	filePath := "/example.txt"
	fileInfo, err := fs.Stat(filePath)
	if err != nil {
		fmt.Printf("Error getting file info: %v\n", err)
		return
	}

	fmt.Printf("\nFile Info for %s:\n", filePath)
	fmt.Printf("Name: %s\n", fileInfo.Name)
	fmt.Printf("Size: %d bytes\n", fileInfo.Size)
	fmt.Printf("Modified: %s\n", fileInfo.ModTime)
}

```

--------------------------------

### GET /api/admin/storage/list

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

List all storages configured in the system.

```APIDOC
## GET /api/admin/storage/list

### Description
List all storages.

### Method
GET

### Endpoint
/api/admin/storage/list
```

--------------------------------

### API Endpoints and Request/Response Examples

Source: https://github.com/alistgo/alist/blob/main/_autodocs/INDEX.md

This section provides access to detailed information about the available HTTP endpoints and practical examples of requests and responses. It covers authentication, file operations, sharing, admin tasks, search, and archive operations.

```APIDOC
## API Reference

This API provides a comprehensive set of operations for managing files, users, and server settings.

### Endpoints
Refer to `endpoints.md` for a detailed list of HTTP routes and their functionalities.

### Request/Response Examples
Refer to `api-reference/request-response-examples.md` for practical examples of API requests and responses, including authentication, file operations, sharing, admin operations, search, task management, archive operations, and error responses.

### Business Logic Layer
Refer to `api-reference/operations-layer.md` for details on the core business logic functions, including storage retrieval, list operations, file operations, upload operations, copy operations, archive operations, caching, and user/storage/settings management.
```

--------------------------------

### Driver Init Error Handling

Source: https://github.com/alistgo/alist/blob/main/_autodocs/errors.md

Return wrapped errors with context during driver initialization. This example shows how to wrap an authentication failure.

```go
func (d *MyDriver) Init(ctx context.Context) error {
    // Return wrapped errors with context
    if err := d.authenticate(ctx); err != nil {
        return errs.NewErr(errs.NotImplement, "authentication failed: %v", err)
    }
    
    return nil
}
```

--------------------------------

### Create Role with Permissions

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/model-structures.md

Example of creating a new role instance and assigning specific permissions to different paths. The role is automatically serialized to JSON upon saving.

```go
// Create role with permissions
role := &model.Role{
    Name:        "Editor",
    Description: "Can edit files",
    Default:     false,
    PermissionScopes: []model.PermissionEntry{
        {
            Path:       "/public",
            Permission: 0b1111, // All permissions
        },
        {
            Path:       "/admin",
            Permission: 0b0000, // No access
        },
    },
}
// Role is automatically serialized to JSON when saved
```

--------------------------------

### Context Cancellation Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/operations-layer.md

Shows how to use `context.WithTimeout` to set a deadline for an operation and handle `context.DeadlineExceeded` errors for graceful shutdown.

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
def cancel()

er := op.Copy(ctx, srcStorage, dstStorage, srcPath, dstPath, progressCallback)
if err == context.DeadlineExceeded {
    log.Warn("Copy operation timed out")
}
```

--------------------------------

### Get Storage by ID

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/operations-layer.md

Retrieves a storage system configuration by its unique ID.

```go
func GetStorageByID(id uint) (*model.Storage, error)
```

--------------------------------

### Local Storage Backend Configuration

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

Example JSON configuration for setting up a local storage backend. Specifies the mount path and the root directory on the local filesystem.

```json
{
  "mount_path": "/local",
  "driver": "local",
  "addition": {
    "root_path": "/data/files"
  }
}
```

--------------------------------

### Label a File

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/model-structures.md

Example of creating a binding to associate a label with a specific file for a user. Requires `userID`, `labelID`, and `filePath`.

```go
// Label a file
binding := &model.LabelFileBinding{
    UserID:   userID,
    LabelID:  labelID,
    FilePath: "/path/to/file.txt",
}
```

--------------------------------

### Preview Frontend Changes

Source: https://github.com/alistgo/alist/blob/main/CONTRIBUTING.md

Start the Alist frontend development server using pnpm. This command is used to preview changes made to the user interface.

```shell
pnpm dev
```

--------------------------------

### Get Storage by Mount Path

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/model-structures.md

Retrieves storage information based on its mount path.

```go
var storage model.Storage
err := db.Where("mount_path = ?", "/mount/path").First(&storage).Error
```

--------------------------------

### Concurrent Operations Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/operations-layer.md

Illustrates how to perform operations concurrently using `sync.WaitGroup` to manage multiple goroutines, ensuring all operations complete before proceeding.

```go
var wg sync.WaitGroup

for _, path := range filePaths {
    wg.Add(1)
    go func(p string) {
        defer wg.Done()
        if err := op.Remove(ctx, storage, p); err != nil {
            log.Errorf("Failed to remove %s: %v", p, err)
        }
    }(path)
}

wg.Wait()
```

--------------------------------

### Full Driver Implementation Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/driver-interface.md

This Go code provides a complete implementation of the Alist driver interface, including methods for configuration, storage management, initialization, resource cleanup, file listing, generating links, renaming files, and uploading files. It shows how to interact with an external API client and manage storage.

```go
type MyDriver struct {
    client *myapi.Client
    store  *model.Storage
}

// Meta implementation
func (d *MyDriver) Config() driver.Config {
    return MyConfig{}
}

func (d *MyDriver) GetStorage() *model.Storage {
    return d.store
}

func (d *MyDriver) SetStorage(s model.Storage) {
    d.store = &s
}

func (d *MyDriver) GetAddition() driver.Additional {
    return &MyAddition{}
}

func (d *MyDriver) Init(ctx context.Context) error {
    // Authenticate, refresh tokens, etc.
    return d.client.Authenticate(ctx)
}

func (d *MyDriver) Drop(ctx context.Context) error {
    // Cleanup resources
    return nil
}

// Reader implementation
func (d *MyDriver) List(ctx context.Context, dir model.Obj, args model.ListArgs) ([]model.Obj, error) {
    items, err := d.client.List(ctx, dir.GetID())
    if err != nil {
        return nil, err
    }
    
    objs := make([]model.Obj, len(items))
    for i, item := range items {
        objs[i] = &model.Object{
            ID:       item.ID,
            Name:     item.Name,
            Size:     item.Size,
            Modified: item.ModTime,
            IsFolder: item.IsDir,
        }
    }
    return objs, nil
}

func (d *MyDriver) Link(ctx context.Context, file model.Obj, args model.LinkArgs) (*model.Link, error) {
    url, err := d.client.GetURL(ctx, file.GetID())
    return &model.Link{URL: url}, err
}

// Rename implementation (optional)
func (d *MyDriver) Rename(ctx context.Context, srcObj model.Obj, newName string) error {
    return d.client.Rename(ctx, srcObj.GetID(), newName)
}

// Put implementation (optional)
func (d *MyDriver) Put(ctx context.Context, dstDir model.Obj, file model.FileStreamer, up driver.UpdateProgress) error {
    // Hash calculation
    hashInfo, err := utils.CalcHash(ctx, file, up)
    if err != nil {
        return err
    }
    
    // Rate limiting
    limitedFile := driver.RateLimitReader(file, stream.ServerUploadLimit)
    
    // Upload
    return d.client.Upload(ctx, dstDir.GetID(), file.GetName(), limitedFile, up)
}
```

--------------------------------

### Error Wrapping Example

Source: https://github.com/alistgo/alist/blob/main/_autodocs/errors.md

Demonstrates wrapping errors using NewErr for specific context and fmt.Errorf with %w for general error chaining.

```go
func CopyFile(ctx context.Context, srcPath, dstPath string) error {
    obj, err := fs.Get(ctx, srcPath, &fs.GetArgs{})
    if err != nil {
        return errs.NewErr(errs.StorageNotFound, "source file not found: %s", srcPath)
    }
    
    if err := fs.Copy(ctx, srcPath, dstPath); err != nil {
        return fmt.Errorf("copy failed: %w", err)
    }
    return nil
}
```

--------------------------------

### Aliyundrive Storage Backend Configuration

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

Example JSON configuration for integrating Aliyundrive as a storage backend. Requires a refresh token and specifies the root folder ID.

```json
{
  "mount_path": "/aliyun",
  "driver": "aliyundrive",
  "addition": {
    "refresh_token": "your_refresh_token",
    "root_folder_id": "root"
  }
}
```

--------------------------------

### GET /api/public/settings

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

Get public settings for the Alist instance. No authentication is required.

```APIDOC
## GET /api/public/settings

### Description
Get public settings (no auth required).

### Method
GET

### Endpoint
/api/public/settings

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code, expected to be 200 for success.
- **message** (string) - A message indicating the status of the request, typically 'success'.
- **data** (object) - Contains the public settings.
  - **title** (string) - The title of the Alist instance.
  - **logo** (string) - URL to the instance logo.
  - **favicon** (string) - URL to the instance favicon.
  - **customize_head** (string) - Custom HTML content for the head section.
  - **customize_body** (string) - Custom HTML content for the body section.
  - **enable_search** (boolean) - Flag indicating if search is enabled.

### Response Example
{
  "code": 200,
  "message": "success",
  "data": {
    "title": "string",
    "logo": "string",
    "favicon": "string",
    "customize_head": "string",
    "customize_body": "string",
    "enable_search": true
  }
}
```

--------------------------------

### GET /api/admin/index/progress

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

Get the current progress of the search index building process.

```APIDOC
## GET /api/admin/index/progress

### Description
Get indexing progress.

### Method
GET

### Endpoint
/api/admin/index/progress
```

--------------------------------

### Alist Server Startup Flags

Source: https://github.com/alistgo/alist/blob/main/_autodocs/configuration.md

Run the Alist binary directly using command-line flags to configure the server. This example sets the port, host, configuration file path, and data directory.

```bash
alist server \
  --port 5244 \
  --host 0.0.0.0 \
  --config ./config.toml \
  --data ./data
```

--------------------------------

### List Storages with jq

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

Troubleshooting command to list all configured storages using curl and jq. Useful for verifying storage setup and identifying mount paths.

```bash
curl http://localhost:5244/api/admin/storage/list | jq
```

--------------------------------

### Create a Share Link with Access Controls

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

This example demonstrates how to create a share link for a file or directory. It shows how to configure options such as the root path, display name, download/preview permissions, access limits, and expiration time. The created share's ID is then used to construct the share URL.

```go
share := &model.Share{
    RootPath:      "/mount/file.pdf",
    Name:          "Report",
    AllowDownload: true,
    AllowPreview:  true,
    AccessLimit:   5,  // 5 accesses maximum
    ExpiresAt:     &expiryTime,
}

err := op.CreateShare(share)
if err != nil {
    log.Fatalf("Share creation failed: %v", err)
}

fmt.Printf("Share URL: https://example.com/s/%s\n", share.ShareID)
```

--------------------------------

### GET /p/*path

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

Proxies file downloads through Alist, enabling caching. Query parameters are similar to /d/*path.

```APIDOC
## GET /p/*path

### Description
Proxy file through alist (with streaming).

### Method
GET

### Endpoint
/p/*path

### Parameters
#### Query Parameters
- **sign** (string) - Required - The download signature.
- **inline** (boolean) - Optional - Set Content-Disposition to inline.

### Response
#### Success Response
- **File content with caching headers** - The content of the file with caching information.

### Auth Required
No (signature-based)
```

--------------------------------

### Download File with Direct Link or Proxy

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

This example illustrates how to obtain a download link for a file. It first generates a link using `fs.Link` and then shows how to use the provided URL for direct download or stream the file through an alist proxy.

```go
link, _, err := fs.Link(ctx, "/mount/file.pdf", model.LinkArgs{
    Redirect: false,
})
if err != nil {
    log.Fatalf("Link failed: %v", err)
}

// Direct download
fmt.Println("Download URL:", link.URL)

// Or stream through alist proxy
resp, err := http.Get(link.URL)
// ...
```

--------------------------------

### Client Connect Method

Source: https://github.com/alistgo/alist/blob/main/pkg/gowebdav/README.md

Establishes a connection to the WebDAV server.

```go
func (c *Client) Connect() error
```

--------------------------------

### Get Current User Request

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/request-response-examples.md

Send a GET request to the /api/me endpoint with an Authorization header to retrieve current user information.

```bash
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -X GET http://localhost:5244/api/me \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/operations-layer.md

Retrieves the metadata for a single file or folder within a storage. This is used to get information about a specific item without retrieving its content.

```APIDOC
## Get

### Description
Retrieve single file/folder metadata.

### Method
Not Applicable (Go function)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Request context
- **storage** (driver.Driver) - Required - Storage driver
- **actualPath** (string) - Required - Path within storage

### Returns
- **model.Obj** - File/folder object
- **error** - Error if not found
```

--------------------------------

### Get File or Folder Metadata

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/operations-layer.md

Retrieves metadata for a single file or folder within a storage. Use this to get information about a specific object.

```Go
func Get(ctx context.Context, storage driver.Driver, actualPath string) (model.Obj, error)
```

--------------------------------

### Example Alist YAML Configuration

Source: https://github.com/alistgo/alist/blob/main/_autodocs/configuration.md

This is the main configuration file for Alist, defining settings for scheme, JWT, database, cache, search, CORS, limits, offline downloads, and logging.

```yaml
scheme:
  http_port: 5244
  https_port: -1
  force_https: false
  cert_file: ""
  key_file: ""

jwt:
  secret: "your-secret-key"

database:
  type: "sqlite"
  dsn: ""
  path: "./data/alist.db"

cache:
  expiration: 300

search:
  enabled: true
  index_path: "./data/search.db"

cors:
  allow_origins:
    - "*"
  allow_headers:
    - "*"
  allow_methods:
    - "*"

limits:
  max_connections: -1
  download_rate_limit: ""
  upload_rate_limit: ""

offline_download:
  enabled: false
  aria2_endpoint: "http://localhost:6800/jsonrpc"
  aria2_token: ""

logging:
  level: "info"
  file: ""
```

--------------------------------

### POST /api/admin/setting/set_qbit

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

Configure qBittorrent settings.

```APIDOC
## POST /api/admin/setting/set_qbit

### Description
Configure qBittorrent.

### Method
POST

### Endpoint
/api/admin/setting/set_qbit
```

--------------------------------

### OneDrive Storage Backend Configuration

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

Example JSON configuration for setting up OneDrive as a storage backend. Includes client ID, client secret, refresh token, and region.

```json
{
  "mount_path": "/onedrive",
  "driver": "onedrive",
  "addition": {
    "client_id": "app_id",
    "client_secret": "app_secret",
    "refresh_token": "token",
    "region": "global"
  }
}
```

--------------------------------

### Retrieve and Update Application Settings

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/model-structures.md

Demonstrates how to retrieve an existing setting by its key and how to update a setting's value. Assumes `op` is an initialized operation handler.

```go
// Retrieve setting
setting, err := op.GetSetting("site_title")
if err == nil {
    title := setting.Value
}

// Update setting
err := op.UpdateSetting("site_title", "My Storage Site")
```

--------------------------------

### S3 Storage Backend Configuration

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

Example JSON configuration for connecting to an S3-compatible storage service. Requires endpoint, bucket name, access key, and secret key.

```json
{
  "mount_path": "/s3",
  "driver": "s3",
  "addition": {
    "endpoint": "https://s3.amazonaws.com",
    "bucket": "my-bucket",
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}
```

--------------------------------

### Client MkdirAll Method

Source: https://github.com/alistgo/alist/blob/main/pkg/gowebdav/README.md

Creates a directory and any necessary parent directories, similar to `mkdir -p`.

```go
func (c *Client) MkdirAll(path string, _ os.FileMode) error
```

--------------------------------

### Get Share

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/operations-layer.md

Retrieves a share link by its ID.

```go
func GetShare(shareID string) (*model.Share, error)
```

--------------------------------

### Example TOML Configuration

Source: https://github.com/alistgo/alist/blob/main/_autodocs/configuration.md

A sample TOML configuration file demonstrating various settings for Alist, including scheme, JWT, database, cache, search, CORS, limits, offline downloads, and logging.

```toml
[scheme]
http_port = 5244
https_port = -1
force_https = false
cert_file = ""
key_file = ""

[jwt]
secret = "your-secret-key"

[database]
type = "sqlite"
dsn = ""
path = "./data/alist.db"

[cache]
expiration = 300

[search]
enabled = true
index_path = "./data/search.db"

[cors]
allow_origins = ["*"]
allow_headers = ["*"]
allow_methods = ["*"]

[limits]
max_connections = -1
download_rate_limit = ""
upload_rate_limit = ""

[offline_download]
enabled = false
aria2_endpoint = "http://localhost:6800/jsonrpc"
aria2_token = ""

[logging]
level = "info"
file = ""

```

--------------------------------

### Go Example: Operations Layer

Source: https://github.com/alistgo/alist/blob/main/_autodocs/SUMMARY.txt

This snippet illustrates business logic API usage from the operations layer. It is relevant for Go developers integrating with AList's core functionalities.

```Go
package main

import (
	"fmt"
	"github.com/alist-org/alist/v3/internal/op"
	"github.com/alist-org/alist/v3/internal/model"
)

func main() {
	// Example: Create a new directory
	parentPath := "/"
	newDirName := "new_directory"
	createdDir, err := op.Mkdir(parentPath, newDirName)
	if err != nil {
		fmt.Printf("Error creating directory: %v\n", err)
		return
	}

	fmt.Printf("Directory created: %s\n", createdDir.Path)

	// Example: Upload a file (simulated)
	// In a real scenario, you would provide file content and size.
	uploadPath := "/new_directory/uploaded_file.txt"
	fileContent := []byte("This is the content of the uploaded file.")
	fileSize := int64(len(fileContent))

	uploadedFile, err := op.Upload(uploadPath, fileContent, fileSize)
	if err != nil {
		fmt.Printf("Error uploading file: %v\n", err)
		return
	}

	fmt.Printf("File uploaded: %s (Size: %d)\n", uploadedFile.Name, uploadedFile.Size)
}

```

--------------------------------

### Get Role

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/operations-layer.md

Retrieves a permission role by its ID.

```go
func GetRole(roleID uint) (*model.Role, error)
```

--------------------------------

### GET /api/task/list

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

List all background tasks currently running or completed.

```APIDOC
## GET /api/task/list

### Description
List background tasks.

### Method
GET

### Endpoint
/api/task/list

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code, expected to be 200 for success.
- **message** (string) - A message indicating the status of the request, typically 'success'.
- **data** (array) - A list of background tasks.
  - **id** (string) - The unique identifier for the task.
  - **name** (string) - The name or type of the task.
  - **status** (string) - The current status of the task (e.g., 'running', 'completed', 'failed').
  - **progress** (number) - The progress of the task as a percentage.
  - **created_at** (string) - The timestamp when the task was created, in ISO 8601 format.

### Response Example
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "string",
      "name": "string",
      "status": "running",
      "progress": 45.5,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Get Current User

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/request-response-examples.md

Retrieves information about the currently authenticated user.

```APIDOC
## GET /api/me

### Description
Fetches the details of the currently logged-in user.

### Method
GET

### Endpoint
/api/me

### Parameters
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code, expected to be 200.
- **message** (string) - Success message, typically "success".
- **data** (object) - User information.
  - **id** (integer) - User's unique identifier.
  - **username** (string) - User's username.
  - **password** (string) - User's password (usually empty in responses).
  - **base_path** (string) - The base path configured for the user.
  - **role** (object) - User's role information.
    - **id** (integer) - Role's unique identifier.
    - **name** (string) - Role's name (e.g., "Admin").
    - **permission** (integer) - Bitmask representing role permissions.
  - **disabled** (boolean) - Indicates if the user account is disabled.
  - **created_at** (string) - Timestamp of user creation.
  - **updated_at** (string) - Timestamp of last user update.

#### Response Example (200)
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "admin",
    "password": "",
    "base_path": "/",
    "role": {
      "id": 1,
      "name": "Admin",
      "permission": 4095
    },
    "disabled": false,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```
```

--------------------------------

### Get Session Information

Source: https://github.com/alistgo/alist/blob/main/pkg/aria2/rpc/README.md

Retrieves information about the current Aria2 session.

```go
func (id *Client) GetSessionInfo() (m map[string]interface{}, err error)
```

--------------------------------

### Initialize GoWebDAV Client

Source: https://github.com/alistgo/alist/blob/main/pkg/gowebdav/README.md

Create a new client instance for interacting with a WebDAV server. Ensure you handle errors in production code.

```go
root := "https://webdav.mydomain.me"
user := "user"
password := "password"

c := gowebdav.NewClient(root, user, password)
```

--------------------------------

### Get Peers

Source: https://github.com/alistgo/alist/blob/main/pkg/aria2/rpc/README.md

Retrieves information about peers connected to a specific download.

```APIDOC
## aria2.getPeers

### Description
Returns information about the peers connected to the download specified by `gid`.

### Method
`aria2.getPeers(gid)`

### Parameters
- **gid** (string) - The identifier of the download.

### Response
- **list of map[string]interface{}** - A list containing peer information.
```

--------------------------------

### Login and List Files via API

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

Demonstrates how to obtain an authentication token and list directory contents using cURL. Ensure the server is running and accessible.

```bash
# Login
TOKEN=$(curl -s -X POST http://localhost:5244/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.data.token')

# List files
curl -s -X POST http://localhost:5244/api/fs/list \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"path":"/","page":1,"per_page":30}' | jq
```

--------------------------------

### Get Files

Source: https://github.com/alistgo/alist/blob/main/pkg/aria2/rpc/README.md

Retrieves the list of files associated with a specific download.

```APIDOC
## aria2.getFiles

### Description
Returns the list of files belonging to the download specified by `gid`.

### Method
`aria2.getFiles(gid)`

### Parameters
- **gid** (string) - The identifier of the download.

### Response
- **map[string]interface{}** - A map representing the file list.
```

--------------------------------

### New Client

Source: https://github.com/alistgo/alist/blob/main/pkg/aria2/rpc/README.md

Initializes a new RPC client with the given URI.

```APIDOC
## New Client

### Description
Initializes a new RPC client with the given URI.

### Function Signature
`New(uri string) *Client`
```

--------------------------------

### Implement Custom Storage Driver Interface

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

This Go code demonstrates the structure for implementing a custom storage driver by embedding the `driver.Driver` interface. It includes required methods for configuration, storage management, initialization, and dropping, as well as optional methods for listing, linking, uploading, and renaming files.

```go
package mydrive

import (
    "context"
    "github.com/alist-org/alist/v3/internal/driver"
    "github.com/alist-org/alist/v3/internal/model"
)

// Implement Driver interface
type MyDriver struct {
    client *MyAPIClient
    store  *model.Storage
}

// Required: Meta implementation
func (d *MyDriver) Config() driver.Config { ... }
func (d *MyDriver) GetStorage() *model.Storage { return d.store }
func (d *MyDriver) SetStorage(s model.Storage) { d.store = &s }
func (d *MyDriver) GetAddition() driver.Additional { ... }
func (d *MyDriver) Init(ctx context.Context) error { ... }
func (d *MyDriver) Drop(ctx context.Context) error { ... }

// Required: Reader implementation
func (d *MyDriver) List(ctx context.Context, dir model.Obj, args model.ListArgs) ([]model.Obj, error) {
    items, err := d.client.ListFiles(ctx, dir.GetID())
    if err != nil {
        return nil, err
    }
    
    objs := make([]model.Obj, len(items))
    for i, item := range items {
        objs[i] = &model.Object{
            ID:       item.ID,
            Name:     item.Name,
            Size:     item.Size,
            Modified: item.ModTime,
            IsFolder: item.IsDir,
        }
    }
    return objs, nil
}

func (d *MyDriver) Link(ctx context.Context, file model.Obj, args model.LinkArgs) (*model.Link, error) {
    url, err := d.client.GetDownloadURL(ctx, file.GetID())
    if err != nil {
        return nil, err
    }
    return &model.Link{URL: url}, nil
}

// Optional: Upload support
func (d *MyDriver) Put(ctx context.Context, dstDir model.Obj, file model.FileStreamer, up driver.UpdateProgress) error {
    // Hash calculation
    hashInfo, err := utils.CalcHash(ctx, file, up)
    if err != nil {
        return err
    }
    
    // Upload with rate limiting
    limitedFile := driver.RateLimitReader(file, stream.ServerUploadLimit)
    return d.client.Upload(ctx, dstDir.GetID(), file.GetName(), limitedFile, up)
}

// Optional: Rename support
func (d *MyDriver) Rename(ctx context.Context, srcObj model.Obj, newName string) error {
    return d.client.Rename(ctx, srcObj.GetID(), newName)
}

```

--------------------------------

### GET /ping

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

Health check endpoint to verify if the Alist server is running.

```APIDOC
## GET /ping

### Description
Health check endpoint.

### Method
GET

### Endpoint
/ping

### Response
Plain text "pong"
```

--------------------------------

### Client Initialization

Source: https://github.com/alistgo/alist/blob/main/pkg/gowebdav/README.md

Initialize a new GoWebDAV client instance with the root URL, username, and password.

```APIDOC
## Client Initialization

### Description
Initializes a new `Client` instance using the `NewClient()` function.

### Usage
```go
root := "https://webdav.mydomain.me"
user := "user"
password := "password"

c := gowebdav.NewClient(root, user, password)
```
```

--------------------------------

### Get Single File Info

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/request-response-examples.md

Retrieves detailed information about a specific file.

```APIDOC
## POST /api/fs/get

### Description
Fetches detailed information for a single file.

### Method
POST

### Endpoint
/api/fs/get

### Parameters
#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication.

#### Request Body
- **path** (string) - Required - The path to the file.
- **password** (string) - Optional - Password for accessing password-protected files.

### Request Example
```json
{
  "path": "/report.pdf",
  "password": ""
}
```

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code, expected to be 200.
- **message** (string) - Success message, typically "success".
- **data** (object) - File information.
  - **id** (string) - Unique identifier for the file.
  - **path** (string) - The full path of the file.
  - **virtual_path** (string) - The virtual path of the file.
  - **name** (string) - The name of the file.
  - **size** (integer) - The size of the file in bytes.
  - **is_dir** (boolean) - False, as this endpoint is for files.
  - **modified** (string) - Timestamp of last modification.
  - **created** (string) - Timestamp of creation.
  - **sign** (string) - Signature or hash of the file.

#### Response Example (200)
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "file-456",
    "path": "/report.pdf",
    "virtual_path": "/report.pdf",
    "name": "report.pdf",
    "size": 2048576,
    "is_dir": false,
    "modified": "2024-01-10T14:22:00Z",
    "created": "2024-01-01T00:00:00Z",
    "sign": "signature_string"
  }
}
```
```

--------------------------------

### POST /api/admin/storage/enable

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

Enable a storage.

```APIDOC
## POST /api/admin/storage/enable

### Description
Enable storage.

### Method
POST

### Endpoint
/api/admin/storage/enable
```

--------------------------------

### GET /api/auth/logout

Source: https://github.com/alistgo/alist/blob/main/_autodocs/endpoints.md

Logs out the currently authenticated user by invalidating their session token.

```APIDOC
## GET /api/auth/logout

### Description
Logout current user (invalidate session).

### Method
GET

### Endpoint
/api/auth/logout

### Response
#### Success Response (200)
- **code** (integer) - Success code
- **message** (string) - Success message

### Auth Required
Yes
```

--------------------------------

### Execute gowebdav commands via wrapper script

Source: https://github.com/alistgo/alist/blob/main/pkg/gowebdav/cmd/gowebdav/README.md

Examples of using the 'dav' wrapper script to interact with a WebDAV server. These commands demonstrate listing, uploading, checking status, and downloading files.

```sh
$ ./dav -X LS /

```

```sh
$ echo hi dav! > hello && ./dav -X PUT /hello

```

```sh
$ ./dav -X STAT /hello

```

```sh
$ ./dav -X PUT /hello_dav hello

```

```sh
$ ./dav -X GET /hello_dav

```

```sh
$ ./dav -X GET /hello_dav hello.txt

```

--------------------------------

### Monitor Upload Progress with Callbacks

Source: https://github.com/alistgo/alist/blob/main/_autodocs/README.md

This example shows how to monitor the progress of upload operations using a callback function. It contrasts a direct copy operation without progress tracking with an `op.Copy` call that accepts a progress callback to report the percentage completion.

```go
fs.Copy(ctx, "/src/large.zip", "/dst/", &fs.ListArgs{})  // No progress
// vs
op.Copy(ctx, srcStorage, dstStorage, srcPath, dstPath, func(percentage float64) {
    log.Printf("Progress: %.1f%%", percentage)
})
```

--------------------------------

### ArchiveGetter Interface

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/driver-interface.md

Provides the capability to get file metadata from within an archive.

```APIDOC
## ArchiveGetter Interface

### Description
Get file metadata from within an archive.

### Method Signature
`ArchiveGet(ctx context.Context, obj model.Obj, args model.ArchiveInnerArgs) (model.Obj, error)`

### Parameters
- `ctx` (context.Context): The request context.
- `obj` (model.Obj): The archive object.
- `args` (model.ArchiveInnerArgs): Arguments for accessing the archive content.

### Returns
- `model.Obj`: The metadata of the file within the archive.
- `error`: An error if the operation fails.
```

--------------------------------

### Get Active Sessions

Source: https://github.com/alistgo/alist/blob/main/_autodocs/api-reference/model-structures.md

Retrieves active user sessions that have not yet expired.

```go
var sessions []model.Session
err := db.Where("user_id = ? AND expires_at > ?", userID, time.Now()).Find(&sessions).Error
```

--------------------------------

### Client Mkdir Method

Source: https://github.com/alistgo/alist/blob/main/pkg/gowebdav/README.md

Creates a new directory at the specified path on the WebDAV server.

```go
func (c *Client) Mkdir(path string, _ os.FileMode) error
```