مرجع API
جستوجو
وقتی فقط به نتایج جستوجو نیاز دارید و نمیخواهید مدل پاسخی بنویسد، مستقیم در منابع جستوجو کنید.
روند کار
روی هر عملیات بزنید تا همهٔ ورودیها، request، response و کدهای وضعیت آن را ببینید.
جستوجوی وب
POST
/v1/searchآدرس پایهٔ API
https://api.mahvashai.irاحراز هویتAPI key پروژه یا JWT کاربر
Responseresponse مستقیم با قالب OpenAI
نوع محتوا
application/jsonپارامترها
این جدول همهٔ ورودیهایی را که این endpoint میپذیرد نشان میدهد. مقدارهای نمونهها ساختگیاند و یک روش امن برای یکپارچهسازی را نشان میدهند.
| نام | محل ارسال | نوع | الزامی | پشتیبانی | توضیحات |
|---|---|---|---|---|---|
Idempotency-Key | Header | string | اختیاری | پشتیبانی میشود | کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمیگردد. |
X-Request-ID | Header | string | اختیاری | مخصوص مهوش | شناسهٔ ردگیری که کلاینت میفرستد. در همهٔ پاسخها برمیگردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازهای میسازد. |
X-Mahvash-Project | Header | string | اختیاری | مخصوص مهوش | slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر میکند و هرگز دسترسی بیشتری نمیدهد. |
country | Body | string | اختیاری | مخصوص مهوش | کشوری که نتایج باید بیشتر به آن مربوط باشند، با قالبی که موتور جستوجو میپذیرد. |
max_results | Body | integer | اختیاری | مخصوص مهوش | تعداد نتیجه برای هر عبارت جستوجو، بین ۱ تا ۲۰. |
model | Body | string | الزامی | مخصوص مهوش | slug یک مدل جستوجوی وب (از فهرست Web Search). مدلهای جستوجو در /v1/models نمایش داده نمیشوند. |
query | Body | string | array<value> | الزامی | مخصوص مهوش | یک عبارت جستوجو یا فهرستی از عبارتها. هر عبارت یک جستوجوی هزینهدار است؛ تعداد و طول آنها با تنظیمات سرویس محدود میشود. |
search_domain_filter | Body | array<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 | توضیحات |
|---|---|
| 200 | request با موفقیت انجام شد. |
| 400 | request نامعتبر است. |
| 401 | اطلاعات احراز هویت فرستاده نشده یا معتبر نیست. |
| 402 | موجودی برای پرداخت هزینه کافی نیست. |
| 403 | دسترسی لازم را ندارید. |
| 404 | منبع پیدا نشد یا برای شما قابل دسترسی نیست. |
| 409 | تداخل در وضعیت یا idempotency. |
| 429 | از سقف مجاز عبور کردهاید. |
| 500 | خطای داخلی سرور. |
| 502 | سرویس ارائهدهنده با خطا مواجه شد. |
| 503 | یکی از سرویسهای موردنیاز موقتاً در دسترس نیست. |