/filepicker

GET SYNC

Opens a native OS dialog for the user to select local files or folders.

GET /api/v1/filepicker

Alias: /open-file-dialog

Description

This is a special utility endpoint that triggers a native operating system file or folder selection dialog on the machine where the application is running. It is designed to be called by a front-end UI to allow users to browse their local filesystem, an action that is restricted in standard web browsers.

Unlike most other endpoints, this call is synchronous. The HTTP request will hang and wait for the user to either select items or cancel the dialog.

💡 UI Integration

This endpoint is the bridge between your web interface and the user's local files. The paths returned by this call can be used directly in other API endpoints like /import or /detect.

Request

The type of dialog is specified using a URL query parameter.

Parameter	Type	In	Description
`type`	string	Query	Specifies the dialog type. Can be `file` (allows multi-select) or `folder`. Defaults to `folder` if omitted.

Response

On success, returns a 200 OK response with a JSON object containing the paths of the selected items.

Response Properties

items_pickedarray of strings

An array of absolute paths for each file or folder selected by the user.

Example Response (for file selection)

{
  "items_picked": [
    "/home/user/Documents/CloudCoins/100.CloudCoin.stack",
    "/home/user/Documents/CloudCoins/another.CloudCoin.png"
  ]
}

Dialog Cancellation

If the user closes or cancels the dialog box without making a selection, the endpoint will return an error with the code dialog_cancelled. Your application should handle this case gracefully.

Examples

JavaScript (async/await)

const apiHost = 'http://localhost:8006';

// Function to open the file picker to select files
async function selectFiles() {
    try {
        const response = await fetch(`${apiHost}/api/v1/filepicker?type=file`);
        if (!response.ok) {
            const errorData = await response.json();
            // Handle cases where the user cancels the dialog
            if (errorData.error.code === 'dialog_cancelled') {
                console.log('User cancelled the file selection.');
                return;
            }
            throw new Error(`HTTP error: ${errorData.error.message}`);
        }
        const data = await response.json();
        console.log('Selected files:', data.items_picked);
        // You can now use these file paths in another API call, like /import
    } catch (error) {
        console.error('Failed to open file picker:', error);
    }
}

// Function to open the file picker to select a folder
async function selectFolder() {
    try {
        const response = await fetch(`${apiHost}/api/v1/filepicker?type=folder`);
        if (!response.ok) {
           // Handle errors similarly...
           const errorData = await response.json();
           console.error(`Error: ${errorData.error.message}`);
           return;
        }
        const data = await response.json();
        console.log('Selected folder:', data.items_picked[0]);
    } catch (error) {
        console.error('Failed to open folder picker:', error);
    }
}

// Example usage:
// selectFiles();
// selectFolder();

cURL

# Request to open a file selection dialog
# Note: This will trigger the dialog on the machine where the API server is running
curl -X GET "http://localhost:8006/api/v1/filepicker?type=file"

# Request to open a folder selection dialog
curl -X GET "http://localhost:8006/api/v1/filepicker?type=folder"

# Example Success Response:
# {"items_picked":["/path/to/selected/file.txt"]}

# Example Error Response (if cancelled):
# {"status":"error","error":{"code":"dialog_cancelled","message":"Dialog cancelled"}}

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

const ApiHost = "http://localhost:8006"
type FilePickerResponse struct {
    ItemsPicked []string `json:"items_picked"`
}

func main() {
    // This function simulates calling the endpoint from a Go application.
    // The dialog will open on the server machine.
    resp, err := http.Get(fmt.Sprintf("%s/api/v1/filepicker?type=file", ApiHost))
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        // Handle potential errors like dialog cancellation
        fmt.Printf("Received non-200 status code: %d\n", resp.StatusCode)
        return
    }

    var pickerResp FilePickerResponse
    if err := json.NewDecoder(resp.Body).Decode(&pickerResp); err != nil {
        panic(err)
    }

    fmt.Printf("User selected: %v\n", pickerResp.ItemsPicked)
}

Related Endpoints

/detect

Use the file paths from the file picker to detect the authenticity of coins before importing.

View Details

/import

After selecting files with the picker, use this endpoint to import the verified coins into a wallet.

View Details