مرجع API

Vector storeها

vector store فایل‌های پروژه را برای جست‌وجو ایندکس می‌کند. ساختن vector store به‌تنهایی فایلی را قابل جست‌وجو نمی‌کند؛ باید فایل‌ها را به آن اضافه کنید و منتظر بمانید تا ایندکس شوند.

ورودی فایل و بازیابی اطلاعات ↗ · ساخت پرسش‌وپاسخ اسناد ↗

روند کار

01ساخت vector store
02فهرست vector storeها
03دریافت اطلاعات vector store

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

ساخت vector store

POST/v1/vector_stores

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

نوع محتواapplication/json

پارامترها

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

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`expires_after`	Body	object	اختیاری	مشروط	شیء `{'anchor':'last_active_at','days':1-365}`. پذیرفته و ذخیره می‌شود، اما حذف خودکار پس از انقضا هنوز انجام نمی‌شود.
`metadata`	Body	object	اختیاری	پشتیبانی می‌شود	حداکثر ۱۶ جفت کلید و مقدار متنی با طول محدود.
`name`	Body	string	الزامی	پشتیبانی می‌شود	نام نمایشی، بین ۱ تا ۲۵۵ نویسه.
`project`	Body	string	اختیاری	مخصوص مهوش	قابلیت مخصوص مهوش: شناسه یا slug یک پروژهٔ فعال در سازمان شما. پیش‌فرض، پروژهٔ همان کلید یا کاربر است.
`retrieval_placement`	Body	string	اختیاری	مخصوص مهوش	قابلیت مخصوص مهوش (ADR-037): محل نگهداری داده‌های این vector store. `local` اسناد را در ایندکس خود مهوش نگه می‌دارد، `hosted` آن‌ها را در حساب یک ارائه‌دهنده آپلود می‌کند و `auto` (پیش‌فرض) در عمل همان `local` است. این مقدار تا پایان عمر vector store ثابت می‌ماند و اگر هیچ حساب ارائه‌دهنده‌ای امکان نگهداری نداشته باشد، `hosted` پذیرفته نمی‌شود.

فیلدهای مشروط فقط وقتی کار می‌کنند که مدل و مسیر ارائه‌دهنده از آن‌ها پشتیبانی کنند.

Request

curl -X POST 'https://api.mahvashai.ir/v1/vector_stores' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product manuals"
}'

Response

{
  "id": "<id>",
  "object": "vector_store",
  "created_at": 1750000000,
  "name": "example",
  "usage_bytes": 0,
  "file_counts": {
    "in_progress": 0,
    "completed": 0,
    "cancelled": 0,
    "failed": 0,
    "total": 0
  },
  "status": "completed",
  "expires_after": null,
  "expires_at": null,
  "metadata": {},
  "retrieval_placement": "<value>",
  "effective_retrieval_placement": null
}

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

کدهای وضعیت

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

فهرست vector storeها

GET/v1/vector_stores

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`after`	Query	string	اختیاری	پشتیبانی می‌شود	vector storeهایی را برمی‌گرداند که بعد از این شناسه ساخته شده‌اند، به ترتیب `order`.
`before`	Query	string	اختیاری	پشتیبانی می‌شود	vector storeهایی را برمی‌گرداند که پیش از این شناسه ساخته شده‌اند.
`order`	Query	string	اختیاری	پشتیبانی می‌شود	مرتب‌سازی بر اساس زمان ساخت؛ `asc` یا `desc`. مقدار پیش‌فرض `desc` است.
`limit`	Query	integer	اختیاری	پشتیبانی می‌شود	اندازهٔ صفحه بین ۱ تا ۱۰۰؛ پیش‌فرض ۲۰.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/v1/vector_stores' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "vector_store",
      "created_at": 1750000000,
      "name": "example",
      "usage_bytes": 0,
      "file_counts": {
        "total": 0,
        "failed": 0,
        "cancelled": 0,
        "completed": 0,
        "in_progress": 0
      },
      "status": "completed",
      "expires_after": null,
      "expires_at": null,
      "metadata": {},
      "retrieval_placement": "<value>",
      "effective_retrieval_placement": null
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false
}

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

کدهای وضعیت

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

دریافت اطلاعات vector store

GET/v1/vector_stores/{store_id}

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`store_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ vector store، با prefix `vs_` یا بدون آن.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/v1/vector_stores/<store_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "vector_store",
  "created_at": 1750000000,
  "name": "example",
  "usage_bytes": 0,
  "file_counts": {
    "total": 0,
    "failed": 0,
    "cancelled": 0,
    "completed": 0,
    "in_progress": 0
  },
  "status": "completed",
  "expires_after": null,
  "expires_at": null,
  "metadata": {},
  "retrieval_placement": "<value>",
  "effective_retrieval_placement": null
}

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

کدهای وضعیت

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

ویرایش نام یا metadata در vector store

POST/v1/vector_stores/{store_id}

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

نوع محتواapplication/json

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`store_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ vector storeی که باید ویرایش شود.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`metadata`	Body	object	اختیاری	پشتیبانی می‌شود	شیء metadata جایگزین.
`name`	Body	string	اختیاری	پشتیبانی می‌شود	نام نمایشی جدید.

Request

curl -X POST 'https://api.mahvashai.ir/v1/vector_stores/<store_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "team": "support"
  }
}'

Response

برای این endpoint نمونهٔ قابل‌اعتمادی از response در دست نیست. کد وضعیت HTTP را بررسی کنید و body برگشتی را متناسب با روند کار کلاینت خود بخوانید.

کدهای وضعیت

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

حذف vector store

DELETE/v1/vector_stores/{store_id}

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`store_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ vector storeی که باید حذف شود.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X DELETE 'https://api.mahvashai.ir/v1/vector_stores/<store_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

کدهای وضعیت

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