API reference

Vector store files

Attach an uploaded file to a store and inspect its indexing state. Removing an attachment does not delete the original file.

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

How it fits together

01Attach an existing file to a vector store. Plan 11: rests in PENDING; indexing ships in plan 12
02List a vector store's files
03Retrieve one vector store file

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

Attach an existing file to a vector store. Plan 11: rests in PENDING; indexing ships in plan 12

POST/v1/vector_stores/{store_id}/files

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
`store_id`	Path	string	Required	Supported	Vector store 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.
`chunking_strategy`	Body	object	Optional	Conditional	{'type': 'auto'} or {'type': 'static', 'static': {'max_chunk_size_tokens': 100-4096, 'chunk_overlap_tokens': ...}}. Validated and stored; not yet applied by any indexer.
`file_id`	Body	string	Required	Supported	Existing file ID to index. Becomes this membership's public ID.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/vector_stores/<store_id>/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_id": "file-3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'

Response

{
  "id": "<id>",
  "object": "vector_store.file",
  "usage_bytes": 0,
  "created_at": 1750000000,
  "vector_store_id": "<id>",
  "status": "in_progress",
  "last_error": null,
  "chunking_strategy": {
    "type": "auto"
  }
}

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

Status codes

HTTP	Details
201	Attach an existing file to a vector store. Plan 11: rests in PENDING; indexing ships in plan 12.
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.

List a vector store's files

GET/v1/vector_stores/{store_id}/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
`store_id`	Path	string	Required	Supported	Vector store ID.
`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.
`filter`	Query	string	Optional	Supported	One of in_progress, completed, failed, cancelled.
`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/vector_stores/<store_id>/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "vector_store.file",
      "usage_bytes": 0,
      "created_at": 1750000000,
      "vector_store_id": "<id>",
      "status": "in_progress",
      "last_error": null,
      "chunking_strategy": {
        "type": "auto"
      }
    }
  ],
  "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 a vector store's 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 one vector store file

GET/v1/vector_stores/{store_id}/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
`store_id`	Path	string	Required	Supported	Vector store ID.
`file_id`	Path	string	Required	Supported	The file ID within this store (same ID as /v1/files).
`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/vector_stores/<store_id>/files/<file_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "vector_store.file",
  "usage_bytes": 0,
  "created_at": 1750000000,
  "vector_store_id": "<id>",
  "status": "in_progress",
  "last_error": null,
  "chunking_strategy": {
    "type": "auto"
  }
}

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

Status codes

HTTP	Details
200	Retrieve one vector store 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.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Remove a file from a vector store (the source file is untouched)

DELETE/v1/vector_stores/{store_id}/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
`store_id`	Path	string	Required	Supported	Vector store ID.
`file_id`	Path	string	Required	Supported	The file ID to remove from this store.
`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/vector_stores/<store_id>/files/<file_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

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

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

Status codes

HTTP	Details
200	Remove a file from a vector store (the source file is untouched).
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.