‏Oh Dear API: بهینه‌سازی برای ایجنت‌های هوش مصنوعی

ایجنت‌های کدنویسی مبتنی بر هوش مصنوعی مثل Claude Code و Codex دیگه فقط کد نمی‌نویسن؛ اون‌ها API صدا می‌زنن، جواب‌ها رو تفسیر می‌کنن و بر اساس داده‌ها تصمیم می‌گیرن. به همین دلیل، تیم Oh Dear یه سری تغییر هدفمند روی API خودشون پیاده کردن تا این ایجنت‌ها بتونن هوشمندتر و مستقل‌تر عمل کنن.

مهم‌ترین تغییر، اضافه شدن تاریخچه‌ی اجرای چک‌هاست. قبلاً API فقط آخرین نتیجه رو برمی‌گردوند، ولی الان می‌شه لیست کامل اجراهای گذشته رو برای چک‌هایی مثل broken links، mixed content، certificate health و sitemap گرفت. این یعنی ایجنت می‌تونه بپرسه «لینک‌های خراب دیروز رو با امروز مقایسه کن» و واقعاً جواب درست بگیره.

{
  "data": [
    {
      "id": 98765,
      "check_type": "broken_links",
      "result": "succeeded",
      "started_at": "2026-03-17T00:30:00+00:00",
      "ohdear_url": "https://ohdear.app/monitors/1234/check/broken-links/report/98765"
    }
  ]
}

می‌شه روی بازه‌ی زمانی و وضعیت نتیجه (succeeded، warning، failed) فیلتر زد و بعد با run_id، جزئیات کامل اون اجرای خاص رو fetch کرد. داده‌ها تا حدود ۱۰ روز نگه داشته می‌شن.

تغییر بعدی اضافه شدن فیلد ohdear_url به همه‌ی پاسخ‌هاست. قبلاً ایجنت باید خودش URL داشبورد رو می‌ساخت که احتمال خطا داشت. الان هر پاسخ API یه لینک مستقیم به صفحه‌ی مربوطه توی داشبورد داره. ایجنت می‌تونه به کاربر بگه «۳ لینک خراب جدید داری، گزارش کامل اینجاست» و یه لینک واقعی و درست بده.

همچنین هر پاسخ API حالا یه documentation_url هم داره. وقتی ایجنت با یه فیلد ناآشنا مواجه می‌شه، می‌تونه مستقیم مستندات مرتبط رو بخونه. نکته‌ی جالب اینه که مستندات Oh Dear حالا به‌صورت Markdown خالص هم سرو می‌شن:

curl -H 'Accept: text/markdown' \
  https://ohdear.app/docs/features/broken-links-detection

این کار حجم توکن مصرفی ایجنت رو به‌شدت کاهش می‌ده. مثلاً صفحه‌ی مستندات Monitor API از ۳۸۶ کیلوبایت HTML به ۲۲.۹ کیلوبایت Markdown می‌رسه؛ یعنی ۹۴٪ کمتر! برای دریافت Markdown می‌شه یا هدر Accept: text/markdown فرستاد یا پسوند .md به آخر URL اضافه کرد.

برای آدیت کامل‌تر سایت، دو endpoint جدید هم اضافه شده. یکی summary که تعداد کل URL های کراول‌شده، تعداد داخلی و خارجی و تفکیک بر اساس نوع (image, link, script و ...) رو می‌ده:

{
  "data": {
    "total": 1234,
    "internal": 800,
    "external": 434,
    "by_type": {
      "image": 250,
      "link": 900,
      "script": 40
    }
  }
}

دیگری details که لیست کامل paginated همه‌ی URL های کراول‌شده رو با فیلدهای type و error_message برمی‌گردونه. اینجوری ایجنت نه فقط می‌دونه چی خراب شده، بلکه می‌فهمه نسبت خراب به سالم چقدره و چه نوع منابعی مشکل دارن. هر دو endpoint هم run_id رو ساپورت می‌کنن.

کلاً الگویی که Oh Dear دنبال می‌کنه اینه: همه‌ی چیزی که ایجنت نیاز داره رو داخل پاسخ API بذار تا خودکفا باشه. علاوه بر این تغییرات، یه فایل llms.txt و یه MCP server کامل برای اینتگریشن عمیق‌تر با دستیارهای هوش مصنوعی هم وجود داره.

نکات کلیدی:

• تاریخچه‌ی اجرای چک‌ها (تا ۱۰ روز) با فیلتر تاریخ و وضعیت اضافه شد
• فیلد ohdear_url در همه پاسخ‌ها برای لینک مستقیم به داشبورد
• مستندات به‌صورت Markdown سرو می‌شن و تا ۹۶٪ توکن کمتری مصرف می‌کنن
• دو endpoint جدید برای summary و details همه URL های کراول‌شده
• هر پاسخ حالا documentation_url هم داره تا ایجنت بتونه خودش مستندات بخونه
• پشتیبانی از llms.txt و MCP server برای اینتگریشن عمیق‌تر