Skip to main content
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. 
curl https://your-spote-app.com/api/buckets \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

["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.
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.

​
Query parameters

​
buckets
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.

​
Response

200 OK — array of { tag: string, count: number } objects, sorted by count descending.
​
tag
string
required
The tag name without a # prefix.
​
count
number
required
The number of notes that have this tag.
curl "https://your-spote-app.com/api/tags?buckets=Work" \
  -H "Authorization: Bearer spote_YOUR_TOKEN"

[
  { "tag": "project", "count": 12 },
  { "tag": "meeting", "count": 8 },
  { "tag": "action-item", "count": 5 }
]