REST API v1 Base: api.transfilio.com

Build with the Transfilio API

Programmatic file transfers with enterprise-grade encryption. Upload, share, and track — all through a simple REST interface.

Get API Key Quick Start

<200ms avg

AES-256

99.9% uptime

terminal

# Upload a file
curl -X POST https://api.transfilio.com/v1/uploads \
-H "Authorization: Bearer zs_live_..." \
-F "file=@document.pdf"

# Response
{
"id": "upl_a1b2c3",
"status": "completed",
"share_url": "https://transfilio.com/s/abc123"
}

Quick Start

Get up and running in under 5 minutes

Get Your API Key

Make a Request

Add your key to the Authorization header as a Bearer token.

Upload & Share

Upload files, create share links, and track downloads — all via the API.

Your first request

# Check API status
curl https://api.transfilio.com/health

# Upload a file
curl -X POST https://api.transfilio.com/v1/uploads \
-H "Authorization: Bearer zs_live_..." \
-F "file=@report.pdf"

# Create a share link
curl -X POST https://api.transfilio.com/v1/links \
-H "Authorization: Bearer zs_live_..." \
-H "Content-Type: application/json" \
-d '{"upload_id": "upl_a1b2c3"}'

from transfilio import TransfilioClient

client = TransfilioClient("zs_live_...")

# Upload a file
upload = client.uploads.create("report.pdf")

# Create a share link
link = client.links.create(upload_id=upload.id)
print(link.url)  # https://transfilio.com/s/abc123

import { Transfilio } from "@transfilio/sdk";

const client = new Transfilio("zs_live_...");

// Upload a file
const upload = await client.uploads.create({
file: fs.readFileSync("report.pdf")
});

// Create a share link
const link = await client.links.create({
uploadId: upload.id
});
console.log(link.url); // https://transfilio.com/s/abc123

Authentication

All API requests require authentication via an API key

Bearer Token

Recommended

# In your request headers
Authorization: Bearer zs_live_a1b2c3d4e5f6

Standard OAuth-style Bearer token. Works with all HTTP clients.

X-API-Key Header

Alternative

# Custom header alternative
X-API-Key: zs_live_a1b2c3d4e5f6

Useful when Authorization header is already in use.

Security: Never expose keys in client-side code. Use environment variables and rotate regularly via POST /api/v1/api-keys/:id/rotate (24h grace period).

Base Configuration

Common settings for all API requests

Base URL

https://api.transfilio.com

Required Headers

Header	Value	Required
Authorization	Bearer {api_key}	Yes
Content-Type	application/json	Yes
Accept	application/json	Optional

Pagination

List endpoints return paginated results. Use page and per_page query parameters.

# Response includes pagination metadata
{
"data": [...],
"meta": {
"page": 1,
"per_page": 20,
"total": 142,
"total_pages": 8
}
}

API Reference

Complete endpoint reference with request and response details

GET /api/health Public

Returns API health status. No authentication required.

Response

{"status": "ok", "version": "1.0.0"}

Uploads

POST /api/v1/uploads Auth required

Upload a new file. Supports multipart form data up to your plan limit.

Parameters

file file required — The file to upload (multipart)

name string — Custom display name

expires_at datetime — Auto-expiry (ISO 8601)

Response

{"id": "upl_a1b2c3", "filename": "report.pdf", "size": 2048576, "status": "completed"}

GET /api/v1/uploads/:id Auth required

Retrieve upload details including status, size, and download count.

Response

{"id": "upl_a1b2c3", "filename": "report.pdf", "size": 2048576, "download_count": 12}

PATCH /api/v1/uploads/:id Auth required

Update upload metadata such as display name or expiration.

Parameters

name string — Updated display name

expires_at datetime — New expiry timestamp

Response

{"id": "upl_a1b2c3", "name": "Q1 Report", "expires_at": "2026-04-01T00:00:00Z"}

DELETE /api/v1/uploads/:id Auth required

Permanently delete an upload and all associated share links.

Response

{"deleted": true}

Share Links

POST /api/v1/links Auth required

Create a secure share link with optional password, expiry, and download limit.

Parameters

upload_id string required — ID of the upload to share

password string — Optional password protection

expires_at datetime — Link expiry timestamp

max_downloads integer — Maximum download count

Response

{"id": "lnk_x1y2z3", "url": "https://transfilio.com/s/abc123", "password_protected": false}

GET /api/v1/links/:id Auth required

Retrieve share link details including download statistics.

Response

{"id": "lnk_x1y2z3", "url": "https://transfilio.com/s/abc123", "download_count": 5}

