رفتن به محتوای اصلی

مستندات API گره

سرورها، DNS و صورتحساب‌ها را با چند خط کد مدیریت کنید.

REST · JSONنسخه ۱

API گره همان کارهایی را که در پنل انجام می‌دهید از طریق HTTP در اختیار اسکریپت‌ها، CI/CD و Terraform می‌گذارد. همه درخواست‌ها و پاسخ‌ها JSON هستند و مبالغ به تومان است.

نشانی پایه

https://gereh.virgule.studio/api/v1

مشخصات کامل در قالب OpenAPI 3.1 منتشر شده است و می‌توانید آن را در Postman، Insomnia یا هر تولیدکننده SDK وارد کنید.

احراز هویت

از پنل › SSH و API یک توکن بسازید. توکن فقط یک بار نمایش داده می‌شود و با grh_ شروع می‌شود. آن را در سربرگ Authorization بفرستید:

export GEREH_TOKEN="grh_..."
curl -s https://gereh.virgule.studio/api/v1/account -H "Authorization: Bearer $GEREH_TOKEN"
نوع توکنمجاز
فقط خواندنیفقط درخواست‌های GET
خواندن و نوشتنهمه درخواست‌ها

توکن‌ها می‌توانند تاریخ انقضا داشته باشند و هر زمان از پنل باطل شوند. اگر حساب تعلیق شود، توکن‌های آن هم کار نمی‌کنند.

محدودیت درخواست

هر توکن حداکثر ۱۲۰ درخواست در دقیقه مجاز است. بیش از آن پاسخ 429 برمی‌گردد؛ چند ثانیه صبر کنید و دوباره بفرستید.

خطاها

خطاها با کد وضعیت HTTP مناسب و این ساختار برمی‌گردند:

{ "error": { "message": "Not found" } }
کدمعنی
401توکن نیست، نادرست است یا منقضی شده
403توکن فقط خواندنی است یا سرویس معلق است
404منبع وجود ندارد یا متعلق به حساب شما نیست
422ورودی نامعتبر است
429از سقف درخواست عبور کرده‌اید

سرورها

متدمسیرتوضیح
GET/serversفهرست سرورها
GET/servers/{id}جزئیات یک سرور
POST/servers/{id}/actionsروشن، خاموش یا راه‌اندازی مجدد
curl -s https://gereh.virgule.studio/api/v1/servers -H "Authorization: Bearer $GEREH_TOKEN"

curl -s -X POST https://gereh.virgule.studio/api/v1/servers/srv-1042/actions \
  -H "Authorization: Bearer $GEREH_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"reboot"}'

مقدار action یکی از start، stop یا reboot است.

دامنه‌ها و DNS

متدمسیرتوضیح
GET/domainsفهرست دامنه‌ها
GET/domains/{id}/recordsرکوردهای DNS
POST/domains/{id}/recordsساخت رکورد
PUT/domains/{id}/records/{rid}جایگزینی رکورد
DELETE/domains/{id}/records/{rid}حذف رکورد
curl -s -X POST https://gereh.virgule.studio/api/v1/domains/dom-501/records \
  -H "Authorization: Bearer $GEREH_TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"A","name":"api","value":"185.143.232.17","ttl":300}'

نوع رکورد یکی از A، AAAA، CNAME، MX، TXT، NS، SRV یا CAA است؛ برای ریشه دامنه نام را @ بگذارید و priority فقط برای MX و SRV لازم است.

حساب و صورتحساب‌ها

متدمسیرتوضیح
GET/accountنام، ایمیل و موجودی کیف پول
GET/invoicesصورتحساب‌ها با وضعیت و مبلغ

Terraform

provider رسمی گره رکوردهای DNS را به‌صورت کد مدیریت می‌کند و مشخصات سرورها را می‌خواند:

terraform {
  required_providers {
    gereh = { source = "gereh/gereh" }
  }
}

provider "gereh" {} # GEREH_TOKEN از متغیر محیطی خوانده می‌شود

data "gereh_server" "web" {
  id = "srv-1042"
}

resource "gereh_dns_record" "api" {
  domain_id = "dom-501"
  type      = "A"
  name      = "api"
  value     = data.gereh_server.web.ipv4
  ttl       = 300
}

پشتیبانی

اگر به endpoint دیگری نیاز دارید یا رفتار API با این مستندات نمی‌خواند، از تیکت فنی خبر دهید.