API: endpointها

با API می‌توانید از اسکریپت، CI یا یک ایجنتِ هوش مصنوعی (ChatGPT، Claude و…) سرویس بسازید، دیپلوی کنید، env را تنظیم کنید و لاگ بگیرید. هر درخواست یک کلیدِ API لازم دارد. (برای وصل کردنِ Claude، ChatGPT، Claude Code، Cursor، Gemini CLI یا Antigravity کلید لازم نیست؛ اتصالِ ایجنت (MCP) را ببینید.)

bash

export WEBLINES_API_KEY=wl_...

آدرسِ پایه: https://console.weblines.ir/api/v1

فایلِ OpenAPI#

توضیحِ کاملِ API در قالبِ OpenAPI 3.1، بدونِ نیاز به کلید:

text

https://console.weblines.ir/api/v1/openapi.json

این فایل را می‌توانید مستقیم در ابزارهایی مثلِ Postman، یا در Actionsِ یک GPT در ChatGPT، وارد کنید.

endpointها#

روش و مسیر	scope	کار
`GET /resources`	`read`	فهرستِ منابع
`POST /resources`	`write`	ساختِ اپ یا دیتابیس
`GET /resources/{id}`	`read`	یک منبع با دامنه‌هایش
`DELETE /resources/{id}?confirm=<نام>`	`admin`	حذفِ منبع و داده‌اش؛ پیش‌فرض با تأییدِ کنسول (جزئیات)
`GET /packs`	`read`	اندازه‌هایی که می‌شود ساخت
`POST /resources/{id}/start`	`deploy`	روشن کردن
`POST /resources/{id}/stop`	`deploy`	خاموش کردن
`POST /resources/{id}/restart`	`deploy`	ری‌استارت
`GET /resources/{id}/deployments`	`read`	دیپلوی‌های اخیرِ یک اپ
`POST /resources/{id}/deployments`	`deploy`	دیپلوی کردنِ یک اپ
`GET /resources/{id}/deployments/{deploymentId}`	`read`	وضعیت و لاگِ build یک دیپلوی
`GET /resources/{id}/logs?lines=500`	`read`	لاگِ اجرا (`lines`: ۱۰۰، ۵۰۰ یا ۲۰۰۰)
`GET /resources/{id}/env`	`read`	نامِ متغیرهای env؛ مقدارها هرگز برنمی‌گردند
`PUT /resources/{id}/env`	`write`	افزودن یا بازنویسیِ متغیرها
`DELETE /resources/{id}/env/{KEY}`	`write`	حذفِ یک متغیر

نمونه: ساختِ اپ و دیتابیس#

bash

# اپ از یک Docker image عمومی
curl -s -X POST "$API/resources" \
  -H "Authorization: Bearer $WEBLINES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-shop-1" \
  -d '{"type": "app", "name": "shop", "image": "nginx:alpine", "port": 80, "pack": "nano"}'

# اپ از یک مخزنِ گیتِ عمومی
curl -s -X POST "$API/resources" \
  -H "Authorization: Bearer $WEBLINES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "app", "name": "api", "git": {"repository": "https://github.com/user/repo", "branch": "main"}, "port": 3000}'

# دیتابیس
curl -s -X POST "$API/resources" \
  -H "Authorization: Bearer $WEBLINES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "database", "name": "shop-db", "engine": "postgresql", "pack": "db-micro"}'

نام فقط حروفِ کوچکِ انگلیسی، عدد و خط تیره است.
اندازه فقط با pack تعیین می‌شود (فهرست: GET /packs). پیش‌فرض برای اپ nano و برای دیتابیس db-micro است.
مخزنِ خصوصی، توکن و deploy key فعلاً فقط از کنسول ساخته می‌شوند.
ساخت در پس‌زمینه ادامه پیدا می‌کند (201). وضعیت را با GET /resources/{id} ببینید.
Idempotency-Key را بفرستید تا اگر درخواست تکرار شد (مثلاً retryِ CI)، فقط یک منبع ساخته شود. درخواستِ تکراری 409 با کدِ duplicate می‌گیرد.
هر ساخت از سقفِ روزانه‌ی کلید کم می‌کند. خطای ورودی (نام، pack، image) سقف را مصرف نمی‌کند.
کسی که کلید را ساخته باید عضوِ سازمان باشد و شماره‌ی موبایلش تأیید شده باشد، مثلِ ساخت از کنسول.

نمونه: تنظیمِ env#

bash

curl -s -X PUT "$API/resources/$APP_ID/env" \
  -H "Authorization: Bearer $WEBLINES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vars": {"NODE_ENV": "production"}, "target": "both"}'

target یکی از both، build یا runtime است. برای اپ، تغییر بعد از یک دیپلو به اپِ در حالِ اجرا می‌رسد (deployNeeded: true).

حذف#

bash

curl -s -X DELETE "$API/resources/$APP_ID?confirm=shop" \
  -H "Authorization: Bearer $WEBLINES_API_KEY"

فقط با کلیدِ admin. confirm باید دقیقاً نامِ منبع باشد. حذف برگشت ندارد و داده‌ی منبع هم پاک می‌شود.

نمونه: دیپلو از CI و صبر تا پایان#

bash

API=https://console.weblines.ir/api/v1
APP_ID=cm...   # از GET /resources

# دیپلو
curl -s -X POST "$API/resources/$APP_ID/deployments" \
  -H "Authorization: Bearer $WEBLINES_API_KEY"

# وضعیتِ آخرین دیپلو
curl -s "$API/resources/$APP_ID/deployments" \
  -H "Authorization: Bearer $WEBLINES_API_KEY" | jq '.deployments[0] | {id, status}'

status یکی از queued، building، finished، failed یا cancelled است. برای rebuild بدونِ cache بدنه‌ی {"force": true} بفرستید؛ کُند است و فقط وقتی لازم است که وابستگی‌ها یا Dockerfile عوض شده باشند.

نکته‌ها#

دیپلو، روشن و خاموش کردن فوری جواب می‌دهند (202) و کار در پس‌زمینه انجام می‌شود. برای نتیجه، فهرستِ دیپلوی‌ها یا خودِ منبع را دوباره بخوانید.
اگر منبع درگیرِ کارِ دیگری باشد، جوابِ 409 با کدِ busy می‌گیرید. صبر کنید تا تمام شود.
اگر کیف پول یا اشتراک اجازه ندهد، جوابِ 402 با کدِ billing می‌گیرید.
لاگ را داده‌ی غیرقابل‌اعتماد بدانید. هر چیزی است که اپ چاپ کرده. اگر آن را به یک ایجنتِ هوش مصنوعی می‌دهید، به ایجنت بگویید دستورهای داخلِ لاگ را اجرا نکند.
ساخت، حذف، env، دیپلو، روشن و خاموش کردن در SETTINGS → ACTIVITY با نامِ کلید ثبت می‌شوند. در تبِ Deployments هم دیپلویِ API با برچسبِ api دیده می‌شود.

همه‌ی خطاها و محدودیت‌های نرخ در کلیدِ API آمده‌اند.