Notifications

Quick start

The raw HTTP path is for reviewed headless integrations. Inject $CHIRP_API_KEY from a secret manager; never paste its value into a prompt, URL, source file, or shared command. Interactive agent hosts should pair with chirp login. Review the headless credential launch gate in the dashboard.

curl -X POST https://api.chirpapp.dev/v1/notify \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello from Chirp","body":"Your first notification!"}'

Inspect the JSON response for API/provider acceptance. The current notification route has no handset-display acknowledgement, so a 2xx response—and even an upstream provider receipt—must not be described as proof that iOS displayed the banner. The guided onboarding demo has a separate Live Activity device acknowledgement.

Reviewed SDK/connector sources may wrap this endpoint. See the integrations page for source examples and explicit release status.

Notifications vs Live Activities

Schema reference

POST to /v1/notify with a JSON body containing any of these fields.

Examples

curl -X POST https://api.chirpapp.dev/v1/notify \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Deploy complete","body":"my-app v2.4.1 is live"}'

curl -X POST https://api.chirpapp.dev/v1/notify \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New order",
    "body": "$129.99 from sarah@example.com",
    "subtitle": "Shopify",
    "sound": "default",
    "open_url": "https://admin.shopify.com/orders/12345",
    "thread_id": "orders"
  }'

curl -X POST https://api.chirpapp.dev/v1/notify \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Server down",
    "body": "api-prod-3 is unreachable. Last ping 45s ago.",
    "sound": "default",
    "interruption_level": "time-sensitive"
  }'

import chirp

chirp.notify(
    title="Build complete",
    body="my-app v2.4.1 deployed to production",
    sound="default",
    thread_id="deploys",
)

# With all options:
chirp.notify(
    title="Payment received",
    body="$49.99 from customer@example.com",
    subtitle="Stripe",
    sound="chirp",
    open_url="https://dashboard.stripe.com/payments/pi_123",
    interruption_level="active",
)

// Source preview: @chirp/sdk is not published yet.
import { ChirpClient } from "@chirp/sdk";

const chirp = new ChirpClient();

await chirp.notify("Build complete", "my-app v2.4.1 deployed to production", {
  sound: "default",
  thread_id: "deploys",
});

# Reviewed local connectors/bash/chirp.sh copy
source ~/.chirp.sh
chirp_notify "Deploy done" "my-app is live"

Sounds

The sound field controls what plays when the notification arrives.

• "default"Standard iOS notification sound.
• "chirp"Custom Chirp notification sound (bundled in the app).
• omittedDefault notification sound.

Interruption levels

iOS lets you control how urgently a notification is presented. Set the interruption_level field to one of these values.

Remote image attachments

Remote image_url attachments are disabled in the launch build. The API rejects a request containing that field with HTTP 400, so callers must omit it; Chirp does not silently send a text-only variant. The app does not fetch a push-controlled URL from the device.

• Planned: server-side validation, size/type caps, and rewrite to an immutable Chirp-owned CDN URL
• Live Activity backgrounds are finite procedural SwiftUI presets compiled into the app; they do not load remote images
• Do not depend on remote notification artwork until the docs mark the Chirp-owned proxy as available

Thread grouping

Set thread_id to group related notifications in Notification Center. All notifications with the same thread ID are bundled together — the user sees a stack instead of individual items.

Good thread IDs are stable, meaningful strings like deploys, orders, ci-main, or alerts-prod.

Tap-to-open URLs

Set open_url to open a link when the user taps the notification. External URLs (https://) open in the browser. The app’s internal deep links (chirp://) route to the appropriate screen.

Send notifications from…

Use the Notification toggle on each integration page to see the notification-specific setup.