İçeriğe geç
Hostio
English Ücretsiz başla

API belgesi

Hostio API'si

Sunucularınızı ve sitelerinizi okuyun, kendi araçlarınızdan site açın ve sertifika isteyin. HTTPS üzerinden JSON, her entegrasyona bir anahtar.

curl https://hostio.talivio.com/api/v1/servers/12 \
  -H "Authorization: Bearer $HOSTIO_TOKEN" \
  -H "Accept: application/json"

API anahtarları

API, Pro ve Agency planlarıyla gelir. Anahtarları ekip sahibi ya da yöneticisi kullanıcı menüsü → API keys altında oluşturur. Anahtar onu oluşturan kişinin değil, ekibindir.

  • Yetkiler: entegrasyonun yalnız ihtiyacı olanları işaretleyin. Yetkisi olmayan bir çağrı, Hostio kimliğe bakmadan 403 ile reddedilir.
  • Siteler: anahtarı bazı sitelerle sınırlayın ya da ekibin bütün siteleri (sonradan eklenecekler dahil) için boş bırakın.
  • Adresler: anahtarın kullanılabileceği IP ya da CIDR aralıklarından oluşan isteğe bağlı liste.
  • Webhook sunucuları: sertifika webhook_url adresinin gösterebileceği ana makineler.
  • Bitiş: isteğe bağlı. Anahtar o günün sonuna kadar çalışır.

Anahtar bir kez gösterilir. Hostio yalnız özetini saklar. İptal hemen geçerli olur.

Authorization: Bearer <anahtarınız>

Yetkiler: servers:read, sites:read, certificates:read, databases:read, sites:create, certificates:write, domains:write.

Hız sınırları

  • Anahtar başına dakikada 120 okuma (GET).
  • Anahtar başına dakikada 30 yazma (POST, DELETE); okumalardan ayrı sayılır.
  • Geçerli anahtarı olmayan çağrılar için adres başına dakikada 60 istek.

Sınır aşılınca yanıt Retry-After (saniye) ile 429'dur. Her yanıt X-RateLimit-Limit ve X-RateLimit-Remaining taşır. Sertifika isteği ayrıca site başına saatte 10 yeni siparişle sınırlıdır.

Hatalar

Her hata message içeren bir JSON'dur. 422 alan başına bir liste olarak errors ekler. Bir reddin mesajı refused: ile başlar ve nedenini söyler.

{"message": "This token lacks the \"sites:create\" ability."}
  • 401: anahtar yok, anahtar yanlış, süresi dolmuş ya da iptal edilmiş.
  • 402: ekibin planında API erişimi yok.
  • 403: anahtarın yetkisi yok ya da listesi dışındaki bir adresten kullanılıyor.
  • 404: bu ekip için böyle bir kayıt yok. Başka bir ekibin kimliği de 403 değil, 404'tür.
  • 409: reddedildi; neden message içinde.
  • 422: istek gövdesi ya da bir sorgu parametresi geçersiz.
  • 429: hız sınırı; Retry-After kadar bekleyin.
  • 501: uç var ama bu işlem yapılmadı; mesaj nedenini söyler.
  • 502, 503: sunucu ya da siteyi hâlâ yöneten panel değişikliği şu an tamamlayamadı; sonra yeniden deneyin (gönderildiyse Retry-After sonrasında).

Listeler

Liste uçları {"data": [...], "meta": {...}} döner. Sayfayı page ve per_page ile isteyin (varsayılan 50, en çok 100).

Uzun süren yazmalar

Bir yazma sunucuda çalışırken istek 25 saniyeye kadar bekler. Bittiyse yanıt 201 (kaldırmada 204) olur. Hâlâ sürüyorsa yanıt o ana kadarki durumla 202'dir; kaynak değişene kadar yeniden okuyun (yeni site creating durumundan active ya da failed durumuna geçer).

Yazmaları tekrarlamak güvenlidir: aynı isteği yeniden göndermek işi iki kez yapmak yerine mevcut sonuçla 200 döner.

