Ask API

ورود با کلید API

کلید را در بخش «برنامه‌ها و کلیدها» داشبورد بسازید و در هدر Authorization به‌شکل Bearer بفرستید. همان کلید روتر برای /api/v1 است.

درخواست

بدنهٔ JSON فقط یک فیلد دارد: q، متنی از ۱ تا ۲۰۰۰ نویسه. فایل را با UTF-8 ذخیره کنید، چون ترمینال‌ها فارسی را در آرگومان خراب می‌کنند.

{
  "q": "ارزان ترین گوشی سامسونگ در دیجی کالا چیست؟"
}

curl -X POST "https://mcpfarsi.ir/api/v1/ask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @ask.json

درخواست‌های چندسرویسی و چندمرحله‌ای هم جواب می‌گیرند؛ مثلاً «ارزان‌ترین پرواز را پیدا کن، بعد برای همان روز هتل بگرد». دستیار خودش سرویس‌ها را پشت سر هم اجرا می‌کند.

جواب

نمونه (مقدارها نمایشی‌اند):

{
  "status": "ok",
  "answer": "…",
  "data": [
    {
      "server": "digikala",
      "tool": "dk_find_cheapest",
      "arguments": { "query": "…" },
      "isError": false,
      "result": { "…": "…" }
    }
  ],
  "usage": { "calls": 1, "ms": 0 }
}

• answer: پاسخ کوتاه به زبان درخواست.
• data: به‌ازای هر اجرا یک آیتم با server، tool، arguments، isError و result (خروجی خام).
• usage: calls تعداد اجراها و ms زمان کل.

فیلد status

• ok: دست‌کم یک اجرا موفق بود. پاسخ و خروجی خام در جواب هست.
• no_tool: در بازارچه قابلیتی که به این درخواست بخورد پیدا نشد.
• failed: اجراها خطا دادند یا مهلت تمام شد.

در وضعیت no_tool، data خالی است، از سهمیه چیزی کم نمی‌شود و answer همیشه یک جملهٔ ثابت است: برای سؤال فارسی «این سرویس نمی‌تواند به این درخواست پاسخ دهد: هیچ‌کدام از سرویس‌های در دسترس به آن مربوط نیست.» و برای زبان‌های دیگر همین معنی به زبان خود سؤال، مثلاً "This service cannot answer this request: none of the available services covers it."

کدهای HTTP

سهمیه و محدودیت‌ها

• سهمیه: هر اجرای موفق یک قابلیت، یک اجرا از سهمیهٔ طرح کم می‌کند. جستجوی قابلیت و اجرای ناموفق شمرده نمی‌شود. تعرفه‌ها
• فقط خواندن: این API فقط داده می‌خواند و هیچ‌وقت خرید، رزرو یا ثبت سفارش نمی‌کند. ابزارهایی که اثر جانبی دارند در آن اجرا نمی‌شوند.
• مهلت: هر درخواست حدود ۴۵ ثانیه وقت دارد. بعد از آن وضعیت failed می‌گیرید.
• خروجی بزرگ: خروجی بیشتر از ۶۴ کیلوبایت بریده می‌شود و truncated: true می‌گیرد. در این حالت result یک رشتهٔ نیمه‌کاره است، نه ساختار JSON.

{ "server": "…", "tool": "…", "isError": false, "result": "…", "truncated": true }