Files and DB Studio API

Files (the File Manager) and DB Studio (the database browser) each have their own JSON API under /api/v1. Their interfaces use it in the browser; your scripts can use it too, to upload a site, edit a file or run SQL as one hosting account.

GET /api/v1 on either app lists its addresses.

Note: these APIs work for one hosting account at a time and sign in as that account. To manage many accounts, use the token API with an hf_ token instead. hf_ tokens do not work here, and hff_ tokens do not work in the token API.

Signing in with an hff_ token

Scripts sign in with the account's username and password, adding "token": true. The answer holds a token that starts with hff_. Send it as Authorization: Bearer hff_… on every later request. No cookie and no CSRF token are needed.

F=https://fm.yourdomain.com
curl -s $F/api/v1/login -H 'Content-Type: application/json' \
     -d '{"username":"sarahbakes","password":"…","token":true}'

{
    "ok": true,
    "data": {
        "csrf": "…",
        "expires_in": 7200,
        "token": "hff_…",
        "user": {
            "email": "sarah@example.com",
            "staff": "",
            "username": "sarahbakes"
        }
    }
}

With two-factor login switched on, the first answer is {"twofa": true, "csrf": "…", "token": "hff_…"}. Send the code from the authenticator app (or a backup code) with that token within 5 minutes:

curl -s $F/api/v1/login/2fa -H "Authorization: Bearer hff_xxx" -H 'Content-Type: application/json' \
     -d '{"code":"123456"}'

Only hosting customers sign in to Files and DB Studio. Sign out with POST /api/v1/logout.

Answers

Every answer is {"ok": true, "data": …} or {"ok": false, "error": "…"}.

Files

path is always relative to the account's home folder, for example /web/example.com/public_html. name, from, to and items are names inside path. Paths cannot leave the home folder, and /web, /logs, /tmp, /.ssh and the home folder itself cannot be deleted or renamed.

For share links, hours is 1–720 (0 = never expires), an empty password means none, and max_downloads 0 means no limit. Anyone can open a share link at https://fm.yourdomain.com/s/<token> without signing in.

Example: upload and unpack a site

F=https://fm.yourdomain.com
T=hff_xxx
P=/web/example.com/public_html

curl -s -H "Authorization: Bearer $T" -F 'files[]=@site.zip' "$F/api/v1/files/upload?path=$P"
curl -s -H "Authorization: Bearer $T" -H 'Content-Type: application/json' $F/api/v1/files/unzip \
     -d "{\"path\":\"$P\",\"name\":\"site.zip\"}"
curl -s -H "Authorization: Bearer $T" "$F/api/v1/files?path=$P" | jq '.data.items[].name'
curl -s -H "Authorization: Bearer $T" -X POST $F/api/v1/logout

DB Studio

DB Studio opens only the account's own databases: MySQL/MariaDB (e=my), PostgreSQL (e=pg) and MongoDB (e=mg), named <username>_…, and only kinds the account's plan includes. Any other database answers 403 "You can’t open that database."

Limits: 30 seconds per statement, 1,000 rows per result, 200 statements per run, 1 MB of SQL text per run, and imports up to the server's import limit (128 MB unless the administrator changed it). A failed SQL statement is not an HTTP error: it is that result's error, with the line where the statement starts.

Example: run SQL

S=https://dbs.yourdomain.com
T=$(curl -s $S/api/v1/login -H 'Content-Type: application/json' \
      -d '{"username":"sarahbakes","password":"…","token":true}' | jq -r .data.token)

curl -s -H "Authorization: Bearer $T" -H 'Content-Type: application/json' $S/api/v1/sql \
     -d '{"e":"my","db":"sarahbakes_shop","sql":"SELECT id, name FROM products LIMIT 5;","limit":5}'

{
    "ok": true,
    "data": {
        "results": [
            {
                "n": 1,
                "line": 1,
                "sql": "SELECT id, name FROM products LIMIT 5",
                "ms": 2,
                "cols": [
                    {"name": "id", "type": "INT", "bin": false},
                    {"name": "name", "type": "VARCHAR", "bin": false}
                ],
                "rows": [
                    ["1", "Sourdough loaf"],
                    ["2", "Lemon drizzle"]
                ],
                "more": false
            }
        ],
        "failed": false
    }
}

Every change made through Files or DB Studio is written to the account's activity log.

Related

• API overview
• API: MongoDB