API reference

Projects

A project scopes AI work, files, stores, and credentials inside an organization. Create it before issuing a project API key.

How it fits together

01Create a project
02List projects in the caller's organization
03Retrieve one project

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

Create a project

POST/api/v1/tenancy/projects

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.
`default_retrieval_placement`	Body	string	Optional	Mahvash extension	Default placement for newly created vector stores.
`description`	Body	string	Optional	Mahvash extension	Optional description.
`name`	Body	string	Required	Mahvash extension	Human-readable project name.
`orchestration_allow_cross_company`	Body	boolean	Optional	Mahvash extension	Whether specialists from another model company may process project content.
`orchestration_enabled_capabilities`	Body	array<value>	Optional	Mahvash extension	Managed capabilities enabled for this project.
`orchestration_max_generated_images`	Body	integer	Optional	Mahvash extension	Maximum generated images in one request chain.
`orchestration_max_web_search_calls`	Body	integer	Optional	Mahvash extension	Maximum managed web searches in one request chain.
`slug`	Body	string	Required	Mahvash extension	1 to 64 lowercase letters, digits, or hyphens. Optional: derived from the name when omitted, a random PRJ slug when the name has no Latin letters, and a random suffix when taken.
`status`	Body	string	Optional	Mahvash extension	ACTIVE or 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"
  }
}

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

Status codes

HTTP	Details
201	Create a project.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

List projects in the caller's organization

GET/api/v1/tenancy/projects

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
`access_mode`	Query	string	Optional	Mahvash extension	Bounded project-list access_mode query parameter.
`page`	Query	integer	Optional	Mahvash extension	Bounded project-list page query parameter.
`page_size`	Query	integer	Optional	Mahvash extension	Bounded project-list page_size query parameter.
`search`	Query	string	Optional	Mahvash extension	Bounded project-list search query parameter.
`status`	Query	string	Optional	Mahvash extension	Bounded project-list status query parameter.
`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/projects' \
  -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 projects in 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.

Retrieve one project

GET/api/v1/tenancy/projects/{project_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
`project_id`	Path	string	Required	Mahvash extension	Project UUID.
`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/projects/<project_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	Retrieve one project.
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.

Update one project

PATCH/api/v1/tenancy/projects/{project_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
`project_id`	Path	string	Required	Mahvash extension	Project UUID.
`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.
`default_retrieval_placement`	Body	string	Optional	Mahvash extension	New default placement for future vector stores.
`description`	Body	string	Optional	Mahvash extension	New description.
`name`	Body	string	Optional	Mahvash extension	New project name.
`orchestration_allow_cross_company`	Body	boolean	Optional	Mahvash extension	Whether specialists from another model company may process project content.
`orchestration_enabled_capabilities`	Body	array<value>	Optional	Mahvash extension	Managed capabilities enabled for this project.
`orchestration_max_generated_images`	Body	integer	Optional	Mahvash extension	Maximum generated images in one request chain.
`orchestration_max_web_search_calls`	Body	integer	Optional	Mahvash extension	Maximum managed web searches in one request chain.
`slug`	Body	string	Optional	Mahvash extension	New slug, unique within the organization.
`status`	Body	string	Optional	Mahvash extension	ACTIVE or ARCHIVED. The default project stays active.

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>"
}

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

Status codes

HTTP	Details
200	Update one project.
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.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Delete one project. The default project cannot be deleted

DELETE/api/v1/tenancy/projects/{project_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
`project_id`	Path	string	Required	Mahvash extension	Project UUID.
`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/projects/<project_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

This endpoint returns no JSON body or delivers binary content.

Status codes

HTTP	Details
204	Delete one project. The default project cannot be deleted.
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.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.