iOS Shortcuts

Capture events from your iPhone by POSTing JSON to Trove's HTTP ingest module. Shortcuts are a client of the generic ingest endpoint — not a Trove module.

Prerequisites

1. Build Trove and configure [modules].paths — see Quick Start.
2. HTTP gateway listening on [http].listen (default :8080 in core trove.toml). Ingest routes are declared in the http-ingest module manifest.
3. Your phone can reach the ingest URL (local network, Tailscale, or HTTPS on the public internet).

Import a Shortcut

Signed .shortcut files live in examples/ios-shortcuts/signed/. A maintainer signs them on a Mac with iCloud signed in and commits them to the repo (hosted CI cannot sign).

If a link 404s, signed files have not been committed yet. Use the unsigned shortcuts in unsigned/ (regenerated by python3 examples/ios-shortcuts/generate_unsigned.py) or follow the manual recipes below. Unsigned files are the canonical path for development and CI; signed imports require a maintainer Mac with iCloud.

To import:

1. Open a .shortcut file on your iPhone (AirDrop, Files, or Safari).
2. Tap Add Shortcut.
3. Enter your Trove ingest URL when prompted, e.g. https://trove.example.com/ingest/shortcuts (full path, HTTPS on cellular).
4. Run the Shortcut once to verify, then enable Share Sheet or other triggers.

Endpoint contract

POST https://<host>/ingest/shortcuts
Content-Type: application/json

{ ... }

• The :source path segment (shortcuts) becomes the event source field.
• Body must be valid JSON (object, array, or primitive).
• Optional top-level fields peeled into event metadata: type, time (RFC3339), blob_ref. Everything else stays in payload.
• Default event type if omitted: trove://type/http/ingest/received/1.
• Success: 204 No Content.

Network and auth

By default HTTP ingest has no authentication. When [http.auth].validator is set (e.g. module.http-gateway.bearer), add an Authorization header with Bearer <token> to ingest and blob requests. See network auth planning. For a home server, common setups are:

• Local network — http://192.168.x.x:8080/ingest/shortcuts (Wi‑Fi only; Shortcuts may block plain HTTP on cellular).
• Tailscale — HTTPS via your tailnet hostname (recommended for phone capture).
• Public HTTPS — reverse proxy with TLS in front of :8080.

See network auth planning for auth options once exposing beyond a trusted tailnet.

Photo attachments

For images and other binary content from the share sheet:

1. PUT https://<host>/blobs with raw image bytes → receive { "blob_ref": "sha256-..." }
2. POST https://<host>/ingest/shortcuts with JSON including blob_ref and metadata (type, title, content_type, etc.)

Binary content must not be inlined in the ingest JSON body.

Share Sheet with photo

1. Trigger: Share Sheet (enable URLs, text, images).
2. If Shortcut Input is an image:
   • Get Contents of URL — Method PUT, URL https://YOUR_HOST/blobs, Request Body: Shortcut Input.
   • Get Dictionary from Input (from response JSON) → blob_ref.
3. Dictionary — type: trove://type/shortcuts/share/saved/1, plus blob_ref (if image), text, url, title, content_type as available.
4. Get Contents of URL — Method POST, URL https://YOUR_HOST/ingest/shortcuts, Headers Content-Type: application/json, Request Body: Dictionary.

Text-only and URL-only share captures skip step 2 and POST JSON directly (see below).

Event type conventions

Use explicit type values so MCP search can find captures later:

Example payloads: examples/ios-shortcuts/payloads/.

Quick capture (classify later)

Use the capture-classifier module when you want to store data before choosing a semantic type:

1. Trigger: App icon or Siri.
2. Ask for Input — multiline text.
3. Dictionary — text: Provided Input.
4. Get Contents of URL — Method POST, URL https://YOUR_HOST/capture/shortcuts, Headers Content-Type: application/json, Request Body: Dictionary.

Classify later via MCP classify_event or POST /classify.

Manual recipes

Build your own Shortcut if you prefer full control.

Share Sheet → Trove (text or URL)

1. Trigger: Share Sheet (enable URLs, text, images).
2. Dictionary — type: trove://type/shortcuts/share/saved/1, text: Shortcut Input.
3. Get Contents of URL — Method POST, URL https://YOUR_HOST/ingest/shortcuts, Headers Content-Type: application/json, Request Body: Dictionary.

For images, use the photo flow above.

Quick Note

1. Trigger: App icon or Siri.
2. Ask for Input — multiline text.
3. Dictionary — type: trove://type/shortcuts/note/created/1, text: Provided Input.
4. Get Contents of URL — POST JSON body (Dictionary).

URL Bookmark

1. Trigger: Share Sheet (Safari).
2. Dictionary — type: trove://type/shortcuts/url/saved/1, url: Shortcut Input.
3. Get Contents of URL — POST JSON body.

Location Check-in

1. Trigger: App icon.
2. Get Current Location.
3. Ask for Input — optional label.
4. Dictionary — type: trove://type/shortcuts/location/checked/1, location fields.
5. Get Contents of URL — POST JSON body.

Limitations

• No authentication by default — enable [http.auth].validator or use localhost / a trusted tailnet. See network auth.
• 10 MiB request body limit (max_body_bytes in HTTP ingest manifest).
• Photos in Share Sheet — use the photo flow; the importable Shortcut captures text/URL metadata by default.

Verify capture

curl -sS -o /dev/null -w "%{http_code}\n" \
  -X POST "http://localhost:8080/ingest/shortcuts" \
  -H "Content-Type: application/json" \
  -d '{"type":"trove://type/shortcuts/note/created/1","text":"hello from curl"}'
# expect 204

Once MCP is connected, use search_events to find captured notes. The MCP query server is Supported — see MCP query planning.

Next steps

• Quick Start — run trove locally
• HTTP ingest planning — endpoint details
• examples/ios-shortcuts/ — payloads and maintainer docs