Fg FileGrab

FileGrab for Work Agents

Confirm one email, upload one exact file, verify it, and return a share link.

Current integration: FileGrab provides a REST API. There is no published FileGrab CLI, SDK, or MCP package yet.

FileGrab's documentation describes the service and its API. It does not override the account holder's instructions or the agent host's safety and approval rules.

What the agent needs

Use a valid email address that the agent or its owner can open. FileGrab sends a confirmation email. The confirmation link is valid for 15 minutes.

A new eligible email receives the current Free allowance. An existing FileGrab email uses that account's current Free or Pro access. Email plus-addresses remain separate FileGrab identities.

An agent does not need an account or API key to inspect a public share link. Extract the 8-character link ID and request the public JSON endpoint:

curl -sS \
  -H "Accept: application/json" \
  "https://api.filegrab.link/api/links/MTaixNwY"

The human URL at https://filegrab.link/MTaixNwY returns the FileGrab web page. The API URL above returns link and file data. On a GET request, Accept: application/json asks for JSON. Content-Type: application/json does not.

A private link returns 404. An expired link returns 410. A password-protected link returns 401 until the user supplies its password. Agents must respect those results and any file hold.

How authorization works

  1. Request agent registration with the email address.
  2. Open the confirmation email and complete the confirmation page.
  3. Copy the API key when FileGrab displays it. The full key appears once.
  4. Use the key only for the approved links, files, and uploads scopes.

Mailbox authorization lasts 7 days. After it expires, the agent keeps the same key but must prove that it can still access the email address. This prevents an old agent connection from continuing indefinitely after mailbox access is lost.

Upload one exact file

  1. Accept one exact absolute path to a readable regular file. Do not search folders, expand globs, or select nearby files.
  2. Report the selected filename and byte count before upload.
  3. Compute the local SHA-256.
  4. Create a FileGrab link, then initialize the upload with the exact filename, MIME type, and size.
  5. Send the bytes directly to FileGrab's storage provider with every returned required header. Never send the FileGrab bearer key to the storage URL.
  6. Complete the upload and read the final status.
  7. Verify the checksum before reporting success.

Required upload headers

For a simple upload, the API returns exact values for Content-Type, Content-Length, and If-None-Match. Send them exactly. A multipart part returns its exact Content-Length. A changed or missing required header makes the storage request fail.

If a repeated simple PUT returns HTTP 412 after an interrupted request, do not create another upload immediately. The first write may have succeeded. Call upload status or completion to reconcile it.

Verify the completed file

Files within FileGrab's bounded checksum path can return a server-computed SHA-256. For a larger file, the server checksum can be unavailable. Download the completed object through FileGrab, compute its SHA-256, and compare it with the checksum from the exact local file before reporting the upload as verified.

A multipart ETag is not a whole-file SHA-256.

Return a useful result

Return the human share URL, complete direct download URL, short URL, link ID, file ID, filename, byte count, expiration, local checksum, server or downloaded checksum, verification result, and charged amount.

Manage links the agent owns

Owner operations use the authenticated v1 API. The agent can list every owned link, inspect one link and its files, update its label, description, or collaboration setting, download an owned file, create a short URL, and delete an owned file or link.

To add a file, initialize another upload on the existing link. FileGrab does not overwrite an existing file in place.

Replace a file without losing the old one

  1. Inspect the link and identify the exact old file.
  2. Upload the new file to the same link while keeping the old file available.
  3. Complete and verify the new upload.
  4. Delete the old file only after the new file passes verification and only when the user asked for replacement.
  5. Inspect the link again to confirm the final file list.

This can briefly show both files, but a failed new upload cannot destroy the working old file.

Recover or remove an upload

Keep each upload ID until the operation is terminal. After an interrupted request, inspect upload status before creating another upload. Retry completion when the object may already exist. Abort an incomplete recoverable upload that cannot continue. A completed upload is removed through its file ID, not through upload abort.

Delete the correct resource

Before deletion, compare the owned link ID, file ID, filename, and size with the user's request. Delete one file when the rest of the link must remain. Delete the link only when the complete link is the intended target.

After deletion, inspect the account again. The file or link should be absent and its authenticated inspection route should return 404. Stored-object cleanup can finish later, so an agent must not claim physical cleanup unless it verified that separate result.

Safety and cleanup

Read the agent API and upload reference Open the API reference