مرجع API

پروژه‌ها

پروژه محدودهٔ کارهای هوش مصنوعی، فایل‌ها، vector storeها و کلیدها را درون یک سازمان مشخص می‌کند. پیش از صدور API key، پروژه را بسازید.

روند کار

01ساخت پروژه
02فهرست پروژه‌ها
03دریافت اطلاعات پروژه

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

ساخت پروژه

POST/api/v1/tenancy/projects

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

احراز هویتJWT کاربر

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

نوع محتواapplication/json

پارامترها

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

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`default_retrieval_placement`	Body	string	اختیاری	مخصوص مهوش	محل پیش‌فرض نگهداری ایندکس برای vector storeهای تازه.
`description`	Body	string	اختیاری	مخصوص مهوش	توضیح اختیاری.
`name`	Body	string	الزامی	مخصوص مهوش	نام پروژه.
`orchestration_allow_cross_company`	Body	boolean	اختیاری	مخصوص مهوش	آیا مدل‌های تخصصی شرکت‌های دیگر اجازه دارند محتوای این پروژه را پردازش کنند.
`orchestration_enabled_capabilities`	Body	array<value>	اختیاری	مخصوص مهوش	قابلیت‌های مدیریت‌شده‌ای که برای این پروژه فعال است.
`orchestration_max_generated_images`	Body	integer	اختیاری	مخصوص مهوش	حداکثر تعداد تصویری که در یک request، با همهٔ مراحلش، ساخته می‌شود.
`orchestration_max_web_search_calls`	Body	integer	اختیاری	مخصوص مهوش	حداکثر تعداد جست‌وجوی وب مدیریت‌شده در یک request، با همهٔ مراحلش.
`slug`	Body	string	الزامی	مخصوص مهوش	بین ۱ تا ۶۴ حرف کوچک لاتین، عدد یا خط تیره. اختیاری است: اگر نفرستید از روی نام ساخته می‌شود؛ اگر نام حرف لاتین نداشته باشد، slug تصادفی با پیشوند `PRJ` می‌گیرد و اگر تکراری باشد، یک پسوند تصادفی به آن اضافه می‌شود.
`status`	Body	string	اختیاری	مخصوص مهوش	یکی از `ACTIVE` یا `ARCHIVED`.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/projects' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Research",
  "slug": "research"
}'

Response

{
  "status": 201,
  "data": {
    "id": "<project-uuid>",
    "organization": "<organization-uuid>",
    "name": "Research",
    "slug": "research"
  }
}

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

کدهای وضعیت

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

فهرست پروژه‌ها

GET/api/v1/tenancy/projects

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

احراز هویتJWT کاربر

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

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`access_mode`	Query	string	اختیاری	مخصوص مهوش	فیلتر فهرست پروژه‌ها بر اساس `access_mode`.
`page`	Query	integer	اختیاری	مخصوص مهوش	شمارهٔ صفحه در فهرست پروژه‌ها.
`page_size`	Query	integer	اختیاری	مخصوص مهوش	تعداد موارد هر صفحه در فهرست پروژه‌ها.
`search`	Query	string	اختیاری	مخصوص مهوش	عبارت جست‌وجو در فهرست پروژه‌ها.
`status`	Query	string	اختیاری	مخصوص مهوش	فیلتر فهرست پروژه‌ها بر اساس وضعیت.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/tenancy/projects' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

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

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

کدهای وضعیت

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

دریافت اطلاعات پروژه

GET/api/v1/tenancy/projects/{project_id}

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

احراز هویتJWT کاربر

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

پارامترها

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

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

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

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

کدهای وضعیت

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

ویرایش پروژه

PATCH/api/v1/tenancy/projects/{project_id}

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

احراز هویتJWT کاربر

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

نوع محتواapplication/json

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`project_id`	مسیر (path)	string	الزامی	مخصوص مهوش	UUID پروژه.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`default_retrieval_placement`	Body	string	اختیاری	مخصوص مهوش	محل پیش‌فرض تازه برای vector storeهایی که از این به بعد ساخته می‌شوند.
`description`	Body	string	اختیاری	مخصوص مهوش	توضیح جدید.
`name`	Body	string	اختیاری	مخصوص مهوش	نام جدید پروژه.
`orchestration_allow_cross_company`	Body	boolean	اختیاری	مخصوص مهوش	آیا مدل‌های تخصصی شرکت‌های دیگر اجازه دارند محتوای این پروژه را پردازش کنند.
`orchestration_enabled_capabilities`	Body	array<value>	اختیاری	مخصوص مهوش	قابلیت‌های مدیریت‌شده‌ای که برای این پروژه فعال است.
`orchestration_max_generated_images`	Body	integer	اختیاری	مخصوص مهوش	حداکثر تعداد تصویری که در یک request، با همهٔ مراحلش، ساخته می‌شود.
`orchestration_max_web_search_calls`	Body	integer	اختیاری	مخصوص مهوش	حداکثر تعداد جست‌وجوی وب مدیریت‌شده در یک request، با همهٔ مراحلش.
`slug`	Body	string	اختیاری	مخصوص مهوش	slug جدید که در سازمان یکتا باشد.
`status`	Body	string	اختیاری	مخصوص مهوش	یکی از `ACTIVE` یا `ARCHIVED`. پروژهٔ پیش‌فرض همیشه فعال می‌ماند.

Request

curl -X PATCH 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "default_retrieval_placement": "hosted"
}'

Response

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

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

کدهای وضعیت

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

حذف پروژه

DELETE/api/v1/tenancy/projects/{project_id}

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

احراز هویتJWT کاربر

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

پارامترها

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

Request

curl -X DELETE 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

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

کدهای وضعیت

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