مستندات توسعه‌دهندگان KHAPI

به مستندات «خبر API» خوش آمدید. با استفاده از این سرویس می‌توانید به جریان لحظه‌ای اخبار ایران دسترسی داشته باشید، آن‌ها را با هوش مصنوعی فیلتر کنید و خروجی تمیز JSON دریافت کنید.

Base URL https://khapi.ir/api/v1

🔑 احراز هویت (Authentication)

برای استفاده از سرویس، باید کلید API خود را در هدر (Header) تمام درخواست‌ها ارسال کنید.

HTTP Header

x-api-key: YOUR_API_KEY

📡 دریافت لیست اخبار

متد: GET /news

این اندپوینت آخرین اخبار را بر اساس فیلترهای شما برمی‌گرداند. نام پارامترها و مقادیر زیر با نسخه فعلی v1 هماهنگ است.

پارامترهای ورودی (Query Params):

پارامتر	نوع	توضیحات
`q`	string	جست‌وجوی آزاد در عنوان، تگ و محتوای قابل جست‌وجو
`q_in_title`	string	جست‌وجو فقط در عنوان خبر
`sources`	string	نام دقیق منابع، کاماجدا؛ مثال: `IRNA,Zoomit`
`categories`	string	دسته‌ها، کاماجدا؛ مانند `اقتصادی,فناوری`
`exclude_sources`	string	حذف منابع مشخص، کاماجدا
`exclude_categories`	string	حذف دسته‌های مشخص، کاماجدا
`entities`	string	موجودیت‌های الزامی، کاماجدا با منطق AND
`exclude_entities`	string	حذف خبرهای دارای موجودیت‌های مشخص
`from_date`	date/datetime	ابتدای بازه به‌صورت ISO یا `YYYY-MM-DD`
`to_date`	date/datetime	انتهای بازه به‌صورت ISO یا `YYYY-MM-DD`
`sort_by`	enum	`published_at` یا `relevancy`
`has_image`	boolean	فقط خبرهای دارای تصویر؛ پیش‌فرض `false`
`page`	int	شماره صفحه؛ حداقل ۱ و پیش‌فرض ۱
`page_size`	int	تعداد نتیجه در صفحه؛ بین ۱ تا ۱۰۰ و پیش‌فرض ۱۰

نمونه درخواست (cURL):

Bash

curl -X GET "https://khapi.ir/api/v1/news?q=هوش+مصنوعی&categories=فناوری&page_size=5" \
     -H "x-api-key: YOUR_API_KEY"

نمونه پاسخ (JSON):

{
  "status": "success",
  "total_results": 1,
  "page": 1,
  "page_size": 5,
  "total_pages": 1,
  "articles": [
    {
      "id": 123456,
      "source": "Zoomit",
      "title": "هوش مصنوعی جدید گوگل معرفی شد",
      "summary": "گوگل امروز از مدل جدید جمینای رونمایی کرد...",
      "url": "https://zoomit.ir/...",
      "published_at": "2026-08-15T10:30:00",
      "image_url": "https://cdn.zoomit.ir/...",
      "tags": ["هوش مصنوعی", "گوگل"],
      "categories": ["فناوری"],
      "entities": ["هوش مصنوعی", "گوگل"]
    }
  ]
}

⚠️ مدیریت خطاها

در صورت بروز مشکل، API کدهای استاندارد HTTP را برمی‌گرداند.

کد	پیام	علت
`401`	Unauthorized	هدر `x-api-key` ارسال نشده است.
`403`	Forbidden	کلید API نامعتبر/غیرفعال است یا IP درخواست مجاز نیست.
`422`	Validation Error	پارامترهایی مانند تاریخ، مرتب‌سازی یا صفحه‌بندی نامعتبر هستند.
`429`	Too Many Requests	تعداد درخواست‌های شما از حد مجاز گذشته است.

پاسخ‌های خطای احراز هویت علاوه بر فیلد سازگارِ error، شامل code ماشین‌خوان و message فارسی هستند.

هدرهای سهمیه

درخواست‌های احرازشده این هدرها را برای نمایش و پایش سهمیه برمی‌گردانند:

هدر	توضیح
`X-RateLimit-Limit`	سقف درخواست روزانه پلن
`X-RateLimit-Remaining`	تعداد درخواست باقی‌مانده امروز
`X-RateLimit-Reset`	زمان reset بعدی به‌صورت Unix timestamp