Documentation
Features
URL Schemes

URL Schemes and Deep Links

Beanstats supports URL schemes (deep links) for automation and integration with external tools like Raycast, Alfred, Shortcuts, and Obsidian.

Overview

All URLs use the beanstats:// scheme and can be used to:

  • Navigate to specific brews or beans
  • Open forms with pre-selected data
  • Trigger scale connection or copy an individual brew as JSON
  • Quick-access freeze entries via NFC tags

Supported URLs

Brew Actions

URLAction
beanstats://brew/newOpen new brew form
beanstats://brew/new?style=EspressoOpen the espresso brew form
beanstats://brew/new?style=FilterOpen the filter brew form
beanstats://brew/new?bean={id}New brew with bean pre-selected
beanstats://brew/new?bean={id}&weight={grams}New brew with bean and weight pre-filled
beanstats://brew/new?bean={id}&weight={grams}&grind={text}New brew with bean, weight, and grind size pre-filled
beanstats://brew/new?method={id}New brew with the brew method preselected. Combine with bean={id}
beanstats://brew/{id}Navigate to brew detail
beanstats://brew/{id}/rateOpen rating sheet for brew
beanstats://brew/{id}/jsonCopy brew as JSON to clipboard
beanstats://brew/{id}/repeatOpen repeat brew form

Bean Actions

URLAction
beanstats://bean/newOpen new bean form
beanstats://bean/{id}Navigate to bean detail
beanstats://beansOpen the bean list

Freeze Actions

URLAction
beanstats://freeze/{tag}Open freeze entry (thaw form)

The freeze URL uses human-readable tags (e.g., ABC12) instead of UUIDs for convenience. This is the publicly supported deep link format.

Scale Actions

URLAction
beanstats://scale/connectStart scanning for Bluetooth scales
beanstats://scale/tareTare connected scale

Stats Actions

URLAction
beanstats://statsNavigate to Statistics view
beanstats://stats/todayOpen Statistics with the 7-day range selected. There is no dedicated daily view, and the app explains that choice

Caffeine Actions

URLAction
beanstats://caffeineOpen the caffeine dashboard

Export Actions

Bulk export URLs such as beanstats://export/brews?format=json are not implemented. Opening one shows a warning that points you to Settings. No file is created, and CSV or date-filter query parameters do not enable an export.

Use Export in Settings, or the JSON export Shortcuts, instead.

Entity IDs

Entity IDs (for beans, brews, methods) are UUID strings. These IDs:

  • Are stable across app launches, reinstalls, and iCloud sync
  • Are human-readable standard UUID format
  • Are URL-safe

Example ID: 550e8400-e29b-41d4-a716-446655440000

You can find entity IDs in JSON exports or webhook payloads.

Use Cases

iOS Shortcuts

Create Shortcuts for common actions:

  • Quick brew logging with your default bean
  • Scale connection shortcut
  • Open the Statistics screen

Example Shortcut action:

  1. Add “Open URLs” action
  2. Enter beanstats://brew/new
  3. Run to open the brew form

Raycast / Alfred

Create quick launcher commands:

# Start a new brew
open "beanstats://brew/new"

# Check your stats
open "beanstats://stats"

# Connect to scale
open "beanstats://scale/connect"

Obsidian Integration

Link to specific beans or brews in your coffee notes:

Today I brewed [Ethiopian Yirgacheffe](beanstats://bean/550e8400-e29b-41d4-a716-446655440000)

NFC Predose Tags

Write NFC tags with pre-dosed bean weight for instant brew setup:

beanstats://brew/new?bean=550e8400-e29b-41d4-a716-446655440000&weight=18.0

For beans you grind ahead of time, the tag can carry a grind size as well. It is free-form text, such as Medium-fine or 22 clicks, and is percent-encoded in the URL:

beanstats://brew/new?bean=550e8400-e29b-41d4-a716-446655440000&weight=18.0&grind=22%20clicks

Weight is always stored in grams in the URL regardless of the app’s display unit system. The grind parameter is optional, and tags written without it keep working exactly as before. See Bean Tracking for how to write these tags.

QR Codes for Freeze Tags

Generate QR codes for freeze entries to attach to frozen coffee bags:

  1. Create a freeze entry in Beanstats
  2. Note the tag (e.g., ABC12)
  3. Generate a QR code for beanstats://freeze/ABC12
  4. Attach to your frozen coffee bag
  5. Scan to quickly open the thaw form

Alternatively, use NFC tags - see Bean Tracking for details.

Related

  • Siri Shortcuts - Voice commands and Shortcuts app integration
  • Webhooks - Push notifications to external services
  • Export - Data export functionality
Siri ShortcutsNotifications