API'ye Başlangıç

UptimeWarden Public API v1 için başlangıç, token oluşturma, base URL, kimlik doğrulama header'ı, yanıt zarfı, hata kodları ve zaman sınırlı veri penceresi.

Bu sayfa, UptimeWarden ile entegrasyon yazan her geliştiricinin başlangıç noktasıdır. Sonunda elinizde çalışan bir API token'ı olacak, kimlik doğrulamayı bileceksiniz ve her v1 endpoint'inin kullandığı yanıt ve hata şekillerini tanıyacaksınız.

Zaten kod yazıyor musunuz? Beş dakikalık curl turu için API Hızlı Başlangıç sayfasına geçin veya tüm liste için API Endpoint'leri sayfasını açın.

Public API ne sunuyor?

Public API /api/v1/ altında çalışır ve şunları kapsar: monitor yönetimi (dashboard'daki her ayarla oluşturma, okuma, güncelleme ve silme), bir monitor'un gösterdiği referans listeleri (eskalasyon politikaları, webhook'lar, bölgeler), olay (incident) takibi, SSL inceleme, güvenlik analizi ve AI Sağlık Tahminleri. Monitor'lar ve referanslar publicId (bir ULID) ile anılır; monitor endpoint'leri dahili sayısal kimlik almaz ve döndürmez. Kanonik şema /api/docs/v1-openapi.json adresinde (OpenAPI 3.0) yayınlanır ve /api/docs altında interaktif Swagger UI olarak sunulur.

Yetenek	Endpoint ailesi
Monitor CRUD + sonuç + istatistik	`/api/v1/monitors/*`
Olay okuma / güncelleme / yorum	`/api/v1/incidents/*`
SSL durumu (genel + monitor başına)	`/api/v1/ssl/*`
Güvenlik analizi (önbellek + anlık)	`/api/v1/security/*`
AI Sağlık Tahminleri	`/api/v1/health/*`

Adım 1. Token oluşturun

Dashboard'a giriş yapın.
API Portal → API Tokens sekmesini açın.
Create API Token'a tıklayın, bir isim verin, bir izin grubu seçin ve token'ı kopyalayın. Token yalnızca bir kez gösterilir.

Token'lar uptw_ ön ekiyle başlar; böylece secret'i sızdırmadan loglarda fark edebilirsiniz. Tüm izin kataloğu ve rotasyon prosedürleri için API Token'ları sayfasına bakın.

export API_TOKEN=uptw_xxxxxxxxxxxxxxxxxxxxxxxx

Adım 2. İlk çağrınızı yapın

Her isteğin Authorization: Bearer <token> header'ına ihtiyacı vardır. Base URL: https://app.uptimewarden.online.

curl -sS "https://app.uptimewarden.online/api/v1/monitors?limit=1" \
  -H "Authorization: Bearer $API_TOKEN"

Başarılı bir liste yanıtı şu zarfa sarılır:

{
  "success": true,
  "data": [ /* monitor dizisi */ ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 42,
    "totalPages": 42,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Tekil kaynak çağrıları { success, data } döner. POST/PATCH/DELETE çağrıları genelde message alanı da ekler.

Hız limiti ve kotalar

Hız limitleri token başına, dakika başına uygulanır; sınır endpoint'e göre değişir:

Endpoint ailesi	Sınır
`GET /api/v1/monitors`, `GET /api/v1/monitors/:id/results`, `GET /api/v1/monitors/:id/stats`, `GET /api/v1/incidents`	120 istek/dk
`POST /api/v1/monitors`, `DELETE /api/v1/monitors/:id`, `PATCH /api/v1/incidents/:id`, `POST /api/v1/incidents/:id/comments`, `GET /api/v1/ssl/*`	60 istek/dk
`GET /api/v1/security/monitors/:id/analysis`	30 istek/dk
`POST /api/v1/security/monitors/:id/analyze`, `POST /api/v1/security/analyze`	10 istek/dk
`GET /api/v1/health/monitors/:id/predictions`	60 istek/dk

Her yanıt, kendi kendinizi throttle edebilmeniz için standart header'ları içerir:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 2026-04-27T10:31:00.000Z

Sınırı aştığınızda 429 Too Many Requests ve retryAfter (saniye) alırsınız. Her abonelik planına ayrı bir aylık API çağrı sınırı uygulanır, aşıldığında MONTHLY_API_LIMIT_EXCEEDED döner.

Yanıt zarfı

Her v1 endpoint'i ya:

{ "success": true, "data": ... }

ya da:

{
  "success": false,
  "error": {
    "code": "TIME_RANGE_EXCEEDED",
    "message": "Time range exceeds maximum allowed",
    "details": ["Requested: 10 days", "Maximum allowed: 7 days"]
  }
}

details opsiyonel açıklayıcı string dizisidir. Kimlik doğrulama hataları (401/403) daha sade { error, message } zarfını dönebilir; istemciler HTTP durum kodunu kanonik kabul etmelidir.

Hata kodları

HTTP	`error.code`	Ne zaman olur
`400`	`VALIDATION_ERROR`	Zorunlu body alanı eksik veya tip hatalı.
`400`	`INVALID_URL`	URL parametresi geçerli URI değil.
`401`	-	`Authorization` header'ı eksik/hatalı veya token geçersiz/süresi dolmuş.
`403`	-	Token gerekli izne sahip değil.
`403`	`TIME_RANGE_EXCEEDED`	Token tier'ının izin verdiğinden eski veri istendi (sonuçlar için 7 gün, olaylar için 30 gün).
`403`	`MONITOR_LIMIT_REACHED`	`POST /monitors`'da abonelik monitor sınırı doldu.
`404`	`NOT_FOUND`	Kaynak yok veya bu token'a görünmez.
`429`	-	Dakikalık hız limiti aşıldı. `retryAfter` alanına bakın.
`429`	`MONTHLY_API_LIMIT_EXCEEDED`	Planın aylık API çağrı kotası tükendi.
`500`	`INTERNAL_ERROR`	Sunucu tarafı arıza.

Geçmiş veri penceresi

API token'ları, sızan bir token'ın yıllarca veri çıkarmaması için bilinçli olarak dar pencerelere kapsamlandırılmıştır:

monitors:results:read, en fazla 7 gün kontrol sonucu.
incidents:read, en fazla 30 gün olay geçmişi.

Her iki sınır da her istekte uygulanır, istemci tarafı sayfalama ile aşılamaz. Daha geniş pencere için dashboard'u kullanın.

Sürüm politikası

v1 stabildir. Kıran değişiklikler v2 olarak gelir; eklemeli değişiklikler (yeni opsiyonel alan, yeni endpoint) sürüm artışı olmadan v1'e iner. /api/docs/v1-openapi.json adresindeki OpenAPI dokümanı kaynak kabul edilir; bu doküman sitesi ondan türetilir.

Sonraki adımlar

Çalışan beş çağrıyı API Hızlı Başlangıç ile geçin.
Tüm endpoint'leri API Endpoint'leri sayfasında inceleyin.
Token'ları ölçekte yönetmek için API Token'ları sayfasına bakın.
Endpoint'leri interaktif denemek için /api/docs (Swagger UI).