Dokümantasyon 08 / 10

REST API

REST API ile monitörleri, olayları, bakımları ve status sayfalarını programatik olarak yönetebilirsiniz. Tüm istek ve yanıtlar JSON'dur; zaman değerleri ISO 8601 biçimindedir. Makine tarafından okunabilir tanım: OpenAPI 3.1 (openapi.json).

Temel adres: https://isletme.net.tr/api/v1

Kimlik doğrulama

API anahtarlarını panelde API anahtarları sayfasından oluşturabilirsiniz (paketinizde API erişimi olmalı ve parolanızı yeniden onaylamanız gerekir). Anahtar yalnızca oluşturulduğu anda gösterilir; sistemde yalnızca özeti saklanır. Anahtarı Authorization başlığında gönderin:

Authorization: Bearer ism_AbCd1234_<40 karakter>

Anahtarlar tek bir organizasyona bağlıdır, isteğe bağlı olarak son kullanma tarihi taşır ve istediğiniz zaman iptal edilebilir. Organizasyon askıya alınırsa API erişimi kapanır.

Kapsamlar (scopes)

Her anahtar yalnızca kendisine verilen kapsamlardaki uç noktalara erişebilir:

Kapsam	Uç noktalar
`monitors:read`	`GET /monitors`, `GET /monitors/{id}`
`monitors:write`	`POST /monitors`, `PATCH /monitors/{id}`, `DELETE /monitors/{id}`, `POST /monitors/{id}/pause`, `POST /monitors/{id}/resume`
`results:read`	`GET /monitors/{id}/results`, `GET /monitors/{id}/stats`
`incidents:read`	`GET /incidents`, `GET /incidents/{id}`, `GET /outages`
`incidents:write`	`POST /incidents`, `POST /incidents/{id}/updates`
`maintenances:read`	`GET /maintenances`
`maintenances:write`	`POST /maintenances`
`status_pages:read`	`GET /status-pages`, `GET /status-pages/{id}`
`channels:read`	`GET /channels`
`usage:read`	`GET /usage`
`status_pages:write`, `channels:write`	Tanımlıdır; şu anda bu kapsamları kullanan bir uç nokta yoktur.

Uç noktalar

Yöntem ve yol	Açıklama
`GET /monitors`	Monitör listesi. `state` ile filtrelenebilir (`healthy`, `suspected_down`, `down`, `recovering`, `unknown`, `paused`).
`POST /monitors`	Monitör oluşturur (201). Alanlar izleme türleri belgesindedir. Heartbeat türünde yanıtta bir kez `heartbeat_url` döner.
`GET /monitors/{id}`	Tek monitör.
`PATCH /monitors/{id}`	Kısmi güncelleme: gönderilmeyen alanlar korunur, tür değiştirilemez, boş bırakılan sırlar değişmez.
`DELETE /monitors/{id}`	Siler (204, gövdesiz).
`POST /monitors/{id}/pause`, `/resume`	Duraklatır / devam ettirir.
`GET /monitors/{id}/results`	Ham ölçümler, yeniden eskiye. `from`/`to` (ISO 8601); varsayılan son 24 saat, aralık en fazla 7 gün. Ham veri paketinizin saklama süresiyle sınırlıdır.
`GET /monitors/{id}/stats`	`days` (1–90, varsayılan 30) için erişilebilirlik özeti ve son 24 saatin yanıt süresi yüzdelikleri.
`GET /outages`	Monitör kesintileri. `open=1` yalnızca devam edenleri döndürür.
`GET /incidents`, `GET /incidents/{id}`	Status sayfası olayları; tekil kayıtta güncellemeler (iç notlar dahil) döner.
`POST /incidents`	Olay açar: `status_page_id`, `title`, `status`, `impact` (`none`/`minor`/`major`/`critical`), `body`, isteğe bağlı `components` (bileşen kimliği → `degraded`/`partial_outage`/`major_outage`) ve `notify` (varsayılan `true`).
`POST /incidents/{id}/updates`	Güncelleme ekler: `status`, `body`, `visibility` (`public`/`internal`), `notify`.
`GET /maintenances`, `POST /maintenances`	Bakım listesi / oluşturma: `status_page_id`, `title`, `starts_at`, `ends_at`, `timezone` (varsayılan UTC), `components` (kimlik listesi), `alert_policy` (`suppress`/`notify`), `auto_start`, `notify`.
`GET /status-pages`, `GET /status-pages/{id}`	Status sayfaları; tekil kayıtta hesaplanmış güncel durum.
`GET /channels`	Bildirim kanalları (yapılandırma sırları dönmez).
`GET /usage`	Paket kodu, kullanım ve haklar.
`GET /public/status/{slug}`	Kimlik doğrulamasız. Yalnızca yayınlanmış, herkese açık veya listelenmemiş sayfaların özet durumu. CORS'a açıktır.

