مرجع API

فایل‌ها

مسیر /v1/files از شناسه‌های فایل و قالب مستقیم OpenAI استفاده می‌کند. /api/v1/chat/files همین فایل‌ها را در قالب پاسخ مخصوص مهوش ارائه می‌دهد؛ مسیری را انتخاب کنید که کلاینت شما انتظار دارد.

انتخاب روش مناسب

مهوش چند رابط برای فایل دارد، چون هر کدام کار متفاوتی انجام می‌دهد؛ نه اینکه هر آپلود نوع جداگانه‌ای از ذخیره‌سازی بسازد. اولین ردیفی را انتخاب کنید که با هدف شما جور است:

نیاز شما	راه‌حل	دلیل
دادن فایل به مدل برای یک پرسش یا در طول یک گفت‌وگو	asset مهوش + `asset_ids`	یک UUID در محدودهٔ پروژه که در هر request پشتیبانی‌شده قابل استفاده است.
استفاده از SDK سازگار با OpenAI یا batch	`/v1/files`	شناسه‌های `file-...` و قالب مستقیم پاسخ، با متدهای پشتیبانی‌شدهٔ SDK سازگارند.
انتقال مطمئن یک فایل بزرگ	آپلود چندبخشی	بخش‌های شماره‌دار همراه با checksum فرستاده و در پایان آپلود تکمیل می‌شود.
جست‌وجو در مجموعه‌ای از اسناد	vector store + فایل‌ها	فایل‌ها باید ایندکس شوند تا `file_search` بتواند در آن‌ها جست‌وجو کند.
فعال کردن جست‌وجوی اسناد برای کل پروژه	منبع دادهٔ پروژه	یک vector store ایندکس‌شده را به پروژه متصل می‌کند؛ خودش چیزی آپلود یا ایندکس نمی‌کند.

assetها (/api/v1/chat/assets) فایل‌های قابل استفادهٔ مجدد پروژه هستند که با یک UUID شناخته می‌شوند. آن‌ها را با asset_ids به request می‌دهید.
فایل‌ها (/v1/files) همان اشیای فایل OpenAI (file-...) هستند و برای سازگاری با SDK، batch و vector store به کار می‌روند. /api/v1/chat/files همین فایل‌ها را در قالب پاسخ مخصوص مهوش ارائه می‌دهد.
آپلود چندبخشی (/api/v1/chat/uploads) یک فایل بزرگ را به بخش‌های شماره‌دار و قابل تکرار تقسیم می‌کند.
vector storeها (/v1/vector_stores) فایل‌ها را ایندکس می‌کنند تا file_search بتواند بخش‌های مرتبط را پیدا کند.
منابع دادهٔ پروژه یک vector store ایندکس‌شده را به بخشی از جست‌وجوی پروژه تبدیل می‌کنند.

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

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

آپلود فایل (مسیر اصلی /v1)

POST/v1/files

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

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

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

نوع محتواmultipart/form-data

پارامترها

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

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`expires_after`	Form	object	اختیاری	مشروط	شیء `{'anchor':'created_at','seconds':3600-2592000}` یا معادل آن در multipart (`expires_after[anchor]` و `expires_after[seconds]`). پذیرفته و ذخیره می‌شود و در `expires_at` پاسخ هم می‌آید، اما حذف خودکار پس از انقضا هنوز انجام نمی‌شود.
`file`	Form	string (binary)	الزامی	پشتیبانی می‌شود	محتوای فایل.
`purpose`	Form	string	اختیاری	مشروط	گزینه‌های رسمی `assistants`، `batch`، `fine-tune`، `vision` و `evals`؛ یا افزونه‌های مهوش `user_data` و `responses`.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -F 'file=@./your-file'

Response

{
  "id": "<id>",
  "object": "file",
  "bytes": 0,
  "created_at": 1750000000,
  "expires_at": null,
  "filename": "example",
  "purpose": "user_data",
  "status": "processed",
  "status_details": null
}

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

کدهای وضعیت

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

