API reference

Teams

Group organization members for shared access policy. Team membership does not bypass project grants or organization authorization.

How it fits together

01Create a team in the selected organization
02Add an organization member to a team
03Read one team

Select an action to see its complete inputs, request, response, and status codes.

Create a team in the selected organization

POST/api/v1/tenancy/teams

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Content typeapplication/json

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.
`name`	Body	string	Required	Mahvash extension	Display name, 1-120 characters.
`slug`	Body	string	Optional	Mahvash extension	Unique within the organization. Derived from the name when omitted; a random team- slug when the name yields none, and a random suffix when taken.

Request

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

Response

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

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
201	Create a team in the selected organization.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Add an organization member to a team

POST/api/v1/tenancy/teams/{team_id}/members

Production base URLhttps://api.mahvashai.ir

AuthenticationUser 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
`team_id`	Path	string	Required	Mahvash extension	Team ID.
`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/teams/<team_id>/members' \
  -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
201	Add an organization member to a team.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Read one team

GET/api/v1/tenancy/teams/{team_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationUser 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
`team_id`	Path	string	Required	Mahvash extension	Team ID.
`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/teams/<team_id>' \
  -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 one team.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Rename or describe a team

PATCH/api/v1/tenancy/teams/{team_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Content typeapplication/json

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
`team_id`	Path	string	Required	Mahvash extension	Team ID.
`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.
`description`	Body	string	Optional	Mahvash extension	Free text, up to 500 characters.
`name`	Body	string	Optional	Mahvash extension	Display name, 1-120 characters.

Request

curl -X PATCH 'https://api.mahvashai.ir/api/v1/tenancy/teams/<team_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Campaign work"
}'

Response

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

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Rename or describe a team.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Archive a team, withdrawing the project reach it conferred

DELETE/api/v1/tenancy/teams/{team_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationUser 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
`team_id`	Path	string	Required	Mahvash extension	Team ID.
`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 DELETE 'https://api.mahvashai.ir/api/v1/tenancy/teams/<team_id>' \
  -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	Archive a team, withdrawing the project reach it conferred.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Remove a member from a team

DELETE/api/v1/tenancy/teams/{team_id}/members/{membership_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationUser 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
`team_id`	Path	string	Required	Mahvash extension	Team ID.
`membership_id`	Path	string	Required	Mahvash extension	Membership ID.
`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 DELETE 'https://api.mahvashai.ir/api/v1/tenancy/teams/<team_id>/members/<membership_id>' \
  -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	Remove a member from a team.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

List teams in the selected organization

GET/api/v1/tenancy/teams

Production base URLhttps://api.mahvashai.ir

AuthenticationUser 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
`search`	Query	string	Optional	Mahvash extension	Case-insensitive search over team name, slug, and description.
`status`	Query	string	Optional	Mahvash extension	Filter by ACTIVE or ARCHIVED.
`page`	Query	integer	Optional	Mahvash extension	One-based page number when bounded pagination is requested.
`page_size`	Query	integer	Optional	Mahvash extension	Page size from 1 through 100 when bounded pagination is requested.
`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/teams' \
  -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 teams in the selected organization.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.