مرجع API

فایل‌های vector store

فایل آپلودشده را به vector store اضافه کنید و وضعیت ایندکس شدنش را دنبال کنید. برداشتن فایل از vector store، فایل اصلی را حذف نمی‌کند.

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

روند کار

01افزودن فایل به vector store
02فهرست فایل‌های یک vector store
03دریافت وضعیت یک فایل در vector store

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

افزودن فایل به vector store

POST/v1/vector_stores/{store_id}/files

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

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

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

نوع محتواapplication/json

پارامترها

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

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`store_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ vector store.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`chunking_strategy`	Body	object	اختیاری	مشروط	شیء `{'type':'auto'}` یا نوع `static` با `max_chunk_size_tokens` بین ۱۰۰ تا ۴۰۹۶ و `chunk_overlap_tokens`. بررسی و ذخیره می‌شود، اما هنوز در ایندکس کردن اعمال نمی‌شود.
`file_id`	Body	string	الزامی	پشتیبانی می‌شود	شناسهٔ فایلی که باید ایندکس شود. همین شناسه، شناسهٔ عمومی فایل در این vector store هم خواهد بود.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/vector_stores/<store_id>/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_id": "file-3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'

Response

{
  "id": "<id>",
  "object": "vector_store.file",
  "usage_bytes": 0,
  "created_at": 1750000000,
  "vector_store_id": "<id>",
  "status": "in_progress",
  "last_error": null,
  "chunking_strategy": {
    "type": "auto"
  }
}

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

کدهای وضعیت

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

فهرست فایل‌های یک vector store

GET/v1/vector_stores/{store_id}/files

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

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

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`store_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ vector store.
`after`	Query	string	اختیاری	پشتیبانی می‌شود	فایل‌هایی را برمی‌گرداند که بعد از این شناسه ساخته شده‌اند، به ترتیب `order`.
`before`	Query	string	اختیاری	پشتیبانی می‌شود	فایل‌هایی را برمی‌گرداند که پیش از این شناسه ساخته شده‌اند.
`order`	Query	string	اختیاری	پشتیبانی می‌شود	مرتب‌سازی بر اساس زمان ساخت؛ `asc` یا `desc`. مقدار پیش‌فرض `desc` است.
`limit`	Query	integer	اختیاری	پشتیبانی می‌شود	اندازهٔ صفحه بین ۱ تا ۱۰۰؛ پیش‌فرض ۲۰.
`filter`	Query	string	اختیاری	پشتیبانی می‌شود	یکی از `in_progress`، `completed`، `failed` یا `cancelled`.
`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>/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "vector_store.file",
      "usage_bytes": 0,
      "created_at": 1750000000,
      "vector_store_id": "<id>",
      "status": "in_progress",
      "last_error": null,
      "chunking_strategy": {
        "type": "auto"
      }
    }
  ],
  "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}/files/{file_id}

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

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

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`store_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ vector store.
`file_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ فایل در این vector store؛ همان شناسه‌ای که در `/v1/files` دارد.
`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>/files/<file_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "vector_store.file",
  "usage_bytes": 0,
  "created_at": 1750000000,
  "vector_store_id": "<id>",
  "status": "in_progress",
  "last_error": null,
  "chunking_strategy": {
    "type": "auto"
  }
}

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

کدهای وضعیت

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

برداشتن فایل از vector store

DELETE/v1/vector_stores/{store_id}/files/{file_id}

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

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

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`store_id`	مسیر (path)	string	الزامی	پشتیبانی می‌شود	شناسهٔ vector store.
`file_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>/files/<file_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "vector_store.file.deleted",
  "deleted": true
}

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

کدهای وضعیت

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