API reference

Retrieval placement

Placement controls where a vector store is indexed. A transition has its own lifecycle; inspect it before depending on the new placement.

How it fits together

01Mahvash extension (ADR-037): move a populated vector store between the Mahvash-hosted index and a provider account. Returns 202 with a durable transition; the store keeps answering from its current placement until cutover
02Mahvash extension (ADR-037): the store's in-flight placement transition, or an empty list when it is not moving
03Mahvash extension (ADR-037): cancel a transition that has not cut over. Refused afterwards - moving back is a new transition, not an undo

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

Mahvash extension (ADR-037): move a populated vector store between the Mahvash-hosted index and a provider account. Returns 202 with a durable transition; the store keeps answering from its current placement until cutover

POST/v1/vector_stores/{store_id}/placement_transitions

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.
`target_placement`	Body	string	Required	Mahvash extension	'local' or 'hosted'. Must differ from where the store currently reads. A store created before per-store placement existed has no resolved source and is refused.

Request

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

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
202	Mahvash extension (ADR-037): move a populated vector store between the Mahvash-hosted index and a provider account. Returns 202 with a durable transition; the store keeps answering from its current placement until cutover.
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.

Mahvash extension (ADR-037): the store's in-flight placement transition, or an empty list when it is not moving

GET/v1/vector_stores/{store_id}/placement_transitions

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.
`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>/placement_transitions' \
  -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	Mahvash extension (ADR-037): the store's in-flight placement transition, or an empty list when it is not moving.
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.

Mahvash extension (ADR-037): cancel a transition that has not cut over. Refused afterwards - moving back is a new transition, not an undo

DELETE/v1/vector_stores/{store_id}/placement_transitions

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.
`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>/placement_transitions' \
  -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	Mahvash extension (ADR-037): cancel a transition that has not cut over. Refused afterwards - moving back is a new transition, not an undo.
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.