Quickstart

You need a Mahvash account and a place to run server-side code — a terminal with curl, a Node.js 18+ project, or Python 3.9+. The examples use the official OpenAI SDKs where they fit, and plain HTTP everywhere else, so you can follow along in any language.

Sign in to the Mahvash dashboard, open the project you want to use (your account already has a default project), and create an API key. Give it a name that says where it will live, such as local-dev or billing-service-prod.

The full key is displayed once. Mahvash stores only a keyed hash, so it cannot show the key again; if you lose it, rotate or issue a new one. The short mk_... prefix remains visible in the dashboard and is safe to use when you need to identify the key.

Put the key in an environment variable or your secret manager:

# .env on your server — never commit this file
MAHVASH_API_KEY=<shown-once-project-api-key>

A project key is pinned to one organization and one project. Everything you create with it — responses, files, vector stores — belongs to that project, and it cannot see anything in other projects.

Ask Mahvash which models your project can use right now:

curl https://api.mahvashai.ir/v1/models \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Each entry describes a logical model and its capabilities. The fields you will use most often are:

{
  "object": "list",
  "data": [
    {
      "id": "<model-id>",
      "object": "model",
      "owned_by": "<company>",
      "is_available": true,
      "supports_responses": true,
      "supports_chat_completions": true,
      "supports_streaming": true,
      "supports_json_mode": true,
      "reasoning": false,
      "context_window": 128000,
      "max_output_tokens": 16384
    }
  ]
}

• is_available — whether the model can be selected now.
• supports_responses, supports_chat_completions, supports_streaming — which APIs and delivery modes the model supports.
• supports_json_mode, reasoning — structured output and reasoning capabilities.
• context_window, max_output_tokens — size limits to respect when you build prompts.

The Responses API is the recommended starting point for new text integrations. The smallest useful request has a model and an input:

curl https://api.mahvashai.ir/v1/responses \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","input":"Say hello in one sentence."}'

model: "auto" lets Mahvash choose a suitable model for a chat-style request. If auto is not available for your route, use an ID returned by GET /v1/models.

The request above is non-streaming: the HTTP call stays open until the whole answer is ready and then returns one JSON object.

A successful call returns a response object:

{
  "id": "resp_<uuid>",
  "object": "response",
  "status": "completed",
  "model": "<model-id>",
  "output": [
    {
      "id": "msg_<id>",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "Hello! It is nice to meet you.", "annotations": [] }
      ]
    }
  ],
  "usage": { "input_tokens": 12, "output_tokens": 9, "total_tokens": 21 }
}

• id is the durable response ID. Store it if you might need to retrieve, continue or investigate this answer later.
• status is completed for a finished answer. Other values such as incomplete or failed need handling in production.
• output is a list of items, not a single string. A plain answer is one message item whose content holds output_text parts; tool calls, reasoning summaries or generated files appear as additional items.
• usage reports input, output and total tokens for the call.

The SDKs provide output_text as a convenience that joins the text for you. Without an SDK, collect the text yourself:

// Without the SDK: collect every output_text part of every message item.
const text = result.output
  .filter((item) => item.type === "message")
  .flatMap((item) => item.content)
  .filter((part) => part.type === "output_text")
  .map((part) => part.text)
  .join("");

console.log(result.id, result.status, text);
console.log("request id:", response.headers.get("X-Request-ID"));

Every response also carries an X-Request-ID header. Log it: it is the fastest way for support to find exactly what happened to a request.

You now have a working integration. Grow it one concern at a time:

• Stream text as it is generated — Streaming & events.
• Continue a conversation by passing previous_response_id with the previous response's id.
• Answer questions from your own documents — File inputs & retrieval.
• Make retries safe with Idempotency-Key and handle every error class — Headers & response shapes.
• Prepare for launch — Production integration checklist.

For every accepted field of the call you just made, see the Responses reference.