رفتن به محتوا

مرجع API

جست‌وجو

وقتی فقط به نتایج جست‌وجو نیاز دارید و نمی‌خواهید مدل پاسخی بنویسد، مستقیم در منابع جست‌وجو کنید.

روند کار

  1. 01جست‌وجوی وب

روی هر عملیات بزنید تا همهٔ ورودی‌ها، request، response و کدهای وضعیت آن را ببینید.

جست‌وجوی وب

POST/v1/search
آدرس پایهٔ APIhttps://api.mahvashai.ir
احراز هویتAPI key پروژه یا JWT کاربر
Responseresponse مستقیم با قالب OpenAI
نوع محتواapplication/json

پارامترها

این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.

ناممحل ارسالنوعالزامیپشتیبانیتوضیحات
Idempotency-KeyHeaderstringاختیاریپشتیبانی می‌شودکلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
X-Request-IDHeaderstringاختیاریمخصوص مهوششناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
X-Mahvash-ProjectHeaderstringاختیاریمخصوص مهوشslug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
countryBodystringاختیاریمخصوص مهوشکشوری که نتایج باید بیشتر به آن مربوط باشند، با قالبی که موتور جست‌وجو می‌پذیرد.
max_resultsBodyintegerاختیاریمخصوص مهوشتعداد نتیجه برای هر عبارت جست‌وجو، بین ۱ تا ۲۰.
modelBodystringالزامیمخصوص مهوشslug یک مدل جست‌وجوی وب (از فهرست Web Search). مدل‌های جست‌وجو در /v1/models نمایش داده نمی‌شوند.
queryBodystring | array<value>الزامیمخصوص مهوشیک عبارت جست‌وجو یا فهرستی از عبارت‌ها. هر عبارت یک جست‌وجوی هزینه‌دار است؛ تعداد و طول آن‌ها با تنظیمات سرویس محدود می‌شود.
search_domain_filterBodyarray<value>اختیاریمخصوص مهوشنتایج را به این دامنه‌ها محدود می‌کند؛ حداکثر ۲۰ دامنه.

Request

curl -X POST 'https://api.mahvashai.ir/v1/search' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "model": "perplexity-search",
  "query": "probe"
}'

Response

{
  "object": "<value>",
  "model": "<value>",
  "results": [
    {
      "query_index": 0,
      "title": "<value>",
      "url": "<value>",
      "snippet": "<value>",
      "date": "<value>"
    }
  ],
  "usage": {
    "queries": 0
  }
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTPتوضیحات
200request با موفقیت انجام شد.
400request نامعتبر است.
401اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
402موجودی برای پرداخت هزینه کافی نیست.
403دسترسی لازم را ندارید.
404منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409تداخل در وضعیت یا idempotency.
429از سقف مجاز عبور کرده‌اید.
500خطای داخلی سرور.
502سرویس ارائه‌دهنده با خطا مواجه شد.
503یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست.