Documentation

Authentication

Every request needs your API key. All responses are JSON.

X-Api-Key: ak_your_key

A bearer token is also accepted: Authorization: Bearer ak_your_key

Send the key as a header only — never in the query string, where it would be recorded in server and proxy logs.

Response format

{
  "success": true,
  "data": { ... },
  "meta": { ... }        // list endpoints only
}

Errors return success:false with an error object and the matching HTTP status code.

Endpoints

Method	Endpoint	Description
GET	/account	Account the key belongs to
GET	/account/storage	Storage usage and plan limits
GET	/files	List files (per_page, folder, search)
GET	/files/{uuid}	File details
PATCH	/files/{uuid}	Rename a file
DELETE	/files/{uuid}	Delete a file
POST	/uploads	Start an upload
POST	/uploads/batch	Start several uploads at once
POST	/uploads/{uuid}/parts/{n}	Get an upload link for one chunk
POST	/uploads/{uuid}/complete	Finish an upload
GET	/uploads/{uuid}	Upload status (supports resuming)
DELETE	/uploads/{uuid}	Cancel an upload
POST	/uploads/remote	Upload from one or more URLs
GET	/uploads/remote/{uuid}	Remote upload status

Uploading a file

File data goes straight to storage, so large files never pass through this server.

1. Start the upload

curl -X POST https://filespay.net/api/v1/uploads \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"video.mp4","size":52428800,"mime":"video/mp4"}'

Returns mode (single or multipart), chunk_size, total_parts and the session uuid. For single mode a put_url is included — send the whole file there with PUT and skip to step 3.

2. Send each chunk

# get a link for chunk 1
curl -X POST https://filespay.net/api/v1/uploads/{uuid}/parts/1 \
  -H "X-Api-Key: ak_..."

# send the bytes straight to storage, keep the ETag from the response
curl -X PUT --data-binary @chunk1 "<url from above>" -D -

3. Finish

curl -X POST https://filespay.net/api/v1/uploads/{uuid}/complete \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"part_number":1,"etag":"abc..."}]}'

The response includes the shareable download link:

{
  "success": true,
  "data": {
    "uuid": "…",
    "name": "video.mp4",
    "size_bytes": 52428800,
    "download_url": "https://yourdomain.com/aB3xY9k2"
  }
}

Uploading from a URL

The transfer runs in the background — the request returns immediately.

curl -X POST https://filespay.net/api/v1/uploads/remote \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/video.mp4"]}'

Poll /uploads/remote/{uuid} for the status; once it reports completed the response carries the download_url as well.

Rate limits & errors