Set this up once and you can say "Hey Siri, add Upkeep task" from anywhere on your phone — locked screen, walking the property, hands full of feed bags. Siri prompts you for the task, you say it, the task lands in Upkeep with Hawkeye picking the right category, and Siri reads the confirmation aloud. Three actions total, about 5 minutes to wire up.
What you'll build
A 3-action chain in Apple's Shortcuts app. Here's the end state so you know what you're aiming for:
Action 1: Ask for Input — Siri prompts "What's the task?"
Action 2: Get Contents of URL — POSTs your spoken text to Upkeep with your API token
Action 3: Speak Text — reads Hawkeye's confirmation back to you
1 Generate your API token
In the Upkeep app: User menu → Profile → Access tokens → Generate. Label it something like iPhone Shortcut. Copy the token immediately — it only shows once. If you lose it, revoke it from the same screen and generate a new one.
⚠ Treat the token like a password. Anyone with it can create / edit data in your Upkeep account. You can revoke it any time from Profile → Access tokens.
2 Open the Shortcuts app + start a new one
Shortcuts is built into iOS — search your home screen for Shortcuts. Open it, tap the + button in the top-right to start a new shortcut. iOS drops you straight into the action picker.
You're in the right place when: you see a search bar at the top labeled Search for apps and actions with categories like Scripting, Media, Web listed below. Don't pick from the categories — type into the search bar for each action.
3 Add the 3 actions, one at a time
For each action: type its name into the search bar, tap the matching result to add it to your shortcut, then configure the fields. After each action, tap the + at the bottom of the shortcut editor to bring the action picker back for the next.
Action 1 — Ask for Input
Type Ask for Input in the action picker. Tap it. Configure:
Prompt:What's the task?
Input Type: Text (usually the default)
Action 2 — Get Contents of URL
Type Get Contents of URL in the action picker. Tap to add. Then tap the Show More chevron (▼) to expand all its fields.
⚠ Common trap: while the URL field has focus, do NOT tap the variable picker (the tag icon above the keyboard) — it'll drop a blue "Ask for Input" pill into the URL, breaking it. The URL field should be plain text only, no blue pills. If you see one, position the cursor right after it and backspace once to delete it.
Method: change from GET to POST
Headers — tap Add new header. iOS labels the two fields Key and Text:
Key
Authorization
Text
Bearer paste-your-token-here
In the Text field: type Bearer (with a trailing space!), then paste the token you copied in Step 1. Final value reads Bearer upk_live_abc123...
Request Body — change the type to Form (not JSON, not File). Then tap Add new field:
Key
text
For the Text field next to text, tap inside it, then tap the variable picker in the keyboard toolbar (small tag icon) → choose Ask for Input. A blue pill labeled "Ask for Input" lands in the field. This is where the pill belongs — not in the URL.
No Content-Type header needed — iOS auto-sets application/x-www-form-urlencoded for Form bodies, which is exactly what the server expects.
Action 3 — Speak Text
Type Speak Text in the action picker. Tap to add. In its input field, tap the variable picker → pick Contents of URL (the output of Action 2). A blue "Contents of URL" pill lands in the field.
Because the URL ends with ?as=text, the server returns a plain-text confirmation directly (no JSON wrapper). Speak Text reads it verbatim — no dictionary parsing needed.
4 Name it (and Siri auto-picks up the trigger)
At the top of the shortcut editor — above your three actions — tap the current name (probably auto-generated like "Get Contents of URL") and rename it to Add Upkeep task. This phrase becomes your Siri trigger automatically.
On iOS 16+, you can immediately say "Hey Siri, add Upkeep task" — no separate "Add to Siri" step required. The shortcut name = the Siri phrase.
If you want a different voice phrase from the name: tap the settings icon (⚙ or ⓘ) at the top of the editor → Add to Siri → record your phrase.
5 Test before going hands-free
Tap the ▶ Play button at the bottom of the shortcut editor. The "What's the task?" prompt appears. Type something like "feed the chickens" → Done. After a second, your phone speaks the confirmation aloud — something like "Added 'Feed the chickens' to your Livestock list, due today." Open Upkeep → My Stuff to see it.
Once the manual play test works, say it for real: "Hey Siri, add Upkeep task."
Troubleshooting (the hard-earned lessons)
🔧 "Bad Request" from Apache after running the shortcut
Maddening one — Apache 400 page comes back even though the URL looks right. Means iOS Shortcuts is sending a malformed request, often from cached state during editing. The fix that worked for us: strip the shortcut to absolute bare bones and rebuild upward.
Change the URL temporarily to https://upkeep.softwerks.pro/ (no path)
Change Method to GET
Delete the Authorization header (red minus button)
Delete the body Form field (red minus)
Run. Should speak back the homepage HTML.
Now add back ONE thing at a time, running between each: change method to POST → add Authorization header → change URL back to /api/quick-task?as=text → add the form body
The piece that breaks is the piece to look at. Often the rebuild itself clears the iOS-internal cruft and everything just works.
🔧 "Unsupported URL"
A blue variable pill snuck into the URL field. The URL must be plain text only. Tap the URL field, position cursor next to the pill, backspace once to delete the entire pill as a unit. Re-paste the URL clean.
🔧 "Conversion Error: couldn't convert from Rich Text to Dictionary"
This is why we use ?as=text on the URL. iOS Shortcuts can't always parse JSON responses cleanly. The ?as=text query parameter tells the server to return plain text instead — bypassing the issue entirely. If you ever see this error, check the URL ends with ?as=text.
🔧 "Not logged in" / 401 error
Token's wrong, expired, or revoked. Common causes:
Missing the trailing space after Bearer in the Authorization Text field
Token has a hidden newline (re-paste it)
Token was revoked in Profile → Access tokens
Token was copied from the wrong banner (you only see the plaintext value the moment you generate it; if you've closed the modal, you have to revoke and generate a new one)
🔧 Siri doesn't trigger the shortcut
Long-press the shortcut on the Shortcuts home → Add to Siri → re-record the phrase. Siri's voice match is flaky for some phrases — "add Upkeep task" works better than "create a task" (which Siri may interpret as "search the web for create a task").
🔧 Request seems to succeed but no task appears in Upkeep
Open Upkeep → Hawkeye chat → ask "what did I add recently?" If Hawkeye sees the task, it landed. If not, the request didn't reach the server. The Speak Text reply is the source of truth — if it spoke a confirmation, the task is in Upkeep.
🔧 "Allow Untrusted Shortcuts" prompt
Doesn't apply when you build the shortcut yourself (only when importing from someone else). If you do see it: Settings → Shortcuts → toggle "Allow Untrusted Shortcuts."
Revoke this token any time from Profile → Access tokens. Generating a new token doesn't invalidate the old one — you have to revoke explicitly. If your phone gets lost or stolen, revoke immediately.