API reference

Resumable uploads

Use upload sessions for larger or interrupted transfers. Create a session, send numbered parts, then complete it before using the resulting file.

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

How it fits together

01Create a resumable upload session
02Upload one resumable part
03Assemble and validate a resumable upload

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

Create a resumable upload session

POST/api/v1/chat/uploads

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

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.
`bytes`	Body	integer	Required	Supported	Total expected size in bytes.
`filename`	Body	string	Required	Supported	Base file name, up to 255 characters.
`mime_type`	Body	string	Optional	Supported	Declared media type of the assembled file.
`part_count`	Body	integer	Optional	Mahvash extension	Expected number of parts, validated on completion.
`purpose`	Body	string	Optional	Conditional	assistants, batch, fine-tune, vision, or evals (official); user_data or responses (Mahvash extensions).

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/uploads' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "bytes": 1024,
  "filename": "report.pdf"
}'

Response

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

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

Status codes

HTTP	Details
201	Create a resumable upload session.
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.

Upload one resumable part

PUT/api/v1/chat/uploads/{upload_id}/parts/{part_number}

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

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
`upload_id`	Path	string	Required	Supported	Upload session ID.
`part_number`	Path	integer	Required	Supported	1-based part index.
`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	Supported	Part contents.

Request

curl -X PUT 'https://api.mahvashai.ir/api/v1/chat/uploads/<upload_id>/parts/<part_number>' \
  -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
200	Upload one resumable part.
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.
503	A dependency is temporarily unavailable.

Assemble and validate a resumable upload

POST/api/v1/chat/uploads/{upload_id}/complete

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

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
`upload_id`	Path	string	Required	Supported	Upload session 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.
`sha256`	Body	string	Optional	Supported	Expected checksum of the assembled file.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/uploads/<upload_id>/complete' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sha256": "e3b0c44298fc1c149afbf4c8996fb924"
}'

Response

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

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

Status codes

HTTP	Details
200	Assemble and validate a resumable upload.
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.
503	A dependency is temporarily unavailable.

Cancel an upload session

POST/api/v1/chat/uploads/{upload_id}/cancel

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

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
`upload_id`	Path	string	Required	Supported	Upload session 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/chat/uploads/<upload_id>/cancel' \
  -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	Cancel an upload session.
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.