How to Use FileGrab with a Work Agent

Work agents often need to return a file that is too large for chat or that must remain available after the task ends. FileGrab gives the agent a narrow file-sharing path without giving it billing or admin access.

Point the Agent to One Text File

Give the agent this URL:

https://filegrab.link/agent-instructions.txt

That file contains the current signup, link, upload, retry, verification, download, and error-handling steps. It also tells the agent to use only the exact file path you supplied and never expose its API key or temporary upload URL.

It also separates two kinds of access. Any agent can inspect a public share link as JSON without an account. An agent that owns a link uses its mailbox-authorized API key to upload, update, replace, or delete files.

FileGrab does not currently publish a CLI, SDK, or MCP package. The instructions use the FileGrab REST API directly.

How Agent Signup Works

1. The agent submits a valid email address that it or you can access.
2. FileGrab sends a confirmation email.
3. The confirmation page creates or reuses the normal FileGrab account for that email.
4. The page displays an API key once.
5. The agent uses that key only for links, uploads, and files.

A new email starts with the normal Free account allowance. If that email already owns a Free or Pro FileGrab account, the agent uses that account’s current allowance.

Plus addressing works without merging identities. For example, name+work@example.com remains separate from name@example.com. Whether both addresses arrive in the same inbox depends on the email provider.

Seven-Day Email Confirmation

The API key remains tied to mailbox access. The agent must confirm the mailbox again every 7 days. This limits how long a key can keep working after the agent or user loses access to the email account.

If the key is lost, the agent can request standalone signup again. After email confirmation, FileGrab replaces the old standalone key and displays one new key.

What the Agent Can Do

With the default scopes, the agent can:

• create and manage its FileGrab links;
• upload an exact local file through simple or multipart upload;
• check upload status and safely retry completion;
• list and inspect its files;
• download its files for checksum verification;
• return the public FileGrab share URL;
• inspect public FileGrab share links as JSON without sending an API key;
• update or delete links and files owned by the connected account.

Agent uploads send the file bytes directly to FileGrab storage, so the file body does not pass through the FileGrab API. Completion verifies the stored byte count, checks exact abuse indicators when a bounded server checksum is available, records the file, and starts supported-file processing. Executable and installer filenames are currently unavailable through the agent API.

The key cannot add money, change a subscription, manage billing, use webhooks, or enter the admin interface.

Inspect a Public Link

The human share URL returns the FileGrab web page. To inspect the same public link as JSON, use the public API host and an Accept header:

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

No API key is required for a public link. A private link returns 404, an expired link returns 410, and a password-protected link asks for its password. The agent should respect those access results rather than trying to bypass them.

Add, Replace, or Delete an Owned File

An agent can add another file by using the normal upload sequence with an existing owned link ID.

FileGrab does not overwrite a file in place. To replace one safely, the agent uploads and verifies the new file first. It deletes the old file only after the replacement passed verification and only when the user asked for that deletion. This can briefly show both files, but it prevents a failed upload from removing the working copy.

Before deleting, the agent inspects the owned link and compares the link ID, file ID, filename, and size with the user’s request. After deletion, it lists or inspects the account again to prove that the intended resource is gone.

Free and Pro Accounts

Basic agent file operations use the account’s normal Free or Pro limits. They do not require a separate agent balance. FileGrab still enforces the account’s storage, link-count, file-size, and expiration limits.

A human account owner can also connect an agent from the FileGrab account page. That creates a separate owner-managed connection with its own key and allowed actions. One agent identity can therefore keep its own Free account and also connect to a different owner’s account.

Verified Upload Result

A careful agent should not stop after the file transfer. Files in the bounded checksum path can return a server SHA-256. For a larger file, the agent downloads the completed file and compares that SHA-256 with the local source. It should report:

• public share URL;
• link ID and file ID;
• filename and byte count;
• expiration and collaboration setting;
• local and server SHA-256 values when the server value is available;
• downloaded SHA-256 when download verification was requested;
• verification result;
• charged cents.

Free and Pro basic file operations return a zero agent-balance charge. If the byte count or checksum does not match, the agent must report verification failure instead of presenting the share as verified.

What to Tell Your Agent

Use a request like this:

Read https://filegrab.link/agent-instructions.txt. Upload the exact file at /absolute/path/to/file.zip to FileGrab, verify it, and give me the public share URL. Do not search for another file or expose credentials.

The exact-path instruction matters. It prevents the agent from searching neighboring folders or choosing a similarly named file.