> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spote.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Buckets and Tags API endpoints

> GET /api/buckets lists all your folder names. GET /api/tags returns tags with note counts, optionally filtered by bucket. Useful for building integrations.

The buckets and tags endpoints let you fetch the current organizational structure of your notes — useful for building integrations, populating filter dropdowns, or auditing what you have. Both endpoints are read-only and reflect the current state of your notes in real time.

***

## GET /api/buckets

List all bucket names for your account. A bucket is created automatically when you save a note with a new bucket name.

### Response

**200 OK** — `string[]` — array of bucket name strings, in no guaranteed order.

```bash theme={null}
curl https://your-spote-app.com/api/buckets \
  -H "Authorization: Bearer spote_YOUR_TOKEN"
```

```json theme={null}
["Inbox", "Work", "Research", "Claude Code", "Blog"]
```

***

## GET /api/tags

List all tags for your account, along with the number of notes each tag appears in. Results are sorted by count descending. You can filter to tags within specific buckets.

<Note>
  Tags in API responses do **not** include the `#` prefix. The `#` is added automatically when tags are displayed in the web app or returned by MCP tools.
</Note>

### Query parameters

<ParamField query="buckets" type="string[]">
  Filter tags to only those appearing in notes within the specified buckets. Pass multiple values to include several buckets: `?buckets=Work&buckets=Research`. If omitted, tags from all buckets are returned.
</ParamField>

### Response

**200 OK** — array of `{ tag: string, count: number }` objects, sorted by `count` descending.

<ResponseField name="tag" type="string" required>
  The tag name without a `#` prefix.
</ResponseField>

<ResponseField name="count" type="number" required>
  The number of notes that have this tag.
</ResponseField>

```bash theme={null}
curl "https://your-spote-app.com/api/tags?buckets=Work" \
  -H "Authorization: Bearer spote_YOUR_TOKEN"
```

```json theme={null}
[
  { "tag": "project", "count": 12 },
  { "tag": "meeting", "count": 8 },
  { "tag": "action-item", "count": 5 }
]
```