Developer documentation

Secure Send API

A REST API and an MCP server for delivering a file to a person as a one-time, encrypted, auto-deleting download link. Base URL https://fileseal.uk/v1.

Quickstart (REST)

1. Create a FileSeal account and, in Settings → API keys, generate a key. The full secret is shown once; store it as FILESEAL_API_KEY.
2. Encrypt your file client-side (see Encryption), base64-encode the result, and create the send:

curl -X POST https://fileseal.uk/v1/sends \
  -H "Authorization: Bearer $FILESEAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "link",
    "expiryHours": 48,
    "files": [{
      "filename": "contract.pdf",
      "mimeType": "application/pdf",
      "ciphertextBase64": "<[12-byte IV][AES-GCM ciphertext], base64>"
    }]
  }'

The response gives you the claim link, expiry and seal id:

{
  "success": true,
  "id": "2c693e7c-...",
  "claimUrl": "https://fileseal.uk/receive/2c693e7c-...",
  "deliveryMode": "link",
  "expiresAt": "2026-06-18T11:01:26.947Z",
  "filesCount": 1,
  "totalSize": 81234
}

In link mode the response is the base URL only; append the key fragment yourself (claimUrl + "#k=" + keyFragment) and relay the full link, so FileSeal never receives the key. In email mode, passrecipientEmail and a per-fileencryptionKey and FileSeal emails the recipient.

Quickstart (MCP server)

The fileseal-send MCP server gives an AI agent a tool to deliver files securely, and does the client-side encryption for you. Register it in your MCP client config and set FILESEAL_API_KEYin the environment:

{
  "mcpServers": {
    "fileseal-send": {
      "command": "node",
      "args": ["mcp/fileseal-send/index.mjs"],
      "env": {
        "FILESEAL_API_KEY": "${FILESEAL_API_KEY}",
        "FILESEAL_API_BASE_URL": "https://fileseal.uk"
      }
    }
  }
}

It exposes three tools:

• secure_send: encrypt a file and create a send; returns the share link (with #k= in link mode).
• send_status: status and audit events for a send.
• revoke_send: revoke before download.

The server ships in the FileSeal repository (mcp/fileseal-send); a published npm package and a hosted remote MCP option are on the roadmap.

Authentication

Every request needs Authorization: Bearer $FILESEAL_API_KEY. Keys are issued and revoked in the dashboard; a revoked key stops working immediately (401). Treat a key like a password: it grants the ability to create sends on your account.

Endpoints

Encryption

Files are encrypted client-side before upload, as [12-byte random IV] + AES-GCM-256 ciphertext, then base64-encoded into ciphertextBase64. Use one fresh AES-256 key per send.

Limits

• File types: PDF, DOC, DOCX, TXT, JPG, PNG.
• Up to 10 files per send; up to 10 MB per file and 50 MB per send (enforced on the encrypted bytes). In Milestone 1 the whole request is sent inline, so it is bounded by the ~4.5 MB platform body limit until the scoped client-upload lands.
• Expiry 1–168 hours (default 48). Rate limit: 100 sends per 24 hours per key.

Errors

• 401: missing or invalid key.
• 403: recipient domain not allow-listed (when configured).
• 400: invalid body, disallowed type or oversize file.
• 429: rate limit exceeded (Retry-After header).
• 503: authentication backend unavailable.

FAQ