API

Everything you can do in the dashboard for a server, you can also do over HTTPS: create servers, add SFTP users, upload and download files, and set up event listeners. The full reference is an OpenAPI 3.1 spec. Import it into Postman, Insomnia or a client generator.

API keys

Go to Settings → API keys and click Create API key. Only owners and admins can do this. Copy the key: it starts with cf_ and is shown once. Keys belong to the organization, so they keep working when the person who made them leaves the team.

Pick the access level when you create the key:

Send the key in the Authorization header:

curl https://cloudfile.dev/api/v1/instances \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY"

Revoke a key under Settings → API keys. Requests with it fail right away.

Examples

Create a server (admin key) and wait until it runs:

curl -X POST https://cloudfile.dev/api/v1/instances \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "partner-uploads", "region": "nbg1"}'
# {"id":"8c1f…"}

curl https://cloudfile.dev/api/v1/instances/8c1f… \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY"
# {"id":"8c1f…","status":"running","connection":{"host":"nbg1.cloudfile.dev","sftp_port":22064,…},…}

Add an upload-only SFTP user. The generated password is in the response, once:

curl -X POST https://cloudfile.dev/api/v1/instances/8c1f…/users \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "acme", "auth": "password", "permissions": ["list", "upload", "create_dirs"], "quotaBytes": 5368709120}'
# {"id":"…","password":"…"}

Upload a file into a user’s folder. Send the raw bytes as the body:

curl -X PUT "https://cloudfile.dev/api/v1/instances/8c1f…/files/upload?user=acme&path=in/report.csv" \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY" \
  --data-binary @report.csv

Get a download link valid for five minutes:

curl "https://cloudfile.dev/api/v1/instances/8c1f…/files/url?user=acme&path=in/report.csv" \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY"
# {"url":"https://…","expiresAt":1767225600}

Ask a partner for files with an upload link that expires in a week (share links):

curl -X POST "https://cloudfile.dev/api/v1/instances/8c1f…/share-links" \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY" -H "Content-Type: application/json" \
  -d '{"user":"acme","path":"in","kind":"upload","expiresInDays":7}'
# {"id":"…","url":"https://cloudfile.dev/u/…",…}

Read recent file activity, newest first. Pass next_before back as before for the next page:

curl "https://cloudfile.dev/api/v1/instances/8c1f…/events?limit=100" \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY"

Read the audit log (who changed what, from the dashboard or with a key; admin keys only). Pass nextCursor back as cursor:

curl "https://cloudfile.dev/api/v1/audit-log?limit=50" \
  -H "Authorization: Bearer $CLOUDFILE_API_KEY"

To react to uploads as they happen, create a webhook listener instead of polling: POST /api/v1/instances/{id}/listeners.

Errors

Errors use HTTP status codes and a JSON body: {"error": "message"}.

Limits

Each key can make 300 requests a minute. Uploads through the API are limited to 5 GB per file. Use SFTP for larger files.