# Agent API

`POST /workspaces/{workspaceId}/buckets/{bucketId}/agent` · `agent:run`

Bucket must have intelligence enabled with the **agent** feature on.

```bash
curl -s -X POST \
  -H "Authorization: Bearer $FR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"sunset drone clips from italy"}' \
  https://www.file.rocks/api/v1/workspaces/$WS/buckets/$BUCKET/agent
```

Body: `{ "query": "..." }` (alias `q`).

Returns an answer plus file cards from keyword + semantic search, summarized by a Replicate LLM. No web tools — bucket scope only.

Guide: [Bucket agent](/docs/agent) · MCP: `ask_agent`.