Build with Mahvash

Mahvash sits between your application and the model providers it can reach. You send one familiar request shape to https://api.mahvashai.ir; Mahvash checks who is calling and on behalf of which project, validates the request, picks a provider route that can actually serve it, runs the call, and returns a normalized answer. Every call is recorded as a durable run with its own ID, usage and cost, owned by your organization.

That means you can build on the OpenAI wire format you may already know, while Mahvash takes care of the parts that are hard to do yourself:

• One API for many models. You ask for a logical model such as auto or an ID from GET /v1/models; Mahvash chooses a compatible upstream route.
• Workspaces with real isolation. Organizations, projects, teams and scoped API keys keep each customer, product or environment separate.
• Durable, inspectable work. Responses have stable IDs, can run in the background, can be retrieved and cancelled, and support idempotent retries.
• Files and retrieval. Upload documents once, index them into vector stores and get answers with citations.
• Managed tools. Where a project enables them, Mahvash can give a model web search, image generation, or document and image reading that its own route lacks.

The AI API follows OpenAI's endpoint names, so most existing examples and SDKs map directly. The main families are:

• Text and reasoning — POST /v1/responses (recommended for new work) and POST /v1/chat/completions for chat-style integrations.
• Embeddings — POST /v1/embeddings for semantic search, clustering and deduplication.
• Images — POST /v1/images/generations and POST /v1/images/edits.
• Audio — POST /v1/audio/transcriptions to turn speech into text and POST /v1/audio/speech to turn text into speech.
• Safety — POST /v1/moderations to classify user content before you process it.
• Documents — /v1/files, /v1/vector_stores and the file_search tool for question answering over your own files.
• Bulk work — /v1/batches to run thousands of requests asynchronously from a JSONL file.

Around these, Mahvash adds workspace APIs under /api/v1 for organizations, projects, API keys, members, teams, prompts, data sources and webhooks.

Mahvash exposes two families of endpoints. Knowing which one you are calling tells you which credential to send and how to read the response.

In practice, your production server usually talks to /v1 with a project API key, while an administrator or a provisioning script uses /api/v1/tenancy with a signed-in user's token to set projects and keys up. Headers & response shapes covers the response formats in detail.

A handful of terms appear on every page of this documentation:

• Organization — the top-level tenant and billing boundary. Every account starts with a personal organization; companies create shared ones.
• Project — a workspace inside an organization. It owns runs, files, vector stores, prompts and API keys. Each organization has a default project.
• Project API key — a secret (mk_...) for server-to-server calls, pinned to exactly one organization and project.
• User access JWT — a short-lived token that represents a signed-in person; required for workspace administration.
• Logical model — the model ID you request. Mahvash maps it to a concrete provider route per request.
• Response / run — one admitted request with a stable ID (resp_...), status, output and usage.
• Asset, file and vector store — reusable uploads, OpenAI-style file objects, and searchable indexes built from files.

Pick the route that matches what you are building:

1. 1First request in a few minutes — follow the Quickstart.
2. 2Serving several customers or teams — read Authentication and Organizations & projects, then the Multi-customer SaaS scenario.
3. 3Answering questions over documents — read File inputs & retrieval, then Build document Q&A.
4. 4Real-time chat UI — read Streaming & events, then the Interactive support chat scenario.
5. 5Going to production — work through Headers & response shapes and the Production integration checklist.

The API reference lists every endpoint with its accepted inputs, status codes and examples. Use it when you need an exact field; use the guides to understand how the pieces fit together.

All requests go to https://api.mahvashai.ir. Official OpenAI SDKs work for supported /v1 operations once you point them at https://api.mahvashai.ir/v1 and give them a Mahvash project API key:

import OpenAI from "openai";

// Server-side only. The key comes from your secret store or environment.
export const mahvash = new OpenAI({
  apiKey: process.env.MAHVASH_API_KEY,
  baseURL: "https://api.mahvashai.ir/v1",
  timeout: 60_000,
  maxRetries: 0, // Decide retries yourself; see "Errors and retries".
});