مرجع API

سازمان‌ها

سازمان مرز اصلی جداسازی پروژه‌ها، کلیدها و اعضاست. عملیات مدیریتی به JWT کاربر و انتخاب سازمانی نیاز دارند که کاربر در آن دسترسی لازم را دارد.

روند کار

01ساخت سازمان تازه
02تبدیل سازمان شخصی به سازمان تیمی
03دریافت سازمان و پروژهٔ فعلی

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

ساخت سازمان تازه

POST/api/v1/tenancy/organizations

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

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

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

نوع محتواapplication/json

پارامترها

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

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

Request

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

Response

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

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

کدهای وضعیت

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

تبدیل سازمان شخصی به سازمان تیمی

POST/api/v1/tenancy/organizations/convert

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

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

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

پارامترها

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

Request

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

Response

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

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

کدهای وضعیت

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

دریافت سازمان و پروژهٔ فعلی

GET/api/v1/tenancy/organization

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

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

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

پارامترها

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

Request

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

Response

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

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

کدهای وضعیت

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

دریافت محدودیت‌ها و بودجهٔ سازمان

GET/api/v1/tenancy/organizations/settings

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

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

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

پارامترها

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

Request

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

Response

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

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

کدهای وضعیت

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

تنظیم محدودیت‌ها و بودجهٔ سازمان

PATCH/api/v1/tenancy/organizations/settings

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

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

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

نوع محتواapplication/json

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`budget_alert_percent`	Body	integer	اختیاری	مخصوص مهوش	درصدی از بودجه که با رسیدن به آن، در هر دوره یک بار هشدار داده می‌شود. `null` هشدار را خاموش می‌کند.
`max_active_runs`	Body	integer	اختیاری	مخصوص مهوش	حداکثر تعداد کارهای همزمان در همهٔ عملیات. `null` یعنی پیروی از مقدار پیش‌فرض سرویس.
`monthly_budget_usd`	Body	string	اختیاری	مخصوص مهوش	سقف قطعی هزینه در هر ماه میلادی به وقت UTC. `null` یعنی بدون سقف.
`name`	Body	string	اختیاری	مخصوص مهوش	نام نمایشی.
`requests_per_minute`	Body	integer	اختیاری	مخصوص مهوش	سقف تعداد request در دقیقه. پروژه یا کلید می‌تواند آن را کمتر کند، اما نمی‌تواند بیشترش کند. `null` یعنی پیروی از مقدار پیش‌فرض سرویس.

Request

curl -X PATCH 'https://api.mahvashai.ir/api/v1/tenancy/organizations/settings' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "budget_alert_percent": 80
}'

Response

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

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

کدهای وضعیت

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

فهرست سازمان‌های قابل انتخاب

GET/api/v1/tenancy/organizations

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

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

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

پارامترها

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

Request

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

Response

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

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

کدهای وضعیت

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