API Reference

Complete API documentation for the Pushy notification system.

Base URL

bash

# Production (AWS EKS)
http://a9a18d9bb21ed4e6e9b07bbd4b8d9f16-251019334.sa-east-1.elb.amazonaws.com
# Local Development
http://localhost:3001

Authentication

API Key Authentication

TODO - All API requests SHOULD include an API key in the Authorization header (Coming Soon):

bash

Authorization: Bearer YOUR_API_KEY

Users API

Create User

POST

bash

POST /users

Request Body

json

{
  "email": "trader@crypto.com",
  "name": "Crypto Trader",
  "push_subscription": {
    "endpoint": "https://fcm.googleapis.com/...",
    "keys": {
      "p256dh": "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA...",
      "auth": "s3VJd6nSsU9JlGgRZ5vJQGXWz9dR8vQyQzQc8..."
    }
  }
}

Response

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "trader@crypto.com",
  "name": "Crypto Trader",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Get User

GET

bash

GET /users/{id}

Path Parameters

id - User UUID

Response

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "trader@crypto.com",
  "name": "Crypto Trader",
  "push_subscription": {...},
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Update User

PUT

bash

PUT /users/{id}

Request Body

json

{
  "name": "Updated Name",
  "push_subscription": {
    // Updated push subscription
  }
}

Delete User

DELETE

bash

DELETE /users/{id}

Response

bash

204 No Content

Notifications API

Send Notification

POST

bash

POST /notifications

Request Body

json

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "template_id": "purchase_confirmed",
  "language": "en",
  "template_variables": {
    "userName": "Crypto Trader",
    "amount": "0.5",
    "currency": "BTC",
    "txHash": "0xabc123def456",
    "exchangeName": "Crypto Exchange"
  },
  "notification_type": "purchase",
  "channel": "both",  // "email", "push", or "both"
  "metadata": {
    "priority": "high",
    "tags": ["crypto", "purchase"]
  }
}

Response

json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "channel": "both",
  "created_at": "2024-01-15T10:00:00Z"
}

Notification Types

alert

info

reminder

promotion

purchase

deposit

withdrawal

sale

Get Notification Status

GET

bash

GET /notifications/{id}

Response

json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Purchase Confirmed",
  "body": "Your purchase of 0.5 BTC has been confirmed...",
  "notification_type": "purchase",
  "channel": "both",
  "status": "sent",
  "sent_at": "2024-01-15T10:00:05Z",
  "created_at": "2024-01-15T10:00:00Z",
  "metadata": {
    "email_delivered": true,
    "push_delivered": true
  }
}

Status Values

pending

queued

sent

failed

Get User Notifications

GET

bash

GET /users/{id}/notifications?limit=20&offset=0&status=sent

Query Parameters

limit - Number of results (default: 20, max: 100)

offset - Pagination offset (default: 0)

status - Filter by status (optional)

type - Filter by notification type (optional)

Response

json

{
  "notifications": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Purchase Confirmed",
      "body": "Your purchase of 0.5 BTC has been confirmed...",
      "notification_type": "purchase",
      "status": "sent",
      "created_at": "2024-01-15T10:00:00Z"
    },
    // More notifications...
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Templates API

Templates are managed through Contentful CMS. The following template IDs are available:

Template ID	Description	Languages	Variables
`purchase_confirmed`	Crypto purchase confirmation	en, es	`userName, amount, currency, txHash`
`deposit_confirmed`	Deposit confirmation	en, es	`userName, amount, currency`
`withdrawal_completed`	Withdrawal completed	en, es	`userName, amount, currency, address`

Error Responses

All error responses follow a consistent format:

json

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is invalid",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  }
}

Common Error Codes

400 Bad RequestInvalid request parameters

401 UnauthorizedMissing or invalid API key

404 Not FoundResource not found

429 Too Many RequestsRate limit exceeded

500 Internal Server ErrorServer error