Skip to content
TipOff

Quick Start

Prerequisites

Section titled “Prerequisites”
  • A TipOff source API key (sk_...) — create one from the dashboard or via the REST API
  • For the agent path: the tipoff-agent binary (available from the project releases)

Send a notification

Section titled “Send a notification”
Terminal window
curl -s https://api.tipoff.dev/v1/notifications \
  -H "Authorization: Bearer sk_your_source_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "task-123",
    "to": "user_abc",
    "title": "Overdue: Buy groceries",
    "body": "Task was due 2 hours ago",
    "category": "done_snooze_dismiss",
    "priority": "high"
  }'

The notification is delivered to the user’s iOS device via APNs. When they tap an action button (e.g. “Done”), an action event is queued for your source.

Receive action callbacks

Section titled “Receive action callbacks”

Pick the path that fits your setup:

The agent maintains a persistent gRPC stream to the server and forwards action events as HTTP POSTs to a local endpoint.

Terminal window
TIPOFF_AGENT_API_KEY=sk_your_source_key \
TIPOFF_AGENT_GRPC_URL=grpc.tipoff.dev:443 \
TIPOFF_AGENT_ADAPTERS_DIR=./adapters \
./tipoff-agent

When a user taps “Done”, the agent evaluates the matching adapter and delivers the action event:

{
  "event_id": "evt_xxxxxxxxxxxx",
  "notification_id": "task-123",
  "action": "done",
  "user": "user_abc",
  "metadata": {},
  "timestamp": "2026-04-21T12:05:00Z",
  "source_id": "src_xxxxxxxxxxxx"
}

For richer routing (mapping actions to upstream API calls), see the Agent Adapters guide.

Next steps

Section titled “Next steps”