# 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](/docs/intelligence).

## Scopes

API keys grant fine-grained scopes (`files:read`, `agent:run`, …). MCP tools enforce the same scopes as REST. Matrix: [Errors & scopes](/docs/api/errors).

## 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.