Documentation

API quick start

Everything you need to upload your first file and share it. The API is versioned and lives under /api/v1.

Authentication

Every request needs an API token in the Authorization header. Tokens are created in the dashboard and can be limited to a single project, a folder, or read-only access.

Authorization: Bearer $NORTHFILES_TOKEN

Keep tokens out of client-side code and public repositories. Store them in environment variables and rotate them if they leak.

Upload a file

Send the file as multipart/form-data. The folder field is optional; folders are created automatically.

curl -X POST https://files.northfiles.tech/api/v1/files \
  -H "Authorization: Bearer $NORTHFILES_TOKEN" \
  -F "file=@./launch-video.mp4" \
  -F "folder=marketing/2026"

A successful upload returns the file record:

{
  "id": "fl_8k2m4q7x",
  "name": "launch-video.mp4",
  "folder": "marketing/2026",
  "size": 48213377,
  "content_type": "video/mp4",
  "visibility": "private",
  "created_at": "2026-10-30T09:15:00Z"
}

Large files

For files above the single-request limit, start a multipart upload with POST /api/v1/uploads, send parts to the URLs in the response, then call POST /api/v1/uploads/{id}/complete. Parts can be retried individually.

Create a private link

Private files are only reachable through signed links. Set an expiry in seconds and, optionally, a maximum number of downloads.

curl -X POST https://files.northfiles.tech/api/v1/files/fl_8k2m4q7x/links \
  -H "Authorization: Bearer $NORTHFILES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 86400, "max_downloads": 5}'

{
  "id": "ln_3v9t1c",
  "url": "https://files.northfiles.tech/s/ln_3v9t1c?sig=...",
  "expires_at": "2026-10-31T09:15:00Z",
  "max_downloads": 5
}

To revoke a link before it expires, send DELETE /api/v1/links/{id}.

List and delete files

# List files in a folder
curl "https://files.northfiles.tech/api/v1/files?folder=marketing/2026" \
  -H "Authorization: Bearer $NORTHFILES_TOKEN"

# Delete a file
curl -X DELETE https://files.northfiles.tech/api/v1/files/fl_8k2m4q7x \
  -H "Authorization: Bearer $NORTHFILES_TOKEN"

List responses are paginated. Pass the next_cursor value from a response as ?cursor= to get the next page.

Formats

You can store any file type. Some formats get extra handling:

Type	Extensions	Extra handling
Images	jpg, png, gif, webp, avif, svg	Thumbnails and previews
Video	mp4, webm, mov	Streaming playback, poster frame
Audio	mp3, m4a, ogg, wav, flac	Streaming playback
Documents	pdf, txt, md, csv, json	Inline preview, compression for text
Archives & other	zip, tar.gz, and anything else	Served as downloads

Limits

Limits depend on your plan. See pricing for storage and transfer.

Limit	Starter	Team	Business
Single-request upload	100 MB	100 MB	100 MB
Max file size (multipart)	2 GB	10 GB	50 GB
API requests per minute	60	300	1,000
Longest link expiry	7 days	30 days	No limit

When you exceed the request rate, the API responds with 429 Too Many Requests and a Retry-After header.

Errors

Errors use standard HTTP status codes and a JSON body with a machine-readable code:

{
  "error": {
    "code": "file_too_large",
    "message": "This file exceeds the single-request limit. Use a multipart upload."
  }
}

Questions about the API? Email our team — real people read every message.