API Documentation — Files App

API Reference

The Files App API is organized around REST. JSON is returned by all responses, including errors.

Base URL

https://files-app.com/api/v2

All API requests must be authenticated and made over HTTPS. Requests made over plain HTTP will be rejected. All responses are returned in JSON format.

Authentication

Authenticate your API requests by including your API key in the Authorization header.

Authorization Header

Authorization: Bearer sk_live_your_api_key_here

API keys can be generated in your dashboard under Settings → API Keys. Keep your keys secure — do not share them in client-side code.

Rate Limits

API requests are rate limited per API key.

Plan	Limit
Free	100 req/hour
Pro	1,000 req/hour
Team	10,000 req/hour

Rate limit information is included in the response headers of every API request:

X-RateLimit-Limit — Maximum requests per hour
X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the limit resets

If you exceed the rate limit, you will receive a 429 response:

429 Too Many Requests json

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please retry after 2025-01-15T11:00:00Z."
  }
}

POST /api/v2/upload

Upload a file. Files are encrypted server-side by default.

Name	Type	Required	Description
`file`	File	Yes	The file to upload (multipart/form-data)
`folder_id`	string	No	Target folder ID
`encrypt`	boolean	No	Enable encryption (default: true)

Request bash

curl -X POST https://files-app.com/api/v2/upload \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@document.pdf" \
  -F "encrypt=true"

Response json

{
  "id": "file_abc123",
  "name": "document.pdf",
  "size": 2048576,
  "encrypted": true,
  "created_at": "2025-01-15T10:30:00Z"
}

POST /api/v2/chunks

Upload large files in chunks. Three-step process: initialize, upload chunks, complete.

Step 1: Initialize

POST /api/v2/chunks/init

Name	Type	Required	Description
`filename`	string	Yes	Name of the file being uploaded
`total_size`	integer	Yes	Total file size in bytes
`total_chunks`	integer	Yes	Total number of chunks

Request bash

curl -X POST https://files-app.com/api/v2/chunks/init \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"filename": "large-video.mp4", "total_size": 524288000, "total_chunks": 100}'

Response json

{
  "upload_id": "upl_xyz789",
  "chunk_size": 5242880,
  "expires_at": "2025-01-15T11:30:00Z"
}

Step 2: Upload Chunks

POST /api/v2/chunks

Name	Type	Required	Description
`upload_id`	string	Yes	Upload session ID from init step
`chunk_index`	integer	Yes	Zero-based index of this chunk
`data`	binary	Yes	Chunk binary data (multipart/form-data)

Request bash

curl -X POST https://files-app.com/api/v2/chunks \
  -H "Authorization: Bearer sk_live_..." \
  -F "upload_id=upl_xyz789" \
  -F "chunk_index=0" \
  -F "data=@chunk_000"

Response json

{
  "chunk_index": 0,
  "received": true
}

Step 3: Complete

POST /api/v2/chunks/complete

Name	Type	Required	Description
`upload_id`	string	Yes	Upload session ID from init step

Request bash

curl -X POST https://files-app.com/api/v2/chunks/complete \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "upl_xyz789"}'

Response json

{
  "id": "file_abc123",
  "name": "large-video.mp4",
  "size": 524288000,
  "encrypted": true,
  "created_at": "2025-01-15T10:30:00Z"
}

GET /api/v2/files/{id}

Retrieve file metadata or download the file.

Name	Type	Required	Description
`download`	boolean	No	Set to true to download the file binary

Request bash

curl https://files-app.com/api/v2/files/file_abc123 \
  -H "Authorization: Bearer sk_live_..."

Response json

{
  "id": "file_abc123",
  "name": "document.pdf",
  "size": 2048576,
  "encrypted": true,
  "mime_type": "application/pdf",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

GET /api/v2/files

List all files in your account or a specific folder.

Name	Type	Required	Description
`folder_id`	string	No	Filter by folder ID
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 20, max: 100)
`sort`	string	No	Sort by: name, size, created_at

Request bash

curl "https://files-app.com/api/v2/files?page=1&per_page=20&sort=created_at" \
  -H "Authorization: Bearer sk_live_..."

Response json

{
  "files": [
    {
      "id": "file_abc123",
      "name": "document.pdf",
      "size": 2048576,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 20
}

DELETE /api/v2/files/{id}

Permanently delete a file.

Request bash

curl -X DELETE https://files-app.com/api/v2/files/file_abc123 \
  -H "Authorization: Bearer sk_live_..."

Response json

{
  "deleted": true
}

POST /api/v2/share

Create a shareable link for a file.

Name	Type	Required	Description
`file_id`	string	Yes	ID of the file to share
`password`	string	No	Password to protect the share link
`expires_in`	integer	No	Link expiry time in hours
`allow_download`	boolean	No	Allow file download (default: true)

Request bash

curl -X POST https://files-app.com/api/v2/share \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"file_id": "file_abc123", "password": "s3cret", "expires_in": 168, "allow_download": true}'

Response json

{
  "id": "share_def456",
  "url": "https://files-app.com/s/abc123",
  "password_protected": true,
  "expires_at": "2025-01-22T10:30:00Z",
  "allow_download": true
}

GET /api/v2/sync

Get file changes since a given timestamp. Used for client synchronization.

Name	Type	Required	Description
`since`	string	Yes	ISO 8601 timestamp to fetch changes from
`folder_id`	string	No	Filter changes by folder ID

Request bash

curl "https://files-app.com/api/v2/sync?since=2025-01-15T10:00:00Z" \
  -H "Authorization: Bearer sk_live_..."

Response json

{
  "changes": [
    {
      "id": "file_abc123",
      "action": "created",
      "timestamp": "2025-01-15T10:30:00Z"
    },
    {
      "id": "file_def456",
      "action": "modified",
      "timestamp": "2025-01-15T10:35:00Z"
    }
  ],
  "cursor": "cur_xyz",
  "has_more": false
}

Errors

Files App uses conventional HTTP response codes. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx range indicate a server error.

Error Response Format json

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked."
  }
}

Status	Code	Description
400	`bad_request`	Invalid request parameters
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	Insufficient permissions
404	`not_found`	Resource not found
413	`file_too_large`	File exceeds plan limit
429	`rate_limited`	Too many requests
500	`internal_error`	Internal server error

SDKs & Libraries

Official client libraries are coming soon. In the meantime, community-maintained SDKs are available:

Python python

# pip install filesapp
from filesapp import Client

client = Client("sk_live_...")
file = client.upload("document.pdf")

Node.js javascript

// npm install @filesapp/sdk
const FilesApp = require('@filesapp/sdk');

const client = new FilesApp('sk_live_...');
const file = await client.upload('./document.pdf');

Go go

// go get github.com/filesapp/go-sdk
client := filesapp.NewClient("sk_live_...")
file, err := client.Upload("document.pdf")

All SDKs are open source and available on GitHub.