file.rocksdocs
Menu

Full tool catalog with args and returns·View as Markdown

MCP tools

Tools wrap shared v1 logic (not HTTP loopback). Unless noted, workspaceId defaults to the API key's workspace.

Upload (read this first)

A PUT to the bucket does not list the file. Call complete_upload after PUT. Scope is files:upload, not files:write. Full steps: Upload flow.

  1. presign_upload
  2. PUT bytes to the returned URL
  3. complete_upload with the same key

Do not call REST upload-complete from an agent (Cloudflare 1010). If the object is already in the bucket, call complete_upload only. After register, use file.url to display when it is not null. Use presign_view to display without a public CDN. Use presign_download only when the user should save a file.

Catalog

ToolScopeMaps to
list_workspacesworkspaces:readGET /workspaces
list_bucketsbuckets:readGET .../buckets
list_filesfiles:readindex listing (not a live bucket list)
get_filefiles:readGET .../files/{fileId}
search_filesfiles:readkeyword + semantic
similar_filesfiles:readsimilar neighbors
ask_agentagent:runbucket agent
update_filefiles:writetags / description (not upload register)
get_intelligenceintelligence:readconfig + progress
start_backfillintelligence:writestart / resume / pause
presign_viewfiles:downloadinline/viewable GET URL
presign_downloadfiles:downloadattachment GET URL
presign_uploadfiles:uploadPUT URL, then you must complete_upload
complete_uploadfiles:uploadregister object (required after PUT)
create_folderfiles:writemkdir
list_automationsautomations:readGET .../automations
get_automationautomations:readGET .../automations/{id}
create_automationautomations:writePOST .../automations
update_automationautomations:writePATCH .../automations/{id}
delete_automationautomations:writeDELETE .../automations/{id}
rename_automationautomations:writePOST .../automations/{id}/name
list_automation_conflictsautomations:readGET .../automations/conflicts
get_trash_settingsautomations:readGET .../trash
set_trash_enabledautomations:writePATCH .../trash
trash_filesfiles:deletePOST .../files/trash
move_filesfiles:writePOST .../files/move
list_suggestionssuggestions:readGET .../suggestions
accept_suggestionssuggestions:writePOST .../suggestions accept
dismiss_suggestionssuggestions:writedismiss
sync_suggestionssuggestions:writesync
auto_accept_suggestionssuggestions:writeauto-accept
list_pagespages:readGET .../pages
get_pagepages:readGET .../pages/{id}
create_pagepages:writePOST .../pages
update_pagepages:writePATCH .../pages/{id}
delete_pagepages:writeDELETE .../pages/{id}
add_page_blockpages:writePOST .../pages/{id}/blocks
update_page_blockpages:writePATCH .../blocks/{id}
delete_page_blockpages:writeDELETE .../blocks/{id}
run_page_blockpages:readblock results (paginated)

Common args

Most bucket tools take:

  • bucketId (required)
  • workspaceId (optional; defaults to key workspace)

Automations

  • list_automations: conflicts?
  • create_automation / update_automation: kind?, name?, scope?, priority?, rules?, enabled?
  • Trash TTL rule config: { ttlDays, minBytes?, maxBytes?, extensions? }

Trash / moves

  • trash_files: bucketId, keys[]
  • move_files: bucketId, moves: [{ fromKey, toKey }]
  • set_trash_enabled: trashEnabled boolean

Suggestions

  • list_suggestions: kind?, bucketId?, sync?, countOnly?
  • accept_suggestions: kind, ids[], optional keep/name maps
  • dismiss_suggestions: ids[]

list_files / search_files

  • prefix?, parentPrefix?, search?, tag?
  • semantic? (boolean)
  • limit?, offset?
  • Reads the file.rocks index. Objects missing after PUT need complete_upload first.
  • Each file includes url / thumbnailUrl when the bucket has a public domain. Use url to display images. For an attachment, call presign_download.

get_file

  • fileId
  • Same url / thumbnailUrl fields as list_files.

ask_agent

  • query (string)

update_file

  • fileId, tags?, description?
  • Requires files:write. Does not register uploads.

start_backfill

  • action: start | pause
  • estimateToken? (required for start)

presign_upload

  • key, contentType?
  • Returns a PUT URL plus next pointing at complete_upload. After PUT, call complete_upload. See Upload flow.

complete_upload

  • key, size?, etag?, contentType?, contentHash?
  • Requires files:upload (Upload + read preset is enough). Does not set tags — that is update_file / files:write.
  • Also registers an object that is already in the bucket but missing from list_files.
  • Returns file.url (public CDN) when the bucket has publicDomain. Use that URL to display the image. For a save-as-file link, call presign_download.

presign_view

  • key? or fileId?
  • Viewable URL (Content-Disposition: inline). Browser displays the file.
  • purpose?: preview (1 hour, default) or embed (7 days)
  • expiresIn?: seconds, 60–604800, overrides purpose default
  • If the bucket has publicDomain, returns that durable URL (durable: true)
  • See Upload flow.

presign_download

  • key? or fileId?
  • Attachment URL (Content-Disposition: attachment). Browser saves the file.
  • Same purpose / expiresIn as presign_view
  • Always signed (even when publicDomain exists). Cannot be non-expiring.
  • See Upload flow.

create_folder

  • key (folder path)

Resources

Doc markdown is exposed as MCP resources (file.rocks://docs/... and/or https .md URIs). For upload, read file.rocks://docs/mcp/upload (also /docs/mcp/upload.md).

Errors

Missing scope or bucket allowlist → tool error with a clear message (same semantics as REST 403).

A Cloudflare 1010 on REST upload-complete is Bot Fight Mode blocking the agent HTTP client. It is not a missing-scope error. Call MCP complete_upload instead.

MCP tools · file.rocks docs