API reference

Files

The /v1/files surface uses OpenAI-style file IDs and direct wire shapes. /api/v1/chat/files is a product alias with a different envelope; choose the surface your client expects.

Choose a file path

Mahvash has several file interfaces because they serve different integration jobs, not because every upload creates a separate kind of storage. Pick the first row that matches your goal:

Need	Use	Why
Give the model a file with one question or across a chat	Mahvash asset + `asset_ids`	One project-scoped UUID can be passed to any supported request.
Use an OpenAI-compatible SDK or a batch	`/v1/files`	`file-...` IDs and the direct wire format fit supported SDK methods.
Transfer a large file reliably	Resumable upload session	Send numbered, checksummed parts, then complete the upload.
Search a collection of documents	Vector store + files	Files are indexed before `file_search` can retrieve them.
Make retrieval available to a whole project	Project data source	Attaches an indexed store to the project; it does not upload or index files.

Assets (/api/v1/chat/assets) are reusable project files identified by a UUID. Pass them to a request with asset_ids.
Files (/v1/files) are OpenAI-style file objects (file-...) for SDK compatibility, batches and vector stores. /api/v1/chat/files offers the same objects inside the product envelope.
Uploads (/api/v1/chat/uploads) split one large file into numbered, retryable parts.
Vector stores (/v1/vector_stores) index files so file_search can find relevant passages.
Project data sources make an indexed store part of a project's retrieval.

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

How it fits together

01Upload a reusable OpenAI-style file (canonical mount)
02List owned reusable files (canonical mount)
03Retrieve file metadata (canonical mount)

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

Upload a reusable OpenAI-style file (canonical mount)

POST/v1/files

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
`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.
`expires_after`	Form	object	Optional	Conditional	{'anchor': 'created_at', 'seconds': 3600-2592000}, or the bracket-encoded multipart equivalent (expires_after[anchor], expires_after[seconds]). Accepted, stored, and reflected in the response expires_at; not yet enforced by a sweep.
`file`	Form	string (binary)	Required	Supported	File contents.
`purpose`	Form	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/v1/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -F 'file=@./your-file'

Response

{
  "id": "<id>",
  "object": "file",
  "bytes": 0,
  "created_at": 1750000000,
  "expires_at": null,
  "filename": "example",
  "purpose": "user_data",
  "status": "processed",
  "status_details": null
}

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

Status codes

HTTP	Details
201	Upload a reusable OpenAI-style file (canonical mount).
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 reusable files (canonical mount)

GET/v1/files

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
`purpose`	Query	string	Optional	Conditional	Filter by stored purpose.
`after`	Query	string	Optional	Supported	Return files created after this file ID, walking in `order`.
`before`	Query	string	Optional	Supported	Return files created before this file ID.
`order`	Query	string	Optional	Supported	'asc' or 'desc' by creation time; default 'desc'.
`limit`	Query	integer	Optional	Supported	Page size, 1-100, default 20.
`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.

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

Request

curl -X GET 'https://api.mahvashai.ir/v1/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "file",
      "bytes": 0,
      "created_at": 1750000000,
      "expires_at": null,
      "filename": "example",
      "purpose": "user_data",
      "status": "processed",
      "status_details": null
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false
}

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

Status codes

HTTP	Details
200	List owned reusable files (canonical mount).
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.

Retrieve file metadata (canonical mount)

GET/v1/files/{file_id}

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
`file_id`	Path	string	Required	Supported	File ID, with or without the file- prefix.
`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/v1/files/<file_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "file",
  "bytes": 0,
  "created_at": 1750000000,
  "expires_at": null,
  "filename": "example",
  "purpose": "user_data",
  "status": "processed",
  "status_details": null
}

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

Status codes

HTTP	Details
200	Retrieve file metadata (canonical mount).
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 file bytes (canonical mount)

GET/v1/files/{file_id}/content

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
`file_id`	Path	string	Required	Supported	File ID to download.
`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/v1/files/<file_id>/content' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

This endpoint returns no JSON body or delivers binary content.

Status codes

HTTP	Details
200	Download file bytes (canonical mount).
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.
503	A dependency is temporarily unavailable.

Delete an owned file (canonical mount)

DELETE/v1/files/{file_id}

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
`file_id`	Path	string	Required	Supported	File ID to delete.
`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/v1/files/<file_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "file",
  "deleted": true
}

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

Status codes

HTTP	Details
200	Delete an owned file (canonical mount).
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.

Upload a reusable OpenAI-style file

POST/api/v1/chat/files

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	Supported	File contents.
`purpose`	Form	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/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -F 'file=@./your-file'

Response

{
  "status": 201,
  "data": {
    "id": "file-<uuid>",
    "object": "file",
    "filename": "policy.pdf",
    "purpose": "user_data",
    "status": "processed"
  }
}

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

Status codes

HTTP	Details
201	Upload a reusable OpenAI-style 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 reusable files

GET/api/v1/chat/files

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
`purpose`	Query	string	Optional	Conditional	Filter by stored purpose.
`cursor`	Query	string	Optional	Mahvash extension	Opaque cursor from a previous page.
`limit`	Query	integer	Optional	Mahvash extension	Requested page size, capped at 100.
`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.

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

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/files' \
  -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 reusable 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.

Retrieve file metadata

GET/api/v1/chat/files/{file_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
`file_id`	Path	string	Required	Supported	File ID, with or without the file- prefix.
`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/files/<file_id>' \
  -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	Retrieve file metadata.
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 file bytes

GET/api/v1/chat/files/{file_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
`file_id`	Path	string	Required	Supported	File ID to download.
`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/files/<file_id>/content' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

This endpoint returns no JSON body or delivers binary content.

Status codes

HTTP	Details
200	Download file bytes.
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.
503	A dependency is temporarily unavailable.

Delete an owned file

DELETE/api/v1/chat/files/{file_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
`file_id`	Path	string	Required	Supported	File ID to delete.
`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/files/<file_id>' \
  -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	Delete an owned 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.