# Tygash Push Notification API — v{{VERSION}}

> The agent-native push notification platform. Agents compose, target, and deliver push notifications across Web Push, iOS APNs, and Android FCM.
> **Doc version: {{VERSION}}** — Check GET /saas/api/v1/sdk/config/status for current version. If your cached version is older, re-fetch this doc.

## Quick Reference

| I want to... | Endpoint | Auth |
|--------------|----------|------|
| Send a notification | POST /saas/api/v1/sdk/push/send | Bearer token |
| Send batch | POST /saas/api/v1/sdk/push/send-batch | Bearer token |
| Get notification history | GET /saas/api/v1/sdk/push/history | Bearer token |
| Get delivery stats | GET /saas/api/v1/sdk/push/stats | Bearer token |
| Register a device | POST /saas/api/v1/sdk/push/devices/register | Bearer token |
| List devices | GET /saas/api/v1/sdk/push/devices | Bearer token |
| Create a topic | POST /saas/api/v1/sdk/push/topics | Bearer token |
| Subscribe to topic | POST /saas/api/v1/sdk/push/topics/:id/subscribe | Bearer token |
| Create a segment | POST /saas/api/v1/sdk/push/segments | Bearer token |
| Create a template | POST /saas/api/v1/sdk/push/templates | Bearer token |
| Create a campaign | POST /saas/api/v1/sdk/push/campaigns | Bearer token |
| Get channel config | GET /saas/api/v1/sdk/push/channels/config | Bearer token |
| Query knowledge base | POST /saas/api/v1/sdk/push/knowledge/query | Bearer token |
| View knowledge tree | GET /saas/api/v1/sdk/push/knowledge/tree | Public |

All endpoints require `Authorization: Bearer YOUR_API_KEY` header unless marked Public.
All request bodies are JSON with `Content-Type: application/json`.

## Authentication

Every API call requires:
```
-H "Authorization: Bearer $TYGASH_API_KEY"
-H "Content-Type: application/json"
```

Get your API key at https://tygash.com/get-started (free tier, no credit card).

## Sending Notifications

POST /saas/api/v1/sdk/push/send
```json
{
  "title": "Price Drop!",
  "body": "Nike Air Max now 30% off",
  "topic": "price-alerts",
  "channels": ["web", "ios", "android"]
}
```
Response: `{ "id": "msg_abc123", "status": "sent", "delivered": { "web": 842, "ios": 1205, "android": 967 }, "total": 3014, "latency_ms": 38 }`

POST /saas/api/v1/sdk/push/send-batch — send to multiple topics/segments in one call.

## Notification History & Stats

GET /saas/api/v1/sdk/push/history — all sent notifications with delivery status.
GET /saas/api/v1/sdk/push/history/:notificationId — specific notification details.
GET /saas/api/v1/sdk/push/stats — delivery rates, open rates, click-through rates.

## Device Management

POST /saas/api/v1/sdk/push/devices/register — register a device for push.
```json
{ "platform": "web|ios|android", "token": "device_push_token", "metadata": {} }
```
GET /saas/api/v1/sdk/push/devices — list registered devices.
GET /saas/api/v1/sdk/push/devices/:deviceId — get device details.
PUT /saas/api/v1/sdk/push/devices/:deviceId — update device metadata.
DELETE /saas/api/v1/sdk/push/devices/:deviceId — unregister device.

## Topics (Pub/Sub)

POST /saas/api/v1/sdk/push/topics — create topic.
```json
{ "name": "price-alerts", "description": "Price drop notifications" }
```
GET /saas/api/v1/sdk/push/topics — list topics.
GET /saas/api/v1/sdk/push/topics/:topicId — get topic details.
PUT /saas/api/v1/sdk/push/topics/:topicId — update topic.
DELETE /saas/api/v1/sdk/push/topics/:topicId — delete topic.
POST /saas/api/v1/sdk/push/topics/:topicId/subscribe — subscribe devices.
POST /saas/api/v1/sdk/push/topics/:topicId/unsubscribe — unsubscribe devices.

## Segments (Audience Targeting)

POST /saas/api/v1/sdk/push/segments — create segment.
```json
{ "name": "active-ios", "filters": { "platform": "ios", "lastActive": ">7d" } }
```
GET /saas/api/v1/sdk/push/segments — list segments.
GET /saas/api/v1/sdk/push/segments/:segmentId — get segment.
PUT /saas/api/v1/sdk/push/segments/:segmentId — update segment.
DELETE /saas/api/v1/sdk/push/segments/:segmentId — delete segment.

## Templates

POST /saas/api/v1/sdk/push/templates — create template.
```json
{ "name": "welcome", "title": "Welcome {{name}}!", "body": "Thanks for signing up." }
```
GET /saas/api/v1/sdk/push/templates — list templates.
GET /saas/api/v1/sdk/push/templates/:templateId — get template.
PUT /saas/api/v1/sdk/push/templates/:templateId — update template.
DELETE /saas/api/v1/sdk/push/templates/:templateId — delete template.

## Campaigns

POST /saas/api/v1/sdk/push/campaigns — create campaign.
```json
{ "name": "Black Friday", "templateId": "...", "segmentId": "...", "scheduledAt": "2026-11-27T09:00:00Z" }
```
GET /saas/api/v1/sdk/push/campaigns — list campaigns.
GET /saas/api/v1/sdk/push/campaigns/:campaignId — get campaign.
GET /saas/api/v1/sdk/push/campaigns/:campaignId/stats — campaign delivery stats.
PUT /saas/api/v1/sdk/push/campaigns/:campaignId — update campaign.
DELETE /saas/api/v1/sdk/push/campaigns/:campaignId — delete campaign.

## Channel Configuration

GET /saas/api/v1/sdk/push/channels/config — get channel config (VAPID, APNs, FCM).
PUT /saas/api/v1/sdk/push/channels/config — update channel config.

## Knowledge Base (h-Conductor)

GET /saas/api/v1/sdk/push/knowledge/tree — view knowledge domains as tau tree notation.
GET /saas/api/v1/sdk/push/knowledge/domain/:domain — drill into domain (compliance, delivery, audience, content, operations).
GET /saas/api/v1/sdk/push/knowledge/source/:sourceCode — drill into source (GDPR, PECR, APNS, FCM, etc.).
POST /saas/api/v1/sdk/push/knowledge/query — query knowledge base with h-context assembly.
```json
{ "domain": "compliance", "query": "GDPR consent requirements for marketing push" }
```
POST /saas/api/v1/sdk/push/consult — full conductor pipeline (intake, classify, expert, verify).
```json
{ "query": "Can I send push notifications to EU users without explicit consent?" }
```
POST /saas/api/v1/sdk/push/consult/stream — same as consult but with Server-Sent Events for progress.

## Quotas

| Plan | Agent Seats | Subscribers | Messages/mo | Rate Limit |
|------|-------------|-------------|-------------|------------|
| Free | 1 | 1,000 | 10,000 | 100/min |
| Starter ($49/mo) | 5 | 10,000 | 100,000 | 500/min |
| Team ($149/mo) | 20 | 50,000 | 500,000 | 2,000/min |
| Enterprise | Unlimited | Unlimited | Unlimited | Custom |

## Health

GET /saas/api/v1/sdk/push/health — push service health check.

## Full Documentation

- Quickstart guides: https://tygash.com/docs/quickstart.html
- Per-agent setup: https://tygash.com/docs/quickstart/claude-code.html (also: cursor, cline, windsurf, aider, codex)
- Sign up: https://tygash.com/get-started