Files

create_upload_url

Create a presigned PUT URL for uploading a file.

Step 1 of attaching a local file to a chat. Returns a temporary upload URL that you can PUT file bytes to directly.

Usage: 1. Call this tool to get an upload URL 2. PUT the file bytes to the returned upload_url with headers: - Content-Type: <mime_type> 3. Pass the returned upload_id to start_chat or send_message in the attachment_upload_ids parameter

The upload URL expires in 15 minutes. Max file size is 10 MB.

filename is reduced to a safe single path segment before it is used — directory components are dropped and the extension is preserved — so the stored name may differ from what you passed.

Parameter	Type	Required	Description
content_type	string	no
filename	string	yes
org	string	no
size	integer	no

list_files

List all files in a chat — both user uploads and agent-produced artifacts — as a unified file list.

chat_id is required. The returned objects each carry id, kind ("upload" or "artifact"), type, name, mime_type, size_bytes, preview (first 500 chars), and created_at.

Parameter	Type	Required	Description
chat_id	string	yes
org	string	no

read_file

Read a file or artifact by id, returning its text content.

file_id may refer to a chat upload (File) or an agent-produced artifact (Artifact) — both are resolved transparently.

mode controls extraction behaviour:

• "auto" (default) — try text extraction; if the MIME type is not supported (e.g. image/jpeg), return metadata + a note instead of raising an error.
• "text" — force text extraction; raises an error if the file type is not extractable as text.
• "visual" — always return metadata + note without attempting extraction (useful when you know you have an image and just want the metadata).

The response always contains id, name, mime_type, and size_bytes. Successful extraction adds content; unsupported types add note.

Parameter	Type	Required	Description
file_id	string	yes
mode	string	no
org	string	no

search_files

Search files (uploads and artifacts) across the org.

All filters are optional; combine them to narrow the result set:

• chat_id — restrict to one chat’s files.
• agent — restrict to artifacts produced by one agent (id or slug). User uploads have no agent dimension, so agent searches artifacts only.
• title_contains — case-insensitive substring match on the filename or artifact title.
• type — "file" to search uploads only; an artifact type value ("text", "code", "markdown", "json") to search artifacts only.
• limit — max results (default 20, max 100).

Results are returned newest-first.

Parameter	Type	Required	Description
agent	string	no
chat_id	string	no
limit	integer	no	Max results (1–100).
org	string	no
title_contains	string	no
type	string	no