What this surface is for
Voice endpoint
Portal profile
HomeKit
Siri and Apple Shortcuts bridge for a full Siri-to-Tater round-trip, with per-device sessions, Shortcut-friendly JSON, and optional auth protection.
Voice endpoint
v1.0.1
5 settings
50 Verbas
Behavior in the current codebase
- Provides a lightweight HTTP bridge for Siri and Apple Shortcuts workflows.
- Designed for Shortcut-driven voice loops where Siri captures speech, posts JSON to Tater, then speaks the reply back aloud.
- Maintains per-device conversation sessions instead of treating every request as stateless.
- Supports optional API key protection so Shortcuts must send X-Tater-Token when enabled.
- Good fit for Apple-first households that want voice access without a full chat client.
Direct portal support
50 current Verbas advertise direct support for this surface.
Configuration schema
-
Require API Key
select
Require X-Tater-Token on HomeKit API requests.
Key: API_AUTH_ENABLED Default: false Options: true, false -
API Key
password
Shared API key expected in the X-Tater-Token header when auth is enabled.
Key: API_AUTH_KEY -
Legacy Auth Token (optional)
password
Backward-compatible fallback token if API Key is empty.
Key: AUTH_TOKEN -
Session TTL (seconds)
number
How long to keep a Siri session alive.
Key: SESSION_TTL_SECONDS Default: 3600 -
Bind Port
number
TCP port for the Tater ↔ Siri / Shortcuts bridge
Key: bind_port Default: 8789
Shortcut guide
How to connect Siri and Apple Shortcuts to this portal.
These notes focus on the Shortcut flow, session handling, optional auth, and the Siri voice round-trip.
ShortcutSiriQuick start
Premade shortcut
A ready-made Apple Shortcut already exists for the HomeKit bridge.
- You can start from the premade Ask Tater shortcut instead of building the flow by hand.
- It is a good baseline even if you later customize the session_id, endpoint IP, or auth header.
Dictate TextPOST JSONSpeak Text
Build the shortcut
The common Shortcut flow is Dictate Text -> Get Contents of URL -> Get Dictionary Value -> Speak Text.
- Create a shortcut such as Ask Tater, then add Dictate Text with stop listening set to After Pause.
- Use Get Contents of URL to POST JSON to http://YOUR-TATER-IP:8789/tater-homekit/v1/message with text and session_id fields.
- Extract the reply key from the JSON response, then feed it into Speak Text so Siri or a HomePod reads it back.
session_idX-Tater-TokenPer-device memory
Session IDs and auth
Each device should use its own session_id, and protected bridges can require the X-Tater-Token header.
- Use a stable session_id such as iphone, ipad, or bedroom_homepod so conversations do not mix between devices.
- If API auth is enabled in Tater HomeKit settings, add an X-Tater-Token header inside the shortcut request.
- The bridge keeps short Siri-friendly session history in Redis using the configured session TTL and history limits.
HomePodHandoffSiri phrase
HomePod behavior
HomePods can use the same shortcut flow by handing off through the iPhone that owns the shortcut.
- After adding the shortcut to Siri, phrases like Ask Tater or Talk to Tater can trigger the round-trip hands-free.
- If the shortcut lives on the iPhone, a HomePod can hand off the shortcut execution and still speak Tater's reply.
- This gives Apple households a practical voice surface without needing a separate Apple-native Tater app.
Built-in APIs
HTTP endpoints exposed by this portal.
When API auth is enabled, requests must include X-Tater-Token with the configured portal API key.
POST
/tater-homekit/v1/message
Main Siri / Shortcuts message endpoint.
Accepts JSON with text plus an optional session_id, enforces X-Tater-Token when API auth is enabled, and returns a plain reply field sized for Siri speech.