# API overview

Agent-readable REST API for workspaces, buckets, files, intelligence, and the bucket agent.

Prefer [MCP](/docs/mcp) in agent clients. Use REST when you need raw HTTP.

## Base URL

```
https://www.file.rocks/api/v1
```

## Auth

```
Authorization: Bearer fr_live_...
```

Create keys in Settings → API keys (dogfood / intelligence allowlist only). Scopes are enforced per route. Keys may restrict `bucketIds`.

→ [Auth](/docs/api/auth) · [API keys guide](/docs/api-keys)

## Resources

| Area | Docs |
|------|------|
| Workspaces | [api/workspaces](/docs/api/workspaces) |
| Buckets | [api/buckets](/docs/api/buckets) |
| Files | [api/files](/docs/api/files) |
| Intelligence | [api/intelligence](/docs/api/intelligence) |
| Agent | [api/agent](/docs/api/agent) |
| Shares & transfers | [api/shares-transfers](/docs/api/shares-transfers) |
| Errors & scopes | [api/errors](/docs/api/errors) |

## Quick map

- `GET /workspaces` — `workspaces:read`
- `GET /workspaces/{workspaceId}/buckets` — `buckets:read`
- `GET .../buckets/{bucketId}/files?prefix=&search=&tag=&semantic=1` — `files:read`
- `PATCH .../files/{fileId}` — tags / description — `files:write`
- `POST .../files/presign-upload` · `presign-download` — `files:upload` / `files:download`
- `GET|PATCH .../intelligence` — `intelligence:read|write`
- `POST .../intelligence/backfill` — `intelligence:write`
- `POST .../agent` — `agent:run`
- `GET .../shares` · `GET .../transfers`

## Example

```bash
curl -s -H "Authorization: Bearer $FR_KEY" \
  https://www.file.rocks/api/v1/workspaces/$WS/buckets | jq
```