Files in Chat, embeds, and secure deployments

Usable Chat can accept temporary attachments, stage structured data, generate files, or upload durable workspace assets. Embedded assistants can expose file capabilities to a parent host when explicitly configured. These paths have different persistence and authorization boundaries.

Do not assume that anything visible in a conversation is a durable workspace file.

Temporary Chat input

Files pasted, dropped, or selected in the composer become prompt context for the current turn or conversation. Their availability depends on the model, tools, and Chat configuration.

A Chat attachment does not automatically become:

• a workspace file;
• a memory fragment;
• a fragment attachment;
• durable output available in another conversation.

Use Files, data, and generated outputs for conversation workflows.

Stage or upload

For supported structured data, released Chat can offer:

• Stage for Chat for temporary analysis in the current data session;
• Upload to workspace for durable storage under workspace permissions.

Choose Stage for exploration and Upload when the file should be retained, searched, reused, or attached. Review inferred schema and metadata before either path.

Generated outputs

Sandbox files, generated documents, images, applets, and canvas outputs can be temporary. Download and move approved output into its durable system of record.

Before retaining generated output:

1. Verify its contents and sources.
2. Scan or review the file type.
3. Remove sensitive data.
4. Upload to the correct workspace if durable Usable storage is intended.
5. Attach it to a fragment that explains its provenance and limitations.

A polished file is not evidence that its content is correct or licensed for use.

Embedded assistant file gates

An embed configuration can hide or lock uploads and workspace-file access. The host must also enforce authorization, accepted file types, size, scanning, and retention.

A hidden upload control does not mean the user has no underlying workspace access; it means the current assistant experience does not expose that capability. Conversely, a visible control does not grant server authorization.

Released parent byte bridge

Usable Chat v1.173.0 includes a gated parent bridge for durable workspace file bytes where the embed configuration exposes workspace files to the parent. The released SDK surface can upload bytes and read authorized file bytes.

The upload path:

• requires an authenticated access token;
• caps decoded upload data at 50 MiB;
• stores the result in durable Usable file storage;
• blocks redirect-following in the released bridge;
• returns a file ID for later attachment;
• fails closed when workspace files are not exposed to the parent.

Do not place long-lived credentials or unrestricted file access in parent JavaScript. Authorize each user and file server-side.

Attach from an embed

A durable uploaded file is still independent until attached. Where enabled, normal Chat tool mode can use the file attachment tool, while restricted discussion or planning modes can remove mutating tools.

The host must verify:

• the current user owns or may access the file;
• the target fragment is in the allowed workspace;
• the operation is enabled for this embed and mode;
• repeated requests are idempotent.

See Integrate embedded Chat.

Public workspace review

Before uploading or attaching a file in a public or broad workspace, inspect:

• file body and embedded metadata;
• filename and tags;
• screenshots for emails, tokens, IDs, and private URLs;
• spreadsheets for hidden sheets or columns;
• documents for comments and revision history;
• whether the underlying license permits redistribution.

Prefer a redacted excerpt over a raw export.

Hosted Zone V1

Leaf-backed Hosted Zone V1 workspaces do not support file upload, search, retrieval, or attachment. Cloud must not silently receive private Leaf file payloads.

Handle HOSTED_ZONE_REQUIRED or UNSUPPORTED_IN_HOSTED_ZONE_V1 as a boundary instruction. Use a Cloud workspace for file workflows until Leaf file support is released, or keep the source in another approved system and reference it without exposing private data.

Troubleshooting

Upload is missing in Chat

Check the selected model, Expert, account, and embed feature configuration.

Parent upload is rejected

Confirm the workspace-file parent gate is enabled, the user is authenticated, the payload is within the 50 MiB bridge cap, and the target workspace is supported.

Generated file later disappears

Sandbox and generated URLs can be temporary. Download and retain important output promptly.

Leaf file call fails

This is expected in Hosted Zone V1. Do not retry against Cloud as a privacy fallback.

Related pages

• Files and assets in Usable
• Attach files to fragments
• Integrate file workflows
• Integrate embedded Chat