Files

Files live in the phone's shared storage under /sdcard, the storage that apps such as the file manager, the camera and the browser's downloads use. /storage/emulated/0 is another name for the same place. Files stay on the phone when it parks, and every file request needs the phone to be ready.

Each request names its file or directory in the path query parameter:

• A path is /sdcard or a path inside it, or the same under /storage/emulated/0, with at most 1024 characters.
• A path can't contain . or .. segments.
• URL-encode the path when it has spaces or other special characters.

A file can be at most 4 MB (4,000,000 bytes), whether you upload it or download it.

Upload a fileCopy Anchor Link

Send the file's bytes as the request body, not as JSON or a form:

curl -X PUT "https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/files?path=/sdcard/Download/report.pdf" \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @report.pdf

The path must end with the file's name. Directories on the way that don't exist yet are created. The response is 201 Created with the path and the size in bytes. A body over 4 MB fails with 413 payload_too_large.

Download a fileCopy Anchor Link

curl -o report.pdf "https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/files/content?path=/sdcard/Download/report.pdf" \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

The response is the file itself, as application/octet-stream, with its name in the Content-Disposition header. A path with no file fails with 404 file_not_found, and a path to a directory fails with 400 validation_failed, whose next tells you how to list it instead. A file over 4 MB fails with 413 payload_too_large. When the file's size isn't known in advance, a download that passes 4 MB is cut off instead.

List a directoryCopy Anchor Link

curl "https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/files?path=/sdcard/Download" \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

Without path, the request lists /sdcard. The response has the path and a data list with one entry for each file or directory:

A directory that doesn't exist fails with 404 file_not_found. A path to a file fails with 400 validation_failed, whose next points to the download request for it.

Delete a fileCopy Anchor Link

curl -X DELETE "https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/files?path=/sdcard/Download/report.pdf" \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

The response has the path and "deleted": true. A path with nothing at it fails with 404 file_not_found, and the storage root itself can't be deleted.

Directories are not supported by this endpoint: they return 400 validation_failed without deleting any contents. To delete a folder, open the Files app on the phone. In the console, choose Open Files in the Files tab, then delete the folder on the phone screen.

From the CLI and the SDKCopy Anchor Link

When the CLI's push target ends with /, the local file keeps its name in that directory.