Örnek

curl -sS https://isletme.net.tr/api/v1/monitors \
  -H "Authorization: Bearer $ISLETME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-2026-01-01-001" \
  -d '{"name":"Ana site","type":"http","target":"https://www.ornek.com.tr","interval_seconds":300}'

Sayfalama

Liste uç noktaları page ve per_page (1–100, varsayılan 25) parametrelerini kabul eder:

{
  "data": [ … ],
  "meta": { "page": 1, "per_page": 25, "total": 42, "last_page": 2 }
}

Hata biçimi

Tüm hatalar aynı yapıdadır:

{ "error": { "code": "not_found", "message": "Kayıt bulunamadı." } }

Doğrulama hatalarında alan bazlı mesajlar fields, iş kuralı ihlallerinde ilgili alan field içinde döner:

{ "error": { "code": "validation_failed", "message": "Gönderilen veriler geçersiz.", "fields": { "interval_seconds": ["…"] } } }

HTTP	Kodlar
401	`unauthenticated`
403	`insufficient_scope`, `plan_forbidden`, `organization_suspended`, `forbidden`
404	`not_found`
409	`idempotency_in_progress`
422	`validation_failed`, `invalid_range`, `quota_exceeded`, `invalid_idempotency_key`, `idempotency_mismatch` ve iş kuralı kodları
429	`rate_limited`
503	`api_disabled` (API geçici olarak kapalı)

Idempotency-Key

POST isteklerinde Idempotency-Key başlığı gönderebilirsiniz (8–100 karakter; harf, rakam, _ . : -).
Aynı anahtar ve aynı gövdeyle tekrar gönderilen istek işlemi yinelemez; kayıtlı yanıt Idempotent-Replayed: true başlığıyla döner.
Aynı anahtar farklı bir gövdeyle kullanılırsa 422 idempotency_mismatch; ilk istek hâlâ işleniyorsa 409 idempotency_in_progress döner.
Anahtarlar API anahtarı bazındadır ve 24 saat saklanır. Sunucu hatasıyla (5xx) biten istekler kaydedilmez; aynı anahtarla yeniden deneyebilirsiniz.

İstek limitleri

Kimlik doğrulamalı uç noktalarda limit, API anahtarı başına dakikadaki istek sayısıdır ve paketinize bağlıdır (bkz. paketler).
Kimlik doğrulamasız public uç noktalarda IP başına dakikada 120 istek sınırı vardır.
Yanıtlarda X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları bulunur. Limit aşılırsa 429 ve Retry-After döner.

Notlar

stats yanıtındaki erişilebilirlik alanlarının anlamı ölçüm yöntemi belgesinde açıklanır; değerler teknik ölçümdür, sözleşmesel SLA değildir.
Monitör yanıtlarında hedef adres maskelenir; sorgu dizeleri ve sırlar dönmez.

Bu belge ürünün mevcut davranışını anlatır. Bir tutarsızlık görürseniz lütfen bize bildirin.