API Documentation

Rytsas exposes a REST API at https://rytsas.lionfi.sh/api/v1. All request and response bodies are JSON.

Authentication

Three auth mechanisms

API Key	`Authorization: Bearer ryt_…` Used by your backend to send notifications. Create keys in the dashboard.
Device Token	`X-Device-Token: <token>` Used by the mobile app to list subscriptions and notification history.
Session	Browser cookie session via GitHub OAuth. Powers the dashboard UI.

MCP Server (Agent Integration)

The Rytsas MCP server lets AI agents send push notifications as a native tool. It’s hosted at https://rytsas.lionfi.sh/mcp—no local install required.

Configuration

Add to your .mcp.json (Claude Code) or equivalent MCP client config:

{
  "mcpServers": {
    "rytsas": {
      "type": "url",
      "url": "https://rytsas.lionfi.sh/mcp",
      "headers": {
        "Authorization": "Bearer rytsas_YOUR_API_KEY"
      }
    }
  }
}

Replace rytsas_YOUR_API_KEY with an API key from your dashboard.

Available Tool

TOOL send_notification

Send a push notification to a subscribed user.

Parameter	Type	Required	Description
`user_id`	string	Yes	The user alias to notify
`title`	string	Yes	Notification title
`body`	string	Yes	Notification body text
`link`	string	No	URL to open on tap
`metadata`	object	No	Arbitrary key-value data passed to the device

Response

{
  "id": "01J…",
  "status": "sent",
  "devices_targeted": 1
}

Endpoints

POST /api/v1/notify API Key

Send a push notification to a subscribed user.

Request body

Field	Type	Required	Description
`user_id`	string	Yes	The user alias to notify
`title`	string	Yes	Notification title
`body`	string	Yes	Notification body text
`link`	string	No	URL to open on tap
`metadata`	object	No	Arbitrary key-value data passed to the device

Example

curl -X POST https://rytsas.lionfi.sh/api/v1/notify \
  -H "Authorization: Bearer ryt_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "title": "New message",
    "body": "You have 3 unread messages",
    "link": "https://example.com/inbox"
  }'

Response

{
  "id": "01J…",
  "status": "sent",
  "devices_targeted": 1
}

POST /api/v1/devices/register None

Request body

Field	Type	Required	Description
`device_token`	string	Yes	Stable device identifier
`fcm_token`	string	Yes	Firebase Cloud Messaging token
`platform`	string	Yes	`android` or `ios`

Example

curl -X POST https://rytsas.lionfi.sh/api/v1/devices/register \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "device_abc123",
    "fcm_token": "fcm_token_here",
    "platform": "android"
  }'

Response

{ "device_id": "01J…" }

POST /api/v1/subscriptions/subscribe None

Subscribe a device to a project (typically triggered after QR scan).

Request body

Field	Type	Required	Description
`device_token`	string	Yes	Stable device identifier
`project_id`	string	Yes	Project to subscribe to
`user_alias`	string	Yes	User identifier within the project

Response

{ "subscription_id": "01J…" }

POST /api/v1/subscriptions/unsubscribe None

Unsubscribe a device from a project.

Request body

Field	Type	Required	Description
`device_token`	string	Yes	Stable device identifier
`project_id`	string	Yes	Project to unsubscribe from

Response

{ "ok": true }

GET /api/v1/subscriptions/mine Device Token

List active subscriptions for a device.

Example

curl https://rytsas.lionfi.sh/api/v1/subscriptions/mine \
  -H "X-Device-Token: device_abc123"

Response

{
  "subscriptions": [
    {
      "id": "01J…",
      "project_id": "01J…",
      "project_name": "My Project",
      "user_alias": "alice",
      "created_at": 1700000000000
    }
  ]
}

GET /api/v1/notifications/history Device Token

Fetch notification history for a device. Supports pagination.

Query parameters

Param	Type	Default	Description
`since`	number	0	Only return notifications created after this timestamp (ms)
`limit`	number	50	Max results (capped at 100)

Example

curl https://rytsas.lionfi.sh/api/v1/notifications/history \
  -H "X-Device-Token: device_abc123"

Response

{
  "notifications": [
    {
      "id": "01J…",
      "project_id": "01J…",
      "project_name": "My Project",
      "title": "Deploy complete",
      "body": "v2.1.0 is live",
      "status": "sent",
      "sent_at": 1700000000000,
      "created_at": 1700000000000
    }
  ]
}