Temporary file sharing, private links and one-time downloads

What file sharing does

File sharing stores one file temporarily and gives you a download link. Use it to hand a build artifact, log or test fixture to a person or another system without setting up storage. Files are private by default, expire after one hour unless you choose otherwise, and can be limited to a number of downloads, including a single one.

Upload a file

POST /api/files with the raw bytes as the body and Content-Type: application/octet-stream. Put the URL-encoded filename (up to 150 characters, no directories) in X-File-Name. The file must be nonempty and at most 10 MiB.

curl -X POST 'https://socket.help/api/files?maxDownloads=1' \
  -H 'Content-Type: application/octet-stream' \
  -H 'X-File-Name: report.txt' \
  --data-binary @report.txt

# 201 Created
{
  "id": "FILE_ID",
  "managementToken": "MANAGEMENT_TOKEN",
  "expiresAt": "2026-10-27T13:00:00.000Z",
  "visibility": "private",
  "accessVersion": "ACCESS_VERSION",
  "accessToken": "ACCESS_TOKEN",
  "name": "report.txt",
  "size": 5,
  "downloadUrl": "https://socket.help/files/FILE_ID",
  "remainingDownloads": 1
}

Download a file

GET /files/{id} returns the file as an attachment (application/octet-stream with a Content-Disposition filename). Each successful GET uses one download. Private files need the access token in X-Access-Token or Authorization: Bearer; workspace credentials with resources:read can also download their own private files.

Two requests do not use a download: HEAD /files/{id}, which returns the size in Content-Length, and GET /files/{id}/info, which returns id, name, size, expiresAt, visibility and remainingDownloads. Requests with a missing or wrong access token also use no download.

curl https://socket.help/files/FILE_ID/info \
  -H "X-Access-Token: $ACCESS_TOKEN"

curl -o report.txt https://socket.help/files/FILE_ID \
  -H "X-Access-Token: $ACCESS_TOKEN"

One-time and limited downloads

When the final allowed download completes, the stored contents are deleted and their storage is released. Later downloads return 404 with "File unavailable, expired, or download limit reached." The file’s metadata stays readable with GET /api/files/{id} (remainingDownloads is 0) until you delete it or it expires.

Manage a file

GET /api/files/{id} returns name, size, visibility, accessVersion, expiresAt, uses, downloadUrl and remainingDownloads. DELETE /api/files/{id} removes the file immediately. A management token cannot download a private file; downloads always need the access token or workspace access.

• Downloads are always forced attachments with a sandboxing Content-Security-Policy.
• Files are not scanned for malware. Share only files you trust.
• When too many file transfers are in progress, the API returns 503 with Retry-After: 5.
• Through MCP, upload_temporary_file and download_temporary_file handle files up to 64 KiB as Base64. Use HTTP for larger files.