Notepush API Endpoints Documentation

1. Web Push Information

Endpoint	HTTP Method	Description
/web	GET	Retrieves web push information for Notepush, including the VAPID key for FCM.

• Authentication: Not required
• Query Parameters: None
• Response Body: JSON object of type WebPushInfo
  • vaapi_key: Option - VAPID key from FCM configuration, if available
• Success Response: 200 OK with JSON body, e.g., {"vaapi_key": "example_key"}
• Error Responses: None

2. User Information Management

Endpoint	HTTP Method	Description
/user-info/{pubkey}/{deviceToken}	PUT	Updates user device information with the specified public key and device token.
/user-info/{pubkey}/{deviceToken}	DELETE	Removes user device information for the specified public key and device token.

• Authentication: Required (NIP-98 Authorization header with Nostr Event)
• Path Parameters:
  • pubkey: PublicKey - User public key in hex format (required, validated against auth event)
  • deviceToken: String - Device token (required, URL-encoded)
• Query Parameters (PUT only):
  • backend: NotificationBackend - Notification backend (optional, defaults to "apns"; must be a supported backend, e.g., APNS, FCM)
• Request Body (PUT only): None
• Success Response (PUT): 200 OK with JSON body: {"message": "User info saved successfully"}
• Success Response (DELETE): 200 OK with JSON body: {"message": "User info removed successfully"}
• Error Responses:
  • 400 Bad Request: Invalid pubkey, deviceToken, or unsupported backend
  • 401 Unauthorized: Missing or invalid Authorization header, or pubkey mismatch with auth event
  • 500 Internal Server Error: Unexpected server error (includes case ID for debugging)

3. Notification Settings Management

Endpoint	HTTP Method	Description
/user-info/{pubkey}/notify/{target}	PUT	Sets or updates notification settings for a specific user and target.
/user-info/{pubkey}/notify/{target}	DELETE	Deletes notification settings for a specific user and target.
/user-info/{pubkey}/notify	GET	Retrieves notification settings for a specific user.

• Authentication: Required (NIP-98 Authorization header with Nostr Event)
• Path Parameters:
  • pubkey: PublicKey - User public key in hex format (required, validated against auth event)
  • target: PublicKey - Target public key in hex format (required for PUT and DELETE, validated)
• Request Body (PUT only): JSON object of type KindsSettings, e.g., {"kinds": {...}}
• Response Body (GET only): JSON array of notification keys (type not specified in code, depends on NotificationManager::get_notify_keys)
• Success Response (PUT): 200 OK with JSON body: {"message": "Saved notification target successfully"}
• Success Response (DELETE): 200 OK with JSON body: {"message": "Deleted notification target successfully"}
• Success Response (GET): 200 OK with JSON body containing notification keys
• Error Responses:
  • 400 Bad Request: Invalid pubkey, target, or missing/invalid KindsSettings in request body
  • 401 Unauthorized: Missing or invalid Authorization header, or pubkey mismatch with auth event
  • 500 Internal Server Error: Unexpected server error (includes case ID for debugging)

4. User Preferences Management

Endpoint	HTTP Method	Description
/user-info/{pubkey}/{deviceToken}/preference	GET	Retrieves user notification preferences for a specific public key and device token.
/user-info/{pubkey}/{deviceToken}/preference	PUT	Updates user notification preferences for a specific public key and device token.

• Authentication: Required (NIP-98 Authorization header with Nostr Event)
• Path Parameters:
  • pubkey: PublicKey - User public key in hex format (required, validated against auth event)
  • deviceToken: String - Device token (required, URL-encoded)
• Request Body (PUT only): JSON object of type UserNotificationSettings, e.g., {"settings": {...}}
• Response Body (GET only): JSON object of type UserNotificationSettings
• Success Response (GET): 200 OK with JSON body containing user notification settings
• Success Response (PUT): 200 OK with JSON body: {"message": "User settings saved successfully"}
• Error Responses:
  • 400 Bad Request: Invalid pubkey, deviceToken, or missing/invalid UserNotificationSettings in request body
  • 401 Unauthorized: Missing or invalid Authorization header, or pubkey mismatch with auth event
  • 500 Internal Server Error: Unexpected server error (includes case ID for debugging)

5. Root and WebSocket

Endpoint	HTTP Method	Description
/ or /index.html	GET	Serves the static index.html page for Notepush.
/*	WebSocket	Handles WebSocket upgrade requests for real-time notification relay.

• Authentication (WebSocket): Not specified in handler
• Response (GET): Static HTML content
• Response (WebSocket): WebSocket upgrade response
• Success Response (GET): 200 OK with HTML content
• Success Response (WebSocket): 101 Switching Protocols
• Error Responses (WebSocket):
  • 500 Internal Server Error: Failed WebSocket upgrade

Authentication

All endpoints except /web and / require authentication via a Nostr event in the Authorization header, following NIP-98. The event must:

• Match the request method and URI.
• Include a valid pubkey that matches the pubkey path parameter.
• Be verifiable using nip98_auth::nip98_verify_auth_header.

Error Responses for Authentication:

• 401 Unauthorized: Missing Authorization header, invalid Nostr event, or pubkey mismatch

Error Handling

Common error responses across all endpoints include:

• 400 Bad Request: Invalid or missing parameters, invalid request body
• 401 Unauthorized: Authentication failure
• 404 Not Found: Unmatched endpoint
• 500 Internal Server Error: Unexpected server errors (includes a unique case ID for debugging)