Uçlar

Yollar https://hostio.talivio.com/api/v1 adresine göredir. {server} ve {site}, panelin ve liste uçlarının gösterdiği Hostio kimlikleridir.

GET /api/v1/servers/{server}

Bir sunucu. Yetki: servers:read.

{"data": {"id": 12, "name": "web-1", "ip": "203.0.113.10", "ipv6": null,
          "hostname": "web-1", "status": "ready"}}

status: pending, provisioning, ready ya da unreachable.

GET /api/v1/servers/{server}/sites

Bir sunucudaki siteler, kimlik sırasıyla. Yetki: sites:read.

  • page, per_page: Listeler'e bakın.
{"data": [{"id": 152, "server_id": 12, "domain": "shop.example.com", "...": "…"}],
 "meta": {"current_page": 1, "last_page": 1, "per_page": 50, "total": 1}}

Bazı sitelerle sınırlı bir anahtar yalnız onları görür.

GET /api/v1/sites/{site}

Bir site. Yetki: sites:read.

{"data": {"id": 152, "server_id": 12, "domain": "shop.example.com",
          "aliases": ["www.shop.example.com"], "status": "active",
          "project_type": "laravel", "php_version": "8.4", "ploi_php_version": null,
          "system_user": "shop", "web_directory": "/public", "has_repository": true,
          "last_deploy_at": "2026-10-30T09:12:44Z", "disk_usage_mb": null,
          "created_at": "2026-10-20T11:02:10Z", "provider_created_at": null,
          "ploi_site_id": null, "owner": "box"}}

status çalışan bir site için active ya da broken, Hostio onu oluştururken creating ya da failed olur. disk_usage_mb henüz ölçülmez, hep null'dır.

GET /api/v1/sites/{site}/certificates

Bir sitenin sertifikaları, tenant'larınınkiler dahil. Yetki: certificates:read.

  • domain (isteğe bağlı): yalnız bu adı kapsayan sertifikalar; *.example.com, a.example.com adını kapsar.
  • page, per_page: Listeler'e bakın.
{"data": [{"id": 88, "site_id": 152, "tenant": null,
           "domains": ["shop.example.com", "www.shop.example.com"],
           "status": "issued", "installed": true, "type": "letsencrypt",
           "method": "http01", "expires_at": "2027-01-28T09:00:00Z",
           "created_at": "2026-10-30T09:00:00Z"}],
 "meta": {"current_page": 1, "last_page": 1, "per_page": 50, "total": 1}}

status: requested, issued ya da failed. 30 dakika sonra hâlâ requested olan istek failed olur.

GET /api/v1/servers/{server}/databases

Bir sunucudaki veritabanları ve onları kullanan siteler. Yetki: databases:read.

  • page, per_page: Listeler'e bakın.
{"data": [{"id": 40, "server_id": 12, "name": "shop", "type": "mysql", "system": false,
           "sites": [{"id": 152, "domain": "shop.example.com", "via": "env"}]}],
 "meta": {"current_page": 1, "last_page": 1, "per_page": 50, "total": 1}}

via Hostio'nun siteyi nasıl bağladığını söyler: .env dosyası, wp-config.php dosyası ya da onu oluşturan panel. system sunucunun kendi veritabanlarını işaretler.

POST /api/v1/servers/{server}/sites

Site oluşturun: sistem kullanıcısı, PHP-FPM havuzu ve nginx vhost. Yetki: sites:create.

  • domain (zorunlu): sitenin alan adı.
  • php_version (isteğe bağlı): kurulu bir PHP sürümü; verilmezse sunucunun varsayılanı.
  • system_user (isteğe bağlı): verilmezse alan adından türetilir. reuse_system_user: siteyi mevcut bir kullanıcının altına koymak için true.
  • web_directory (isteğe bağlı): varsayılan /public. project_type (isteğe bağlı): verildiği gibi saklanır.
{"domain": "shop.example.com", "php_version": "8.4", "web_directory": "/public"}
201 {"data": {"id": 153, "domain": "shop.example.com", "status": "active", "...": "…"}}
202 {"data": {"id": 153, "domain": "shop.example.com", "status": "creating", "...": "…"}}

