API reference

Conversations and Chat Completions

Use the familiar Chat Completions format when your client already speaks it. Conversation operations let you inspect saved messages and runs.

How it fits together

01Create a chat completion
02List owned conversations
03Retrieve conversation metadata

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

Create a chat completion

POST/v1/chat/completions

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
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`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.
`asset_ids`	Body	array<value>	Optional	Mahvash extension	Reusable owned files to attach to the latest user message.
`audio`	Body	object	Optional	Conditional	Audio output configuration; requires an audio-output route.
`chat_id`	Body	string	Optional	Mahvash extension	Continue a stored, owner-scoped conversation.
`frequency_penalty`	Body	number	Optional	Supported	Frequency penalty, -2 to 2.
`function_call`	Body	string \| object	Optional	Deprecated	Legacy function selection. Prefer tool_choice.
`functions`	Body	array<value>	Optional	Deprecated	Legacy function definitions. Prefer tools.
`id_chat`	Body	string	Optional	Deprecated	Legacy alias of chat_id. Prefer chat_id in new clients.
`logit_bias`	Body	object	Optional	Conditional	Up to 300 token-ID biases between -100 and 100.
`logprobs`	Body	boolean	Optional	Conditional	Request token log probabilities; needs route support. Reported under choices[].logprobs, and per chunk while streaming.
`managed_tools`	Body	object	Optional	Mahvash extension	Mahvash-executed tools. Absent: the project's capability tools are offered automatically; enabled=false turns them off; tools narrows the set; max_rounds caps the tool rounds.
`max_completion_tokens`	Body	integer	Optional	Supported	Completion-token ceiling, 1 to 1,000,000.
`max_output_tokens`	Body	integer	Optional	Mahvash extension	Accepted alias of max_completion_tokens.
`max_tokens`	Body	integer	Optional	Deprecated	Legacy output-token ceiling. Prefer max_completion_tokens.
`messages`	Body	array<value>	Required	Supported	Conversation messages; 1 to 1,000 items.
`metadata`	Body	object	Optional	Supported	Bounded provider/application metadata object.
`modalities`	Body	array<value>	Optional	Conditional	Requested output modalities; each needs an output capability.
`mode`	Body	string	Optional	Mahvash extension	Automatic model-selection mode when no explicit model is given.
`model`	Body	string	Optional	Supported	Public logical model ID. Defaults to automatic selection.
`n`	Body	integer	Optional	Conditional	Number of choices. Values above 1 need explicit route support.
`parallel_tool_calls`	Body	boolean	Optional	Conditional	Allow parallel tool calls where the route supports it.
`prediction`	Body	object	Optional	Conditional	Predicted-output configuration forwarded to capable routes.
`presence_penalty`	Body	number	Optional	Supported	Presence penalty, -2 to 2.
`project`	Body	string	Optional	Mahvash extension	Project slug or ID for this request; conflicts are rejected.
`prompt_cache_key`	Body	string	Optional	Conditional	Prompt-cache partition name; namespaced per organization before it reaches the provider. Needs route support.
`prompt_cache_retention`	Body	string	Optional	Conditional	Prompt-cache retention preference; needs route support.
`prompt_id`	Body	string	Optional	Mahvash extension	Project-owned prompt resource to append to the run instructions.
`reasoning_effort`	Body	string	Optional	Conditional	Must be supported by the logical model and the route.
`response_format`	Body	object	Optional	Conditional	json_object or json_schema; the route must declare the capability. A json_schema declaration is bounded and, under strict, validated before any provider call, and the returned document is checked against it.
`safety_identifier`	Body	string	Optional	Supported	Stable safety identifier forwarded to a compatible route.
`seed`	Body	integer	Optional	Conditional	Provider determinism hint; needs route support.
`service_tier`	Body	string	Optional	Conditional	Provider service-tier request; needs route support.
`stop`	Body	string \| array<value>	Optional	Supported	Up to 4 stop sequences of at most 1,024 characters each.
`stream`	Body	boolean	Optional	Supported	Return Server-Sent Events instead of one JSON object.
`stream_options`	Body	object	Optional	Conditional	Only include_usage is accepted.
`temperature`	Body	number	Optional	Supported	Sampling temperature, 0 to 2.
`thinking`	Body	object	Optional	Mahvash extension	Provider reasoning configuration for routes that use it.
`tool_choice`	Body	string \| object	Optional	Supported	auto, none, required, or a provider-compatible object.
`tools`	Body	array<value>	Optional	Conditional	Function tools only; hosted tools belong to Responses.
`top_logprobs`	Body	integer	Optional	Conditional	Most likely tokens per position, 0 to 20; needs route support.
`top_p`	Body	number	Optional	Supported	Nucleus sampling, 0 to 1.
`user`	Body	string	Optional	Supported	Provider abuse-monitoring user identifier.
`verbosity`	Body	string	Optional	Conditional	Provider response verbosity option.
`web_search_options`	Body	object	Optional	Conditional	Requires a route supporting web search and this parameter.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/chat/completions' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": "Say hello in one sentence."
    }
  ]
}'

Response

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "<model-id>",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Hello!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "completion_tokens": 4,
    "total_tokens": 15
  }
}

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

Status codes

HTTP	Details
200	Create a chat completion.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
402	The account cannot authorize the request cost.
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.
502	The selected provider returned an invalid or failed response.
503	A dependency is temporarily unavailable.

List owned conversations

GET/v1/chat/completions

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
`search`	Query	string	Optional	Mahvash extension	Filter conversations by title or message content.
`status`	Query	string	Optional	Mahvash extension	Filter by conversation status.
`mode`	Query	string	Optional	Mahvash extension	Filter by conversation mode.
`is_pinned`	Query	boolean	Optional	Mahvash extension	Filter pinned conversations.
`ordering`	Query	string	Optional	Mahvash extension	updated_at or title, optionally prefixed with '-'.
`cursor`	Query	string	Optional	Mahvash extension	Opaque cursor from a previous page.
`limit`	Query	integer	Optional	Mahvash extension	Requested page size, capped by server policy.
`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/chat/completions' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "chat.completion",
      "created": 1750000000,
      "model": null,
      "metadata": {
        "chat_id": "<id>",
        "title": "<value>",
        "is_pinned": false,
        "status": "ACTIVE",
        "mode": "<value>"
      }
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false,
  "next": null,
  "previous": null
}

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

