Workspaces, buckets, files, intelligence, MCP·View as Markdown

Concepts

Workspace

A billing and membership boundary. API keys belong to a workspace. Most routes are nested under /workspaces/{workspaceId}/....

Bucket

A connected storage target (hosted or bring-your-own S3-compatible). Files live in a bucket. Keys may be restricted to a subset of bucketIds.

Shadow file

file.rocks keeps an inventory row (ShadowFile) for each object: key, size, content type, tags, description, embedding status. List/search/agent APIs operate on this inventory.

Intelligence

Opt-in per bucket: vision tags, descriptions, CLIP embeddings, similarity, and the bucket agent. Platform-paid via Replicate by default. See File intelligence.

Scopes

API keys grant fine-grained scopes (files:read, agent:run, …). MCP tools enforce the same scopes as REST. Matrix: Errors & scopes.

MCP vs REST

	MCP	REST
Best for	Agents / IDEs	Scripts, backends, raw HTTP
Auth	Bearer `fr_live_...`	Same
Surface	Tools over shared libs	`/api/v1` JSON

Both hit the same data model — no second inventory.