API reference
Organizations
An organization is the tenant boundary for projects, credentials, and members. Management calls use a user JWT and an authorized organization context.
How it fits together
- 01Create a company organization owned by the caller
- 02Convert the selected personal organization into a team organization
- 03Read the caller's organization
Select an action to see its complete inputs, request, response, and status codes.
Create a company organization owned by the caller
POST
/api/v1/tenancy/organizationsProduction base URL
https://api.mahvashai.irAuthenticationUser access JWT
ResponseMahvash product envelope
Content type
application/jsonParameters
The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.
| Name | Location | Type | Required | Support | Details |
|---|---|---|---|---|---|
X-Request-ID | Header | string | Optional | Mahvash extension | Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed. |
X-Mahvash-Project | Header | string | Optional | Mahvash extension | Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it. |
name | Body | string | Required | Mahvash extension | Display name for the new organization. |
slug | Body | string | Optional | Mahvash extension | Globally unique slug, usable in X-Mahvash-Organization. Derived from the name when omitted; a random org- slug when the name yields none, and a random suffix when taken. |
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>"
}Illustrative response shape; actual fields depend on the operation and model.
Status codes
| HTTP | Details |
|---|---|
| 201 | Create a company organization owned by the caller. |
| 400 | The request is not valid. |
| 401 | Authentication credentials are missing or invalid. |
| 403 | The principal is not allowed to perform this request. |
| 429 | A quota or rate limit was exceeded. |
| 500 | An internal error occurred. |
Convert the selected personal organization into a team organization
POST
/api/v1/tenancy/organizations/convertProduction base URL
https://api.mahvashai.irAuthenticationUser access JWT
ResponseMahvash product envelope
Parameters
The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.
| Name | Location | Type | Required | Support | Details |
|---|---|---|---|---|---|
X-Request-ID | Header | string | Optional | Mahvash extension | Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed. |
X-Mahvash-Project | Header | string | Optional | Mahvash extension | Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it. |
Request
curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/organizations/convert' \
-H "Authorization: Bearer $MAHVASH_USER_JWT"Response
{
"status": 0,
"data": "<value>"
}Illustrative response shape; actual fields depend on the operation and model.
Status codes
| HTTP | Details |
|---|---|
| 200 | Convert the selected personal organization into a team organization. |
| 400 | The request is not valid. |
| 401 | Authentication credentials are missing or invalid. |
| 403 | The principal is not allowed to perform this request. |
| 429 | A quota or rate limit was exceeded. |
| 500 | An internal error occurred. |
Read the caller's organization
GET
/api/v1/tenancy/organizationProduction base URL
https://api.mahvashai.irAuthenticationUser access JWT
ResponseMahvash product envelope
Parameters
The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.
| Name | Location | Type | Required | Support | Details |
|---|---|---|---|---|---|
X-Request-ID | Header | string | Optional | Mahvash extension | Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed. |
X-Mahvash-Project | Header | string | Optional | Mahvash extension | Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it. |
Request
curl -X GET 'https://api.mahvashai.ir/api/v1/tenancy/organization' \
-H "Authorization: Bearer $MAHVASH_USER_JWT"Response
{
"status": 0,
"data": "<value>"
}Illustrative response shape; actual fields depend on the operation and model.
Status codes
| HTTP | Details |
|---|---|
| 200 | Read the caller's organization. |
| 401 | Authentication credentials are missing or invalid. |
| 403 | The principal is not allowed to perform this request. |
| 429 | A quota or rate limit was exceeded. |
| 500 | An internal error occurred. |
Read the selected organization's layered limits and monthly budget
GET
/api/v1/tenancy/organizations/settingsProduction base URL
https://api.mahvashai.irAuthenticationUser access JWT
ResponseMahvash product envelope
Parameters
The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.
| Name | Location | Type | Required | Support | Details |
|---|---|---|---|---|---|
X-Request-ID | Header | string | Optional | Mahvash extension | Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed. |
X-Mahvash-Project | Header | string | Optional | Mahvash extension | Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it. |
Request
curl -X GET 'https://api.mahvashai.ir/api/v1/tenancy/organizations/settings' \
-H "Authorization: Bearer $MAHVASH_USER_JWT"Response
{
"status": 0,
"data": "<value>"
}Illustrative response shape; actual fields depend on the operation and model.
Status codes
| HTTP | Details |
|---|---|
| 200 | Read the selected organization's layered limits and monthly budget. |
| 401 | Authentication credentials are missing or invalid. |
| 403 | The principal is not allowed to perform this request. |
| 429 | A quota or rate limit was exceeded. |
| 500 | An internal error occurred. |
Set the organization's limits and monthly budget
PATCH
/api/v1/tenancy/organizations/settingsProduction base URL
https://api.mahvashai.irAuthenticationUser access JWT
ResponseMahvash product envelope
Content type
application/jsonParameters
The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.
| Name | Location | Type | Required | Support | Details |
|---|---|---|---|---|---|
X-Request-ID | Header | string | Optional | Mahvash extension | Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed. |
X-Mahvash-Project | Header | string | Optional | Mahvash extension | Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it. |
budget_alert_percent | Body | integer | Optional | Mahvash extension | Percentage of the budget at which a soft alert is raised once per period. Null disables the alert. |
max_active_runs | Body | integer | Optional | Mahvash extension | Concurrent in-flight runs across every operation. Null inherits the deployment default. |
monthly_budget_usd | Body | string | Optional | Mahvash extension | Hard spend ceiling for the calendar month in UTC. Null means no ceiling. |
name | Body | string | Optional | Mahvash extension | Display name. |
requests_per_minute | Body | integer | Optional | Mahvash extension | Per-minute request ceiling. A project or credential may tighten it and never raise it; null inherits the deployment default. |
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>"
}Illustrative response shape; actual fields depend on the operation and model.
Status codes
| HTTP | Details |
|---|---|
| 200 | Set the organization's limits and monthly budget. |
| 400 | The request is not valid. |
| 401 | Authentication credentials are missing or invalid. |
| 403 | The principal is not allowed to perform this request. |
| 429 | A quota or rate limit was exceeded. |
| 500 | An internal error occurred. |
List the organizations this account may act in, and which is selected
GET
/api/v1/tenancy/organizationsProduction base URL
https://api.mahvashai.irAuthenticationUser access JWT
ResponseMahvash product envelope
Parameters
The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.
| Name | Location | Type | Required | Support | Details |
|---|---|---|---|---|---|
X-Request-ID | Header | string | Optional | Mahvash extension | Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed. |
X-Mahvash-Project | Header | string | Optional | Mahvash extension | Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it. |
Request
curl -X GET 'https://api.mahvashai.ir/api/v1/tenancy/organizations' \
-H "Authorization: Bearer $MAHVASH_USER_JWT"Response
{
"status": 0,
"data": "<value>"
}Illustrative response shape; actual fields depend on the operation and model.
Status codes
| HTTP | Details |
|---|---|
| 200 | List the organizations this account may act in, and which is selected. |
| 401 | Authentication credentials are missing or invalid. |
| 403 | The principal is not allowed to perform this request. |
| 429 | A quota or rate limit was exceeded. |
| 500 | An internal error occurred. |