API key → first list and search in minutes·View as Markdown

Quickstart

Get from zero to a listed bucket and a semantic search in a few minutes.

1. Create an API key

In the app: Settings → API keys → Create.

Prefer the Agent read-only preset for exploration (files:read, agent:run, download).
Prefer Upload + read to upload without tags/mkdir/move. After PUT, call MCP complete_upload (Upload flow).
Use Full access only if the agent must mutate (tags, move, automations).
Optionally restrict bucketIds.

Copy the secret once (fr_live_...). It is not shown again.

2. List workspaces and buckets

export FR_KEY=fr_live_...
export BASE=https://www.file.rocks/api/v1

curl -s -H "Authorization: Bearer $FR_KEY" \
  "$BASE/workspaces" | jq

# pick a workspace id, then:
curl -s -H "Authorization: Bearer $FR_KEY" \
  "$BASE/workspaces/$WS/buckets" | jq

3. List or search files

Keyword search:

curl -s -H "Authorization: Bearer $FR_KEY" \
  "$BASE/workspaces/$WS/buckets/$BUCKET/files?search=drone&limit=20" | jq

Semantic search (requires intelligence embeddings on the bucket):

curl -s -H "Authorization: Bearer $FR_KEY" \
  "$BASE/workspaces/$WS/buckets/$BUCKET/files?search=sunset%20over%20water&semantic=1&limit=10" | jq

4. Ask the bucket agent (optional)

curl -s -X POST \
  -H "Authorization: Bearer $FR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"find photos of sunsets"}' \
  "$BASE/workspaces/$WS/buckets/$BUCKET/agent" | jq

Requires scope agent:run and agent enabled on the bucket. Guide: Bucket agent.

Prefer MCP?

Skip curl entirely — install the MCP server and use list_buckets / search_files / ask_agent from your agent client. To upload, follow Upload flow.