Skip to content

HTTP API

PutFS speaks plain HTTP. Any client that can issue PUT, GET, HEAD, and DELETE works without any extra SDK.

Authentication

The native API uses a two-header model enforced by nginx:

Header Purpose
X-Api-Key Key ID
X-Api-Secret Key secret

The key is then matched against a method/URI pattern to scope what it can do. See Auth for the full pattern reference.

Endpoints

Method Pattern Action
PUT /:path Upload an object
GET /:path Download an object
HEAD /:path Check if an object exists + metadata
DELETE /:path Delete an object
GET /:path/ List objects in path prefix (trailing slash)

Examples

The examples below assume an auth key putfs_demo:demo and a server at http://localhost:8000.

Upload

curl -X PUT \
  -H "X-Api-Key: putfs_demo" \
  -H "X-Api-Secret: demo" \
  http://localhost:8000/my-dataset/hello.txt \
  -d "hello world"

Upload a file from disk:

curl -X PUT \
  -H "X-Api-Key: putfs_demo" \
  -H "X-Api-Secret: demo" \
  --data-binary @./report.pdf \
  http://localhost:8000/my-dataset/report.pdf

Download

curl \
  -H "X-Api-Key: putfs_demo" \
  -H "X-Api-Secret: demo" \
  http://localhost:8000/my-dataset/hello.txt

Check existence

curl -I \
  -H "X-Api-Key: putfs_demo" \
  -H "X-Api-Secret: demo" \
  http://localhost:8000/my-dataset/hello.txt

List

A trailing slash on the path lists the prefix:

curl \
  -H "X-Api-Key: putfs_demo" \
  -H "X-Api-Secret: demo" \
  http://localhost:8000/my-dataset/

GET / lists from the root.

Listing returns paths relative to the listed prefix and accepts these query params:

Param Description
glob Filter by glob pattern (e.g. *.pdf)
exclude_prefix Skip keys starting with this prefix
depth Maximum directory depth 
curl \
  -H "X-Api-Key: putfs_demo" \
  -H "X-Api-Secret: demo" \
  "http://localhost:8000/my-dataset/?glob=*.pdf&depth=2"

Delete

curl -X DELETE \
  -H "X-Api-Key: putfs_demo" \
  -H "X-Api-Secret: demo" \
  http://localhost:8000/my-dataset/hello.txt

Status codes

Code Meaning
200 OK (GET, LIST)
201 Created (PUT)
204 No content (DELETE, PUT to existing key under default WORM)
401 Missing or invalid key/secret
403 Key not authorized for this method/path; or filesystem EPERM/EACCES/EROFS (WORM, readonly)
404 Object not found
409 Conflict – PUT on an existing key under WORM strict mode
422 Unprocessable – PUT body digest does not match the value captured from the URL (see content-addressed verification)
423 Locked – another writer is currently streaming to this key; retry with backoff
507 Insufficient storage (ENOSPC) – disk is full

See WORM for the PUT/DELETE behavior under write-once-read-many semantics.