هر چه از رابط می‌کنی، با API هم بکن.

کلید API شخصی

از داشبورد (تنظیمات ← کلیدهای API) یک کلید بساز. کلید کامل فقط یک بار نمایش داده می‌شود؛ بعد روی سرور فقط هش آن می‌ماند. اسکوپ‌ها هم در همان لحظه‌ی ساخت قابل انتخاب‌اند.

plk_abc12345_xjMfA_8bL…YourSecret

«plk_» پیشوند ثابت · ۸ نویسهٔ بعدی شناسهٔ عمومی · بقیه مخفی.

اسکوپ‌ها

• tasks:read · tasks:write
• reminders:read · reminders:write
• habits:read · habits:write
• budget:read · budget:write
• ai:chat — تماس با دستیار از بیرون

API عمومی · نسخه‌ی ۱

آدرس پایه: https://api.planly.ir/api/public/v1/. هر درخواست یا سربرگ Authorization: Bearer plk_… می‌خواهد، یا X-Api-Key: plk_…. هر دو یک کار را می‌کنند.

تأیید هویت + me

curl -H "X-Api-Key: plk_abc12345_…" \
  https://api.planly.ir/api/public/v1/me/

{
  "workspace": { "id": "…", "name": "شخصی" },
  "owner":     { "id": "…", "email": "you@planly.ir" },
  "scopes":    ["tasks:read", "tasks:write"],
  "prefix":    "abc12345"
}

ساختن یک وظیفه

curl -X POST https://api.planly.ir/api/public/v1/tasks/ \
  -H "Authorization: Bearer plk_abc12345_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "بررسی بودجه", "due_at": "2026-04-27T10:00:00Z", "priority": "high"}'

یادآور تکراری

curl -X POST https://api.planly.ir/api/public/v1/reminders/ \
  -H "Authorization: Bearer plk_abc12345_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "نوشیدن آب", "next_fire_at": "2026-04-22T06:00:00Z",
       "freq": "daily", "interval": 1}'

خطاها

همهٔ خطاها پاکتِ استاندارد پلن‌لی دارند:

{
  "error": {
    "type":    "validation_error",
    "code":    "invalid_input",
    "message": "اعتبارسنجی ناموفق.",
    "detail":  [{"field": "due_at", "code": "invalid", "message": "زمان ISO-8601 معتبر نیست."}]
  }
}

سرور MCP

یک سرور Model Context Protocol با ترابری HTTP. هر کلاینت سازگاری — کلاد دسکتاپ، کرسر یا کد دلخواه خودت — می‌تواند به آن وصل شود و مستقیم از ابزارهای پلن‌لی استفاده کند.

نقطهٔ اتصال

URL:   https://api.planly.ir/mcp/
Auth:  Authorization: Bearer plk_…  (یا X-Api-Key)
Type:  jsonrpc 2.0, HTTP transport

پیکربندی Claude Desktop

{
  "mcpServers": {
    "planly": {
      "url":     "https://api.planly.ir/mcp/",
      "headers": { "Authorization": "Bearer plk_…" }
    }
  }
}

متدها

• initialize · handshake + discovery
• ping · بررسی سلامت
• tools/list · ابزارهای قابل‌دسترس با توجه به اسکوپ‌ها
• tools/call · فراخوانی یک ابزار با JSON input

یک tools/call کامل

curl -X POST https://api.planly.ir/mcp/ \
  -H "Authorization: Bearer plk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "bulk_create_tasks",
      "arguments": {
        "tasks": [
          {"title": "بررسی بودجه",         "priority": "high"},
          {"title": "پاسخ به ایمیل‌ها",     "priority": "med"},
          {"title": "آماده‌سازی ارائه",    "priority": "high"}
        ]
      }
    }
  }'