# 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).
- Or **Full access** if you'll upload and mutate.
- Optionally restrict `bucketIds`.

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

Details: [API keys](/docs/api-keys).

## 2. List workspaces and buckets

```bash
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:

```bash
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):

```bash
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)

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

Requires scope `agent:run` and agent enabled on the bucket. Guide: [Bucket agent](/docs/agent).

## Prefer MCP?

Skip curl entirely — [install the MCP server](/docs/mcp/install) and use `list_buckets` / `search_files` / `ask_agent` from your agent client.