File Security API Behavior

File-writing APIs accept protected content into private quarantine and return an accepted or pending result. Do not treat a successful upload request as immediate file availability.

Console file payloads and timeline attachment metadata can include the following fields. These names are not a universal shape for every file API:

Field	Meaning
scanStatus	pending, scanning, retrying, clean, infected, unavailable, or not_required
available	Whether a protected consumer may read bytes or create a URL now
scanErrorCode	A stable, non-sensitive machine error when applicable
threatName	An optional sanitized scanner-provided threat label

When an availability flag is present, only use content when available is true. Pending, infected, unavailable, and missing protected scan records are fail-closed. Download and signed-URL endpoints do not expose quarantine locations.

Conversation text and pending attachment metadata can be persisted before scanning completes. Whether the agent processes that text immediately also depends on its active input-security rules and emergency state; a pending or unsupported attachment can keep a required Block inspection unavailable. When the batch reaches terminal verdicts, the platform persists a hidden conversation-bound event and requests a wake-up through the normal pending-work path.

For replacement writes, pendingMalwareScan describes the candidate generation while the existing activeMalwareScan can remain available. The candidate atomically becomes active only after clean promotion.

Scanner configuration endpoints under /system-settings/api/file-security/ are session-authenticated, CSRF-protected, and restricted to system administrators. They never serialize the mTLS private key.

Supported REST workflow

REST Files provides gated multipart upload/replacement, status, bounded listing, exact-generation downloads and retained immutable attachment downloads. It shares service-credential authority, safe-retry replay and application-request attachment UUIDs. Upload alone creates no runtime work; a clean old generation remains readable while a replacement waits.

Remote MCP uploads

upload_agent_file accepts agent_id, an absolute filespace path, base64 content_base64, and optional mime_type and overwrite. It enforces the deployment's MAX_FILE_SIZE (10 MiB by default, measured as decoded bytes). Invalid base64, inaccessible agents, path conflicts without overwrite, and unreadable content return tool errors.

A protected upload returns an accepted result such as:

{
  "status": "pending_scan",
  "message": "File accepted for malware scanning.",
  "path": "/uploads/brief.txt",
  "node_id": "30f34d22-243c-471c-9242-a4fc0d1b8a3",
  "filename": "brief.txt",
  "scan_status": "pending",
  "available": false
}

The human-readable message may vary. This result uses snake_case scan_status and does not yet contain resource_uri. An immediately readable upload instead returns status: "ok" with its resource URI and file metadata.

list_agent_files returns bounded file metadata and resource URIs plus scan_status, available, availability, and active/pending generation objects. Optional limit is 1–100; supplying limit or cursor opts into bounded pagination (100 if continuing with only a cursor). Calls omitting both preserve the legacy complete inventory/order. Follow next_cursor with the same principal/resource/page size within 24 hours. A resource URI is a locator, not a guarantee of readable content. Poll bounded listings for the intended active generation, then use resources/read or read_agent_resource; failures remain closed while scanning or when content is rejected. If a file remains blocked, inspect its status in the product or ask the deployment administrator to inspect scanner health. Do not repeatedly overwrite the file to try to clear a verdict.

For reliable messaging, upload first, wait until the resource is readable, then send attachment_file_paths. Inline send_agent_message.attachments supports up to 10 files but can fail to attach a newly quarantined upload. A failed inline call can therefore leave an uploaded file behind; reconcile the filespace before retrying. Existing-file replacement can leave the older clean generation readable while its replacement is scanning, so confirm you are attaching the intended content.

Resource reads and attachment copies

Files use agent://agents/{agent_uuid}/files/{node_uuid} and message attachments use agent://agents/{agent_uuid}/attachments/{attachment_uuid}. Follow returned URIs rather than substituting storage URLs. Query strings and fragments are not supported. Reads require agents:read and recheck the agent, resource association, malware availability, size, and stored checksum when present.

resources/read returns contents with UTF-8 text for supported text types, or base64 blob for binary/non-UTF-8 content. read_agent_resource also returns structured resource metadata and native MCP image content for PNG, JPEG, GIF, or WebP. Other types use an embedded resource block. Clients should inspect mimeType and the actual content variant.

Published message attachments retain their own stored bytes. Replacing a filespace file later does not replace the copy already attached to a message; an attachment URI and a filespace URI can therefore refer to different generations. list_agent_files returns the entire default filespace, including directories, without pagination or a path filter. The current MCP catalog has no general rename/delete file tool.