فهرست فایل‌ها (مسیر اصلی /v1)

GET/v1/files

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

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

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`purpose`	Query	string	اختیاری	مشروط	فیلتر بر اساس `purpose` ذخیره‌شده.
`after`	Query	string	اختیاری	پشتیبانی می‌شود	فایل‌هایی را برمی‌گرداند که بعد از این شناسه ساخته شده‌اند، به ترتیب `order`.
`before`	Query	string	اختیاری	پشتیبانی می‌شود	فایل‌هایی را برمی‌گرداند که پیش از این شناسه ساخته شده‌اند.
`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/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "file",
      "bytes": 0,
      "created_at": 1750000000,
      "expires_at": null,
      "filename": "example",
      "purpose": "user_data",
      "status": "processed",
      "status_details": null
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false
}

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

کدهای وضعیت

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

دریافت اطلاعات فایل (مسیر اصلی /v1)

GET/v1/files/{file_id}

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

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

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

پارامترها

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

Request

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

Response

{
  "id": "<id>",
  "object": "file",
  "bytes": 0,
  "created_at": 1750000000,
  "expires_at": null,
  "filename": "example",
  "purpose": "user_data",
  "status": "processed",
  "status_details": null
}

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

کدهای وضعیت

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

دانلود محتوای فایل (مسیر اصلی /v1)

GET/v1/files/{file_id}/content

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

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

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

پارامترها

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

Request

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

Response

این endpoint بدنهٔ JSON برنمی‌گرداند یا خروجی آن فایل باینری است.

کدهای وضعیت

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

حذف فایل (مسیر اصلی /v1)

DELETE/v1/files/{file_id}

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

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

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

پارامترها

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

Request

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

Response

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

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

کدهای وضعیت

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

آپلود فایل با قالب OpenAI

POST/api/v1/chat/files

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

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

Responseresponse در قالب مخصوص مهوش

نوع محتواmultipart/form-data

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`file`	Form	string (binary)	الزامی	پشتیبانی می‌شود	محتوای فایل.
`purpose`	Form	string	اختیاری	مشروط	گزینه‌های رسمی `assistants`، `batch`، `fine-tune`، `vision` و `evals`؛ یا افزونه‌های مهوش `user_data` و `responses`.

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

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -F 'file=@./your-file'

Response

{
  "status": 201,
  "data": {
    "id": "file-<uuid>",
    "object": "file",
    "filename": "policy.pdf",
    "purpose": "user_data",
    "status": "processed"
  }
}

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

کدهای وضعیت

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

فهرست فایل‌ها

GET/api/v1/chat/files

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

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

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`purpose`	Query	string	اختیاری	مشروط	فیلتر بر اساس `purpose` ذخیره‌شده.
`cursor`	Query	string	اختیاری	مخصوص مهوش	cursorی که از صفحهٔ قبل گرفته‌اید؛ محتوای آن را تغییر ندهید.
`limit`	Query	integer	اختیاری	مخصوص مهوش	اندازهٔ صفحهٔ درخواستی، حداکثر ۱۰۰.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

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

Request

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

Response

{
  "status": 0,
  "data": "<value>"
}

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

کدهای وضعیت

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

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

GET/api/v1/chat/files/{file_id}

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

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

Responseresponse در قالب مخصوص مهوش

پارامترها

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

Request

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

Response

{
  "status": 0,
  "data": "<value>"
}

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

کدهای وضعیت

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

دانلود محتوای فایل

GET/api/v1/chat/files/{file_id}/content

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

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

Responseresponse در قالب مخصوص مهوش

پارامترها

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

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/files/<file_id>/content' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

این endpoint بدنهٔ JSON برنمی‌گرداند یا خروجی آن فایل باینری است.

کدهای وضعیت

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

حذف فایل

DELETE/api/v1/chat/files/{file_id}

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

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

Responseresponse در قالب مخصوص مهوش

پارامترها

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

Request

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

Response

{
  "status": 0,
  "data": "<value>"
}

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

کدهای وضعیت

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