API reference

Responses

The primary API for text, tools, streaming, and durable background work. Start with a simple request, then add capabilities as needed.

How it fits together

01Create a response
02Retrieve one owned response
03List the input items one owned response was asked

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

Create a response

POST/v1/responses

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.
`background`	Body	boolean	Optional	Supported	Admit the request durably and answer before the provider does.
`chat_id`	Body	string	Optional	Mahvash extension	Continue a stored, owner-scoped conversation.
`container`	Body	string \| object	Optional	Conditional	Provider container configuration; needs explicit route support.
`id_chat`	Body	string	Optional	Deprecated	Legacy alias of chat_id. Prefer chat_id in new clients.
`include`	Body	array<value>	Optional	Conditional	Request additional response data from a capable route: web-search sources and results, file-search results, or output-text logprobs.
`input`	Body	string \| array<value>	Required	Supported	Text or typed input items.
`instructions`	Body	string	Optional	Supported	System or developer instruction text.
`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_output_tokens`	Body	integer	Optional	Supported	Output-token ceiling.
`max_tool_calls`	Body	integer	Optional	Conditional	Bounded by the service hosted-tool call cap.
`metadata`	Body	object	Optional	Supported	Bounded metadata object echoed in the response.
`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.
`parallel_tool_calls`	Body	boolean	Optional	Conditional	Allow parallel tool calls where the route supports it.
`previous_response_id`	Body	string	Optional	Supported	Continue a completed response on its pinned route.
`project`	Body	string	Optional	Mahvash extension	Project slug or ID for this request; conflicts are rejected.
`prompt`	Body	object \| string	Optional	Conditional	Provider prompt-template reference.
`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`	Body	object	Optional	Conditional	Reasoning configuration; the route must support the request.
`safety_identifier`	Body	string	Optional	Supported	Stable provider safety identifier.
`service_tier`	Body	string	Optional	Conditional	Provider service tier; needs route support.
`store`	Body	boolean	Optional	Conditional	Provider storage preference.
`stream`	Body	boolean	Optional	Supported	Return typed Server-Sent Events.
`temperature`	Body	number	Optional	Supported	Sampling temperature, 0 to 2.
`text`	Body	object	Optional	Conditional	Text and structured-output configuration. A json_schema format is bounded and validated before any provider call, and the returned document is checked against it.
`text_format`	Body	object	Optional	Mahvash extension	Explicit structured-output format alias.
`tool_choice`	Body	string \| object	Optional	Supported	Tool selection policy forwarded to a compatible route.
`tools`	Body	array<value>	Optional	Conditional	Function tools and the registered provider-hosted tools.
`top_p`	Body	number	Optional	Supported	Nucleus sampling, 0 to 1.
`truncation`	Body	string	Optional	Conditional	Provider truncation mode.
`user`	Body	string	Optional	Supported	Provider abuse-monitoring user identifier.

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

Request

curl -X POST 'https://api.mahvashai.ir/v1/responses' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "model": "auto",
  "input": "Summarize the value of a small, reliable API in one sentence."
}'

Response

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1750000000,
  "status": "completed",
  "model": "<model-id>",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 11,
    "output_tokens": 4,
    "total_tokens": 15
  }
}

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

Status codes

HTTP	Details
200	Create a response.
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.

Retrieve one owned response

GET/v1/responses/{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	Supported	Response ID beginning with resp_.
`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/responses/<pk>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "<value>",
  "created_at": 0,
  "status": "queued",
  "background": false,
  "error": "<value>",
  "incomplete_details": "<value>",
  "instructions": "<value>",
  "max_output_tokens": "<value>",
  "model": "<value>",
  "output": [
    {
      "type": "<value>"
    }
  ],
  "parallel_tool_calls": false,
  "previous_response_id": "<id>",
  "reasoning": "<value>"
}

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

Status codes

HTTP	Details
200	Retrieve one owned response.
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 the input items one owned response was asked

GET/v1/responses/{pk}/input_items

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	Supported	Response ID beginning with resp_.
`limit`	Query	integer	Optional	Supported	Page size, 1 to 100. Defaults to 20.
`order`	Query	string	Optional	Supported	asc (default) or desc, by item order.
`after`	Query	string	Optional	Supported	Return items after this item ID.
`before`	Query	string	Optional	Supported	Return items before this item 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/responses/<pk>/input_items' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "<value>",
  "data": [
    {
      "id": "<id>",
      "type": "<value>"
    }
  ],
  "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 the input items one owned response was asked.
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 owned response

POST/v1/responses/{pk}/cancel

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	Supported	Response ID to cancel.
`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 POST 'https://api.mahvashai.ir/v1/responses/<pk>/cancel' \
  -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	Request cancellation of an owned response.
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.

Delete an owned response

DELETE/v1/responses/{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	Supported	Response 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/responses/<pk>' \
  -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 an owned response.
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.