Status codes

HTTP	Details
200	List owned conversations.
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 conversation metadata

GET/v1/chat/completions/{pk}

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
`pk`	Path	string	Required	Mahvash extension	Conversation ID, with or without the chatcmpl- 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/chat/completions/<pk>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "chat.completion",
  "created": 1750000000,
  "model": null,
  "metadata": {
    "chat_id": "<id>",
    "title": "<value>",
    "is_pinned": false,
    "status": "ACTIVE",
    "mode": "<value>"
  }
}

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

Status codes

HTTP	Details
200	Retrieve conversation 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.

List messages and attached files in a conversation

GET/v1/chat/completions/{pk}/messages

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
`pk`	Path	string	Required	Mahvash extension	Conversation ID.
`search`	Query	string	Optional	Mahvash extension	Filter messages by content substring.
`cursor`	Query	string	Optional	Mahvash extension	Opaque cursor from a previous page.
`limit`	Query	integer	Optional	Mahvash extension	Requested page size, capped by server policy.
`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/chat/completions/<pk>/messages' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "chat.completion.message",
      "role": "user",
      "content": "<value>",
      "content_parts": [],
      "tool_calls": [],
      "attachments": [],
      "created": 1750000000,
      "metadata": {
        "status": "COMPLETED"
      }
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false,
  "next": null,
  "previous": null
}

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

Status codes

HTTP	Details
200	List messages and attached files in a conversation.
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.

Request cancellation of an in-flight run

POST/v1/chat/completions/cancel

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.
`run_id`	Body	string	Required	Mahvash extension	Run identifier returned by a queued or streaming request.

Request

curl -X POST 'https://api.mahvashai.ir/v1/chat/completions/cancel' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "run_id": "3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'

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	Request cancellation of an in-flight run.
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.

Redact and delete a conversation

DELETE/v1/chat/completions/{pk}

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
`pk`	Path	string	Required	Mahvash extension	Conversation ID to redact.
`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/chat/completions/<pk>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "message": "<value>"
}

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

Status codes

HTTP	Details
200	Redact and delete a conversation.
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.