API reference

Reusable assets

Mahvash assets are reusable project-scoped files. Upload once and pass the asset UUID in supported asset_ids requests; they are not public or cross-project files.

File inputs & retrieval ↗ · Build document Q&A ↗

How it fits together

01Upload one reusable Mahvash file
02List owned Mahvash files
03Download an asset through a signed URL

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

Upload one reusable Mahvash file

POST/api/v1/chat/assets/upload

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseMahvash product envelope

Content typemultipart/form-data

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.
`file`	Form	string (binary)	Required	Mahvash extension	File contents.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/assets/upload' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -F 'file=@./your-file'

Response

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

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

Status codes

HTTP	Details
201	Upload one reusable Mahvash file.
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.
503	A dependency is temporarily unavailable.

List owned Mahvash files

GET/api/v1/chat/assets

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user 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
`type`	Query	string	Optional	Mahvash extension	Filter by asset kind.
`source`	Query	string	Optional	Mahvash extension	Filter by origin: UPLOAD, REMOTE, or GENERATED.
`ordering`	Query	string	Optional	Mahvash extension	created_at or -created_at.
`page`	Query	integer	Optional	Mahvash extension	One-based result page.
`search`	Query	string	Optional	Mahvash extension	Case-insensitive substring of the file name.
`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/chat/assets' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

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

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

Status codes

HTTP	Details
200	List owned Mahvash files.
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.

Download an asset through a signed URL

GET/api/v1/chat/assets/{asset_id}/content

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user 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
`asset_id`	Path	string	Required	Mahvash extension	Asset UUID.
`token`	Query	string	Required	Mahvash extension	Signed, expiring delivery capability.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/assets/<asset_id>/content?token=<token>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

This endpoint returns no JSON body or delivers binary content.

Status codes

HTTP	Details
200	Download an asset through a signed URL.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.
503	A dependency is temporarily unavailable.

Delete one owned Mahvash file

DELETE/api/v1/chat/assets/{asset_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user 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
`asset_id`	Path	string	Required	Mahvash extension	Asset 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/chat/assets/<asset_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

This endpoint returns no JSON body or delivers binary content.

Status codes

HTTP	Details
204	Delete one owned Mahvash file.
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.