202 gelirse status active ya da failed olana kadar GET /api/v1/sites/{id} okuyun. Bazı sitelerle sınırlı bir anahtar site oluşturamaz.

POST /api/v1/sites/{site}/certificates

Sitenin kendi adları için Let's Encrypt sertifikası isteyin. Yetki: certificates:write.

  • domains (zorunlu): her biri sitenin alan adı ya da takma adlarından biri olan 1 ile 100 arası ad.
  • method (zorunlu): http01. Joker adlar ve dns01 reddedilir.
  • webhook_url (isteğe bağlı): 443 portunda https, anahtarın webhook sunucularından birinde.
{"domains": ["shop.example.com", "www.shop.example.com"], "method": "http01",
 "webhook_url": "https://hooks.example.com/hostio"}
201 {"data": {"id": 89, "site_id": 152, "status": "requested", "installed": false, "...": "…"}}

Geçerli bir sertifika 30 gün daha bütün adları kapsıyorsa yanıt o sertifikayla 200'dür. Sertifika verilince kurulur (installed: true); webhook o anda bir kez tetiklenir.

Webhook gövdesi: event (certificate.installed), site_id, certificate_id, tenant, domains, installed_at. Başlıklar: x-servio-event, x-servio-timestamp ve x-servio-signature: sha256=<hex>; bu, <timestamp>.<body> metninin ekibinizin webhook imza anahtarıyla HMAC-SHA256'sıdır. Anahtarı Hostio desteği verir ve bir kez gösterir.

POST /api/v1/sites/{site}/certificates/{certificate}/activate

Yapılmadı. Yetki: certificates:write.

501 {"message": "Not implemented. There is nothing to activate: …"}

Etkinleştirilecek bir şey yok: Hostio üzerinden istenen sertifika verildiği anda kurulur. Özel sertifikalar desteklenmez.

POST /api/v1/sites/{site}/tenants

Çok kiracılı bir siteden bir alan adı daha sunun. Yetki: domains:write.

  • domain (zorunlu): tenant'ın alan adı.
{"domain": "client-a.example.com"}
201 {"data": {"domain": "client-a.example.com", "state": "attached"}}
202 {"data": {"domain": "client-a.example.com", "state": "attaching"}}

Alan adı zaten bağlıysa 200. Başka bir site tutuyorsa 409.

DELETE /api/v1/sites/{site}/tenants/{domain}

Bir tenant alan adını sunmayı bırakın. Yetki: domains:write.

204 (no body)
202 {"data": {"domain": "client-a.example.com", "state": "detaching"}}

Sitede böyle bir tenant yoksa 404: zaten kaldırılmış sayın.

POST /api/v1/sites/{site}/tenants/{domain}/certificates

Bir tenant için sertifika isteyin. Yetki: certificates:write.

  • domains (zorunlu): 1 ile 10 arası ad.
  • method (zorunlu): http01 ya da dns01.
  • webhook_url (isteğe bağlı): site sertifikasındaki gibi.
{"domains": ["client-a.example.com"], "method": "http01"}
201 {"data": {"id": 90, "tenant": "client-a.example.com", "status": "requested", "...": "…"}}

Aynı tenant için açık bir istek varsa 200.

DELETE /api/v1/sites/{site}/aliases/{domain}

Bir siteden takma ad kaldırın. Yetki: domains:write.

204 (no body)
202 {"data": {"domain": "old.example.com", "state": "removing"}}

Sitenin ana alan adı asla kaldırılmaz (409). Sertifikalara dokunulmaz. Takma ad ekleyen bir uç yoktur.

Bütün rehberler

Ücretsiz sağlık taramasıyla başlayın.

Ücretsiz başla

Talivio'dan: TCSR A11yProof PrivaScan