DELETE /api/v1/links/:id Auth required

Revoke a share link immediately.

Response

{"deleted": true}

Transfers

GET /api/v1/transfers Auth required

List all transfers with pagination and filtering.

Parameters

page integer — Page number (default: 1)

per_page integer — Items per page (max: 100)

status string — Filter: completed, pending, expired

Response

{"data": [...], "meta": {"page": 1, "per_page": 20, "total": 142}}

Usage & Billing

GET /api/v1/usage Auth required

Get current billing period usage including storage, transfers, and API calls.

Response

{"transfers_count": 45, "api_calls_count": 892, "storage_bytes_used": 5368709120}

API Key Management

POST /api/v1/api-keys/:id/rotate Auth required

Rotate an API key with a 24-hour grace period for the old key.

Parameters

grace_period_hours integer — Grace period (default: 24, max: 72)

Response

{"new_key": "zs_live_newkey123", "old_key_expires_at": "2026-03-14T10:00:00Z"}

Rate Limits

Sliding window rate limiting ensures fair usage across all plans

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset: 1710345600

# When rate limited (HTTP 429):
Retry-After: 42 (seconds)

Limits by Plan

Plan	Req/Hour	Max File
Free	100	2 GB
Pro	1,000	5 GB
Business	5,000	20 GB
Enterprise	Custom	Unlimited

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.

Webhooks

Receive real-time notifications when events occur in your account

upload.completed

link.created

link.accessed

file.downloaded

link.expired

transfer.reviewed

Example Payload

POST https://your-app.com/webhooks/transfilio
X-Transfilio-Signature: sha256=a1b2c3...

{
"event": "file.downloaded",
"timestamp": "2026-03-13T14:30:00Z",
"data": {
"upload_id": "upl_a1b2c3",
"link_id": "lnk_x1y2z3",
"ip_address": "203.0.113.42"
}
}

Signature Verification

All payloads are signed with HMAC-SHA256. Verify the X-Transfilio-Signature header to ensure authenticity.

import hmac, hashlib

def verify_signature(payload, signature, secret):
expected = hmac.new(
    secret.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()
return hmac.compare_digest(
    f"sha256={expected}", signature
)

Error Handling

Consistent JSON error responses with actionable codes

Error Format

{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key",
"details": []
}
}

Status Codes

200 OK Request succeeded

201 Created Resource created successfully

400 Bad Request Invalid parameters or malformed request

401 Unauthorized Missing or invalid API key

403 Forbidden Insufficient permissions

404 Not Found Resource does not exist

422 Unprocessable Validation error with details

429 Rate Limited Too many requests — see Retry-After

500 Server Error Internal error — contact support

SDKs & Libraries

Official client libraries for popular languages

Python

pip install transfilio

JavaScript

npm i @transfilio/sdk

Ruby

gem install transfilio

Go

go get transfilio/go

SDK Example

from transfilio import TransfilioClient

client = TransfilioClient("zs_live_...")

# Upload with progress callback
upload = client.uploads.create(
"report.pdf",
on_progress=lambda p: print(f"{p}%")
)

# Create a password-protected link
link = client.links.create(
upload_id=upload.id,
password="secure123",
max_downloads=10
)
print(link.url)

import { Transfilio } from "@transfilio/sdk";

const client = new Transfilio("zs_live_...");

// Upload with progress
const upload = await client.uploads.create({
file: fs.readFileSync("report.pdf"),
onProgress: (p) => console.log(`${p}%`)
});

// Create a password-protected link
const link = await client.links.create({
uploadId: upload.id,
password: "secure123",
maxDownloads: 10
});
console.log(link.url);

require "transfilio"

client = Transfilio::Client.new("zs_live_...")

# Upload a file
upload = client.uploads.create(
file: File.open("report.pdf")
)

# Create a password-protected link
link = client.links.create(
upload_id: upload.id,
password: "secure123",
max_downloads: 10
)
puts link.url

Ready to integrate?

Get your API key and start building in minutes. Free tier includes 100 API calls per hour.

Get API Key — Free View Pricing

Build with the Transfilio API

Quick Start

Get Your API Key

Make a Request

Upload &amp; Share

Your first request

Authentication

Bearer Token

X-API-Key Header

Base Configuration

API Reference

Uploads

Share Links

Transfers

Usage & Billing

API Key Management

Rate Limits

Response Headers

Limits by Plan

Webhooks

Example Payload

Signature Verification

Error Handling

Error Format

Status Codes

SDKs & Libraries

Python

JavaScript

Ruby

Go

SDK Example

Ready to integrate?

Upload & Share