API reference

Vector stores

A vector store indexes project files for retrieval. Creating the store alone does not make a file searchable; attach files and wait for indexing.

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

How it fits together

01Create a vector store (plan 11: local resource only, no indexing)
02List owned vector stores
03Retrieve a vector store

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

Create a vector store (plan 11: local resource only, no indexing)

POST/v1/vector_stores

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.
`expires_after`	Body	object	Optional	Conditional	{'anchor': 'last_active_at', 'days': 1-365}. Accepted and stored; not yet enforced by a sweep.
`metadata`	Body	object	Optional	Supported	At most 16 string key/value pairs, bounded length.
`name`	Body	string	Required	Supported	Display name, 1-255 characters.
`project`	Body	string	Optional	Mahvash extension	Mahvash extension: an active project ID or slug in the caller's organization. Defaults to the principal's project.
`retrieval_placement`	Body	string	Optional	Mahvash extension	Mahvash extension (ADR-037): where this store's data lives. 'local' keeps documents in the Mahvash-owned index; 'hosted' uploads them to a provider account; 'auto' (the default) resolves to 'local'. Fixed for the life of the store, and rejected as 'hosted' on a deployment whose configured accounts cannot host.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/vector_stores' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product manuals"
}'

Response

{
  "id": "<id>",
  "object": "vector_store",
  "created_at": 1750000000,
  "name": "example",
  "usage_bytes": 0,
  "file_counts": {
    "in_progress": 0,
    "completed": 0,
    "cancelled": 0,
    "failed": 0,
    "total": 0
  },
  "status": "completed",
  "expires_after": null,
  "expires_at": null,
  "metadata": {},
  "retrieval_placement": "<value>",
  "effective_retrieval_placement": null
}

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

Status codes

HTTP	Details
201	Create a vector store (plan 11: local resource only, no indexing).
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 owned vector stores

GET/v1/vector_stores

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
`after`	Query	string	Optional	Supported	Return stores created after this store ID, walking in `order`.
`before`	Query	string	Optional	Supported	Return stores created before this store 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.

Request

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

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "vector_store",
      "created_at": 1750000000,
      "name": "example",
      "usage_bytes": 0,
      "file_counts": {
        "total": 0,
        "failed": 0,
        "cancelled": 0,
        "completed": 0,
        "in_progress": 0
      },
      "status": "completed",
      "expires_after": null,
      "expires_at": null,
      "metadata": {},
      "retrieval_placement": "<value>",
      "effective_retrieval_placement": 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 vector stores.
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 a vector store

GET/v1/vector_stores/{store_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, with or without the vs_ 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/vector_stores/<store_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "vector_store",
  "created_at": 1750000000,
  "name": "example",
  "usage_bytes": 0,
  "file_counts": {
    "total": 0,
    "failed": 0,
    "cancelled": 0,
    "completed": 0,
    "in_progress": 0
  },
  "status": "completed",
  "expires_after": null,
  "expires_at": null,
  "metadata": {},
  "retrieval_placement": "<value>",
  "effective_retrieval_placement": null
}

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

Status codes

HTTP	Details
200	Retrieve a vector store.
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 a vector store's name or metadata

POST/v1/vector_stores/{store_id}

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 to update.
`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.
`metadata`	Body	object	Optional	Supported	Replacement metadata object.
`name`	Body	string	Optional	Supported	New display name.

Request

curl -X POST 'https://api.mahvashai.ir/v1/vector_stores/<store_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "team": "support"
  }
}'

Response

A representative JSON response is not available for this endpoint. Handle the documented HTTP status and inspect the returned body according to your client workflow.

Status codes

HTTP	Details
200	Update a vector store's name or metadata.
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 a vector store

DELETE/v1/vector_stores/{store_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 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/vector_stores/<store_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

A representative JSON response is not available for this endpoint. Handle the documented HTTP status and inspect the returned body according to your client workflow.

Status codes

HTTP	Details
200	Delete a vector store.
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.