# Uptify Developer Documentation & Complete Technical Specification

> **Canonical Document URL:** https://uptify.site/llms-full.txt  
> **API Hub:** https://uptify.site/docs or https://docs.uptify.site  
> **API Base URL:** https://api.uptify.site  
> **Resource Shop:** https://uptify.site/shop  
> **User Wallet & Credits:** https://uptify.site/wallet  
> **Founder & Chief Architect:** Shaikh Zaid ([@ShaikhZaid404](https://github.com/ShaikhZaid404))  
> **Document Version:** 2.6.0-Production  

---

## Table of Contents
1. [Overview & Credit Shop Pricing Matrix](#1-overview--credit-shop-pricing-matrix)
2. [Authentication (JWT & API Tokens)](#2-authentication-jwt--api-tokens)
3. [REST Endpoints: Uptime Monitors](#3-rest-endpoints-uptime-monitors)
4. [REST Endpoints: Projects & Status Pages](#4-rest-endpoints-projects--status-pages)
5. [REST Endpoints: Incidents & Updates](#5-rest-endpoints-incidents--updates)
6. [REST Endpoints: Feedback Boards & Roadmaps](#6-rest-endpoints-feedback-boards--roadmaps)
7. [Heartbeat & Cron Dead-Man Monitoring](#7-heartbeat--cron-dead-man-monitoring)
8. [Minecraft SLP & RakNet Pinger Protocol](#8-minecraft-slp--raknet-pinger-protocol)
9. [Webhook Payloads & Discord Integration](#9-webhook-payloads--discord-integration)
10. [Global Outage Radar API](#10-global-outage-radar-api)
11. [Rate Limits & HTTP Status Error Codes](#11-rate-limits--http-status-error-codes)

---

## 1. Overview & Credit Shop Pricing Matrix

Uptify provides infrastructure uptime monitoring, hosted status portals, crowdsourced outage detection, and customer feedback boards.

### Pricing Model: No Subscription Traps — Free Core + On-Demand Credits
Uptify eliminates monthly software subscription lock-ins. Every account receives generous permanent limits, and users expand capacity by spending platform **Credits (Cr)**.

### Always Free Core (₹0 / $0)
- **Monitors:** Up to 70 active endpoints
- **Projects & Status Pages:** Up to 5 projects
- **Feedback Boards:** Up to 2 feedback boards
- **Custom Domains:** Up to 2 custom domains with automated Cloudflare SSL
- **Check Frequency:** 5-minute intervals (300 seconds)
- **Data Retention:** 30 days of latency, uptime, and incident telemetry
- **Incident Dispatch:** Instant email notifications & Discord webhooks

### Resource Shop Catalog (Kitne Credits me Kya Milta Hai):
Users can upgrade specific capabilities via `POST /api/k2/shop/checkout` or directly in the console at `https://uptify.site/shop`:

| Item Key | Upgrade Name | Price | Unit / Duration | What It Unlocks |
|---|---|---|---|---|
| `MONITOR_SLOT` | **Additional Monitor Slot** | **100 Cr** | Permanent | Adds 1 permanent active uptime monitor slot to your account |
| `PROJECT_SLOT` | **Additional Project Slot** | **250 Cr** | Permanent | Adds 1 permanent project space slot for hosting dedicated status pages |
| `CUSTOM_DOMAIN` | **Custom Domain Slot** | **200 Cr** | Permanent | Bind a custom domain (e.g. status.yourbrand.com) with auto SSL |
| `FAST_PING_60S` | **Fast-Ping Turbo (60s)** | **150 Cr** | 30 Days | Reduces check interval from 300s to ultra-fast 60s across all monitors |
| `ULTRA_PING_30S` | **Ultra-Fast Realtime (30s)** | **300 Cr** | 30 Days | Real-time probing every 30 seconds for mission-critical infrastructure |
| `WHITE_LABEL` | **White-Label Branding** | **250 Cr** | Permanent | Removes the "Powered by Uptify" footer watermark & unlocks custom themes |
| `EXTENDED_SLA` | **365-Day SLA History** | **120 Cr** | Permanent | Extends historical response times and incident logs to 1 full year |
| `MYSQL_DB` | **Incident & Metrics DB** | **20 Cr** | Permanent | Dedicated relational database for metrics export and audit trails |
| `BACKUP_SLOT` | **Automated Snapshot Backup**| **15 Cr** | Permanent | Automated configuration snapshot retention with 1-click disaster recovery |
| `PRIORITY_ALERTS`| **Priority Alerts Relay** | **75 Cr** | Permanent | Instant zero-delay incident delivery with Discord role pings & Telegram sync |
| `SPOTLIGHT_7D` | **Explore Spotlight Banner** | **500 Cr** | 7 Days | Promotes your project in the featured spotlight carousel on explore pages |

### Earning Free Platform Credits
- **200 Cr Signup Bonus:** Credited immediately to your wallet upon creating an account.
- **Daily Streak Claim (`/daily`):** Claim 50 Cr (Day 1) scaling up to 75 Cr/day on a 5-day streak.
- **AFK Mining Hub (`/afk`):** Keep an AFK session tab open to mine credits in the background with up to 3x crowd multipliers.
- **Creator Quests (`/events`):** Complete community challenges and report platform outages to earn bonus credit packs.
- **P2P Transfers:** Transfer credits to teammates or clients via `POST /api/k2/wallet/transfer`.

---

## 2. Authentication (JWT & API Tokens)

Uptify supports authentication via JSON Web Tokens (JWT) for user sessions and API Tokens (`upt_live_...`) for automation scripts and CI/CD pipelines.

### HTTP Header Specification
All authenticated requests must include the `Authorization` header:
```http
Authorization: Bearer <JWT_TOKEN_OR_API_KEY>
Content-Type: application/json
```

### Obtain Auth Token
- **Endpoint:** `POST https://api.uptify.site/api/auth/login`
- **Request Body:**
```json
{
  "email": "developer@example.com",
  "password": "YourSecurePassword123"
}
```
- **Response (`200 OK`):**
```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "usr_78a6b2c9",
    "email": "developer@example.com",
    "username": "zaid_dev",
    "role": "USER",
    "plan": "FREE"
  }
}
```

---

## 3. REST Endpoints: Uptime Monitors

### 3.1 Create Monitor
- **Endpoint:** `POST https://api.uptify.site/api/projects/:projectId/monitors`
- **Headers:** `Authorization: Bearer <token>`
- **Request Body:**
```json
{
  "name": "Production API Gateway",
  "type": "HTTP",
  "targetUrl": "https://api.yourdomain.com/health",
  "interval": 300
}
```
*Supported `type` values:*
- `HTTP`: Web endpoints with status code & keyword verification
- `PING` / `PORT`: Low-level TCP socket port checks (e.g. `db.yourdomain.com:5432`)
- `DISCORD_BOT`: Discord bot token and gateway presence monitoring
- `SSL_CERTIFICATE`: Standalone TLS/SSL validity tracking

- **Response (`201 Created`):**
```json
{
  "success": true,
  "monitor": {
    "id": "mon_98f12a4b",
    "projectId": "1002345678",
    "name": "Production API Gateway",
    "type": "HTTP",
    "targetUrl": "https://api.yourdomain.com/health",
    "interval": 300,
    "status": "UP",
    "createdAt": "2026-09-20T12:00:00.000Z"
  }
}
```

### 3.2 List Monitors in Project
- **Endpoint:** `GET https://api.uptify.site/api/projects/:projectId/monitors`
- **Headers:** `Authorization: Bearer <token>`
- **Response (`200 OK`):**
```json
[
  {
    "id": "mon_98f12a4b",
    "name": "Production API Gateway",
    "type": "HTTP",
    "targetUrl": "https://api.yourdomain.com/health",
    "status": "UP",
    "latency": 24,
    "interval": 300,
    "lastCheck": "2026-09-21T03:00:00.000Z"
  }
]
```

### 3.3 Delete Monitor
- **Endpoint:** `DELETE https://api.uptify.site/api/projects/:projectId/monitors/:monitorId`
- **Headers:** `Authorization: Bearer <token>`
- **Response (`200 OK`):**
```json
{
  "success": true,
  "message": "Monitor deleted successfully"
}
```

---

## 4. REST Endpoints: Projects & Status Pages

### 4.1 Create Project
- **Endpoint:** `POST https://api.uptify.site/api/projects`
- **Headers:** `Authorization: Bearer <token>`
- **Request Body:**
```json
{
  "name": "Acme Cloud Infrastructure",
  "description": "Public system status and uptime telemetry",
  "type": "STATUS",
  "isPublic": true
}
```
- **Response (`201 Created`):**
```json
{
  "success": true,
  "project": {
    "id": "1002345678",
    "name": "Acme Cloud Infrastructure",
    "type": "STATUS",
    "isPublic": true,
    "createdAt": "2026-09-20T12:00:00.000Z"
  }
}
```

### 4.2 Attach Custom Domain (CNAME)
- **DNS Setup:** Point your CNAME record to `cname.uptify.site` (e.g. `status.yourdomain.com CNAME cname.uptify.site`).
- **Endpoint:** `POST https://api.uptify.site/api/k2/projects/:projectId/domain`
- **Request Body:**
```json
{
  "domain": "status.yourdomain.com"
}
```
- **Response (`200 OK`):**
```json
{
  "success": true,
  "domain": "status.yourdomain.com",
  "status": "ACTIVE",
  "ssl": "PROVISIONED"
}
```

### 4.3 Public Status Page Telemetry (No Auth Required)
- **Endpoint:** `GET https://api.uptify.site/s/:projectId`
- **Response (`200 OK`):**
```json
{
  "project": {
    "id": "1002345678",
    "name": "Acme Cloud Infrastructure",
    "uptimePercentage": 99.98
  },
  "monitors": [
    {
      "id": "mon_98f12a4b",
      "name": "Production API Gateway",
      "status": "UP",
      "uptime": 99.99,
      "latency": 24
    }
  ],
  "incidents": []
}
```

---

## 5. REST Endpoints: Incidents & Updates

### 5.1 Post Incident
- **Endpoint:** `POST https://api.uptify.site/api/projects/:projectId/incidents`
- **Headers:** `Authorization: Bearer <token>`
- **Request Body:**
```json
{
  "title": "Elevated Latency on European Database Replicas",
  "status": "INVESTIGATING",
  "severity": "MAJOR",
  "message": "We are investigating elevated query response times on the EU-Central database cluster."
}
```
*Supported `status` values:* `INVESTIGATING`, `IDENTIFIED`, `MONITORING`, `RESOLVED`  
*Supported `severity` values:* `MINOR`, `MAJOR`, `CRITICAL`, `NONE`

---

## 6. REST Endpoints: Feedback Boards & Roadmaps

### 6.1 Submit User Feedback
- **Endpoint:** `POST https://api.uptify.site/api/feedback`
- **Headers:** `Authorization: Bearer <token>`
- **Request Body:**
```json
{
  "projectId": "1002345678",
  "title": "Add Telegram Alert Bot Integration",
  "content": "Allow users to receive downtime notices directly in Telegram channels."
}
```

---

## 7. Heartbeat & Cron Dead-Man Monitoring

For background workers, cron jobs, database backups, and scheduled queue consumers:
1. Create a Monitor with type `HTTP` or generate a Heartbeat Token.
2. In your cron job or worker script, send an HTTP GET or POST request to Uptify upon job completion:
```bash
# Linux Crontab Example (runs daily at 3:00 AM)
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 https://api.uptify.site/heartbeat/hb_live_83fa19b2
```
3. If Uptify does not receive the ping within your configured schedule plus grace window, an incident alert is immediately dispatched.

---

## 8. Minecraft SLP & RakNet Pinger Protocol

Uptify provides instant native binary socket pinging for Minecraft servers:

### Public Instant Ping Endpoint
- **Endpoint:** `GET https://api.uptify.site/mc/:target`
- **Example:** `GET https://api.uptify.site/mc/play.hypixel.net`
- **Response (`200 OK`):**
```json
{
  "online": true,
  "host": "play.hypixel.net",
  "port": 25565,
  "players": {
    "online": 32145,
    "max": 100000
  },
  "version": {
    "name": "Requires MC 1.8.x - 1.21.x",
    "protocol": 47
  },
  "motd": {
    "clean": "Hypixel Network [1.8-1.21]\nEASTER EVENT IS LIVE!"
  },
  "latency": 34
}
```

---

## 9. Webhook Payloads & Discord Integration

When an endpoint changes state (UP -> DOWN or DOWN -> UP), Uptify dispatches a structured JSON webhook:

### Incident Webhook Payload
```json
{
  "event": "monitor.status_changed",
  "timestamp": "2026-09-21T03:00:00.000Z",
  "data": {
    "monitorId": "mon_98f12a4b",
    "monitorName": "Production API Gateway",
    "targetUrl": "https://api.yourdomain.com/health",
    "previousStatus": "UP",
    "currentStatus": "DOWN",
    "statusCode": 502,
    "error": "Bad Gateway: Remote upstream server connection timed out",
    "projectId": "1002345678",
    "statusPageUrl": "https://uptify.site/status/1002345678"
  }
}
```

---

## 10. Global Outage Radar API

Monitor the health of 101+ internet services:
- **All Services State:** `GET https://api.uptify.site/radar/services`
- **Specific Platform Reports & Chat:** `GET https://api.uptify.site/radar/:slug` (e.g. `openai`, `github`, `cloudflare`)
- **Submit Outage Report:** `POST https://api.uptify.site/radar/:slug/report` (rate limited to 5 submissions/hour/IP with SHA-256 IP hashing)

---

## 11. Rate Limits & HTTP Status Error Codes

| HTTP Status Code | Description | Resolution Strategy |
|---|---|---|
| **200 OK** | Request succeeded | Standard response |
| **201 Created** | Resource successfully provisioned | Monitor or project initialized |
| **400 Bad Request** | Missing required parameters | Verify payload against JSON schema |
| **401 Unauthorized** | Missing or expired token | Refresh Bearer JWT / API key |
| **403 Forbidden** | Quota limit reached | Purchase additional slots in Shop with Credits |
| **404 Not Found** | Target project or monitor not found | Check project ID / monitor ID |
| **409 Conflict** | Target endpoint already registered | Targets must be globally unique per user |
| **429 Too Many Requests** | Rate limit window exceeded | Implement exponential backoff |
| **500 Internal Error** | Backend unhandled exception | Check https://status.uptify.site |

### Standard Rate Limits
- Public Endpoints (`/status`, `/s/:id`, `/mc/:target`): 60–120 requests/minute
- SVG Badges (`/badge/:id`): 300 requests/minute
- Write Endpoints (Create Monitor, Incident): 30 requests/minute