Get File / Folder Info

Retrieve information about files or folders on your shard node by specifying the path as a query parameter.

GET /fso-info

Get metadata information about a file or folder

Important Notes

  • • All paths must start with / (absolute paths only)
  • • Use trailing / for folders (e.g., /files/)
  • • Use your shard node URL and your API key

Headers

Header Type Required Description
x-user-api-key string Yes Your authentication API key

Query Parameters

Parameter Type Required Description
path string Yes Absolute path of the file or folder (must start with /)

Example Request

type EntryInfo struct {
    Path         string      `json:"path"`
    Name         string      `json:"name"`
    Size         int64       `json:"size"`
    LastModified string      `json:"last_modified"`
    Nested       []EntryInfo `json:"nested"`
}

func GetFSOInfo(pathOnShard string) (info *EntryInfo) {
    info = &EntryInfo{}
    url := fmt.Sprintf("%s/fso-info?path=%s", SHARD_NODE_URL, url.QueryEscape(pathOnShard))
    req, err := http.NewRequest(http.MethodGet, url, nil)
    if err != nil {
        panic(fmt.Errorf("could not create fso-info request: %w", err))
    }

    req.Header.Set("x-user-api-key", API_KEY)

    client := http.DefaultClient
    resp, err := client.Do(req)
    if err != nil {
        panic(fmt.Errorf("error getting file info: %w", err))
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        body, _ := io.ReadAll(resp.Body)
        panic(fmt.Sprintf("Get file info failed with status %d: %s", resp.StatusCode, string(body)))
    }

    err = json.NewDecoder(resp.Body).Decode(info)
    if err != nil {
        panic(fmt.Errorf("could not decode fso info JSON: %w", err))
    }

    return info
}
interface EntryInfo {
    path: string;
    name: string;
    size: number;
    last_modified: string;
    nested: EntryInfo[];
}

async function getFSOInfo(pathOnShard: string): Promise<EntryInfo> {
    const url = `${SHARD_NODE_URL}/fso-info?path=${encodeURIComponent(pathOnShard)}`;
    const res = await fetch(url, {
        method: 'GET',
        headers: { 'x-user-api-key': API_KEY }
    });

    if (res.status !== 200) {
        const body = await res.text();
        throw new Error(`Get file info failed with status ${res.status}: ${body}`);
    }

    const info: EntryInfo = await res.json();
    return info;
}

Response Format

EntryInfo JSON

{
  "path": "/files/hello.txt",
  "name": "hello.txt",
  "size": 15,
  "last_modified": "2025-08-18T11:30:09+03:00",
  "nested": null
}

path: Absolute path of the file/folder

name: Name of the file/folder

size: Size in bytes

last_modified: Timestamp in RFC3339 format

nested: Array of EntryInfo objects for folder contents (null for files)

Response Status Codes

Code Status Description
200 Success Info retrieved successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
404 Not Found File or folder doesn't exist
5xx Server Error Internal server error - check response body for details

Query Storage Usage

Check your remaining storage space by using the info=remaining parameter.

GET /fso-info?info=remaining

Get total and remaining storage information

Query Parameters

Parameter Type Required Description
info string Yes Must be "remaining" to query storage usage

Example Request

type RemainingSizeResp struct {
    Total     int64 `json:"total"`
    Remaining int64 `json:"remaining"`
}

func QueryRemainingStorage() RemainingSizeResp {
    var remaining RemainingSizeResp
    url := fmt.Sprintf("%s/fso-info?info=remaining", SHARD_NODE_URL)
    req, err := http.NewRequest(http.MethodGet, url, nil)
    if err != nil {
        panic(fmt.Errorf("could not create storage query request: %w", err))
    }
    req.Header.Set("x-user-api-key", API_KEY)

    client := http.DefaultClient
    resp, err := client.Do(req)
    if err != nil {
        panic(fmt.Errorf("error querying storage: %w", err))
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        body, _ := io.ReadAll(resp.Body)
        panic(fmt.Sprintf("Query remaining failed with status %d: %s", resp.StatusCode, string(body)))
    }

    err = json.NewDecoder(resp.Body).Decode(&remaining)
    if err != nil {
        panic(fmt.Errorf("could not decode storage info JSON: %w", err))
    }

    return remaining
}
interface RemainingSizeResp {
    total: number;
    remaining: number;
}

async function queryRemainingStorage(): Promise<RemainingSizeResp> {
    const url = `${SHARD_NODE_URL}/fso-info?info=remaining`;
    const res = await fetch(url, {
        method: 'GET',
        headers: { 'x-user-api-key': API_KEY }
    });

    if (res.status !== 200) {
        const body = await res.text();
        throw new Error(`Query remaining failed with status ${res.status}: ${body}`);
    }

    const remaining: RemainingSizeResp = await res.json();
    return remaining;
}

Response Format

Storage Usage JSON

{
  "total": 1073741824,
  "remaining": 536870912
}

total: Total storage capacity in bytes

remaining: Available storage space in bytes