مرجع API

{
  "summary": "فهرست مدل‌ها و مسیرهای قابل استفاده",
  "description": "Required scope: models:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_models",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "models"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  },
  {
    "name": "X-Customer-ID",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 120
    },
    "description": "Your internal customer or record ID for usage reconciliation; do not include personal information."
  },
  {
    "name": "X-Reference-ID",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 120
    },
    "description": "Your internal customer or record ID for usage reconciliation; do not include personal information."
  }
]

{
  "summary": "Chat with text, images, inline audio/video, function tools and structured outputs",
  "description": "Select thinking intensity with reasoning.effort (or reasoning_effort). Discover the exact supported values per model in GET /v1/models reasoning.supported_efforts. Omit both fields for automatic behavior. Unsupported values and conflicting aliases return HTTP 400 before credits are reserved. Higher effort may take longer and consume more output tokens within the request token limit. include_reasoning controls visibility separately.",
  "operationId": "post__v1_chat_completions",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    },
    {
      "name": "X-Customer-ID",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 120
      },
      "description": "Your internal customer or record ID for usage reconciliation; do not include personal information."
    },
    {
      "name": "X-Reference-ID",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 120
      },
      "description": "Your internal customer or record ID for usage reconciliation; do not include personal information."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ChatCompletionRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "OpenAI-compatible completion or SSE; tool execution remains in the client.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ChatCompletion"
          }
        },
        "text/event-stream": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "chat"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  },
  {
    "name": "X-Customer-ID",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 120
    },
    "description": "Your internal customer or record ID for usage reconciliation; do not include personal information."
  },
  {
    "name": "X-Reference-ID",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 120
    },
    "description": "Your internal customer or record ID for usage reconciliation; do not include personal information."
  }
]

{
  "summary": "Text or single-image Responses; JSON or SSE",
  "description": "Select thinking intensity with reasoning.effort (or reasoning_effort). Discover the exact supported values per model in GET /v1/models reasoning.supported_efforts. Omit both fields for automatic behavior. Unsupported values and conflicting aliases return HTTP 400 before credits are reserved. Higher effort may take longer and consume more output tokens within the request token limit. include_reasoning controls visibility separately. Text models require responses:write. An image model as the top-level model requires studio:write and returns one image_generation_call with base64 result; optional image_generation settings and stream=true are supported. Chat-model image tools, previous_response_id, remote image URLs and partial images are not supported. See the images guide for supported options.",
  "operationId": "post__v1_responses",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    },
    {
      "name": "X-Customer-ID",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 120
      },
      "description": "Your internal customer or record ID for usage reconciliation; do not include personal information."
    },
    {
      "name": "X-Reference-ID",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 120
      },
      "description": "Your internal customer or record ID for usage reconciliation; do not include personal information."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ResponseRequest"
        },
        "example": {
          "model": "z-ai/glm-5.3-flash",
          "input": "سلام! در یک جمله خودت را معرفی کن.",
          "max_output_tokens": 512
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "JSON response (including image_generation_call for image models), or SSE when stream=true: response.output_item.done, response.image_generation_call.completed, response.created, response.output_text.delta, response.reasoning.delta (opt-in), response.tool, response.completed or response.failed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "object": {
                "const": "response"
              },
              "model": {
                "type": "string"
              },
              "status": {
                "enum": [
                  "completed",
                  "incomplete"
                ]
              },
              "output_text": {
                "type": "string"
              },
              "reasoning": {
                "type": "object",
                "description": "Present only when include_reasoning=true. Provider output; availability varies.",
                "properties": {
                  "status": {
                    "enum": [
                      "available",
                      "unavailable"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "format": {
                    "enum": [
                      "summary",
                      "text"
                    ]
                  },
                  "source": {
                    "const": "provider"
                  }
                }
              },
              "output": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "usage": {
                "type": "object",
                "properties": {
                  "input_tokens": {
                    "type": "integer"
                  },
                  "output_tokens": {
                    "type": "integer"
                  },
                  "total_tokens": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "text/event-stream": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "responses"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ساخت image با موتور استودیو",
  "description": "Required scope: studio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_studio_image",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ImageRequest"
        },
        "example": {
          "model": "google/gemini-2.5-flash-image",
          "prompt": "یک پوستر عمودی از انار سرخ روی میز سنگی، نور نرم پنجره",
          "aspectRatio": "auto",
          "count": 1
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ImageResult"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "studio"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ساخت audio با موتور استودیو",
  "description": "Required scope: studio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_studio_audio",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AudioRequest"
        },
        "example": {
          "model": "google/gemini-3.8-flash-tts",
          "text": "سلام! به ساروی خوش آمدید.",
          "voice": "Kore",
          "format": "wav",
          "instructions": "Warm, friendly Persian"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AudioResult"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "studio"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ساخت text با موتور استودیو",
  "description": "Required scope: studio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_studio_text",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TextRequest"
        },
        "example": {
          "model": "z-ai/glm-5.3",
          "prompt": "یک معرفی کوتاه فارسی برای یک فروشگاه بنویس."
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TextResult"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "studio"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ساخت video با موتور استودیو",
  "description": "Required scope: studio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_studio_video",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VideoRequest"
        },
        "example": {
          "model": "bytedance/seedance-2.5",
          "prompt": "نمای نزدیک گل‌های بهاری، حرکت آرام دوربین و نور صبح",
          "duration": 4,
          "resolution": "480p",
          "aspectRatio": "16:9",
          "generateAudio": false
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Accepted; poll status until terminal completion.",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoSubmission"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "studio"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "وضعیت و تسویهٔ ساخت ویدیو",
  "description": "Required scope: studio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_studio_video_status",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VideoJob"
        },
        "example": {
          "id": "SAROVI_JOB_ID",
          "providerJobId": "PROVIDER_JOB_ID"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoStatus"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "studio"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "دریافت فایل ویدیو پس از تکمیل",
  "description": "Required scope: studio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_studio_video_content",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VideoJob"
        },
        "example": {
          "id": "SAROVI_JOB_ID",
          "providerJobId": "PROVIDER_JOB_ID"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Video file",
      "content": {
        "video/mp4": {
          "schema": {
            "type": "string",
            "format": "binary"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "studio"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "تبدیل صدای Base64 به متن",
  "description": "Required scope: audio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_audio_transcriptions",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TranscriptionRequest"
        },
        "example": {
          "model": "openai/whisper-large-v3-turbo",
          "language": "fa",
          "audioBase64": "YOUR_BASE64_AUDIO_DATA",
          "mediaType": "audio/wav"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TranscriptionResponse"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "audio"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ساخت اتصال WebRTC با SDP",
  "description": "Required scope: audio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_realtime_calls",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RealtimeCreate"
        },
        "example": {
          "sdp": "YOUR_WEBRTC_OFFER_SDP"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "realtime"
  ]
}

{
  "summary": "پایان اتصال صوتی متعلق به حساب",
  "description": "Required scope: audio:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "delete__v1_realtime_calls",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RealtimeEnd"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "realtime"
  ]
}

{
  "summary": "عامل‌های پروژه",
  "description": "Required scope: agents:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_agents",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "agents"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ذخیرهٔ عامل",
  "description": "Required scope: agents:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_agents",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Agent"
        },
        "example": {
          "name": "دستیار پشتیبانی",
          "kind": "chat",
          "model": "z-ai/glm-5.3-flash",
          "instructions": "به فارسی پاسخ بده. اگر اطلاعات کافی نیست، یک پرسش روشن بپرس."
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "agents"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "summary": "حذف عامل",
  "description": "Required scope: agents:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "delete__v1_agents_id_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "agents"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "tags": [
    "agents"
  ],
  "summary": "Update the saved agent draft",
  "description": "Required scope: agents:write. See /developers/docs/business-start. Shared account credits; business budgets and project ownership are enforced.",
  "operationId": "patch__v1_agents_id_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AgentPatch"
        },
        "example": {
          "instructions": "Answer from business documents and offer human handoff."
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AgentRecord"
          }
        }
      }
    },
    "default": {
      "description": "Structured API error; no successful completion is implied.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "اجرای عامل؛ پاسخ مستقیم یا کار ماندگار",
  "description": "Required scope: agents:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_agents_id_runs",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AgentRun"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "202": {
      "description": "Durable Work accepted; poll status_url."
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "agents"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "شروع پژوهش، سند، کد یا تحلیل داده",
  "description": "Required scope: work:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_work",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/WorkRequest"
        },
        "example": {
          "kind": "document",
          "title": "راهنمای شروع فروشگاه",
          "input": "یک راهنمای عملی فارسی برای شروع فروشگاه کوچک اینترنتی بنویس. چک‌لیست مراحل و جدول هزینه‌های نمونه داشته باشد."
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Work accepted. Poll the existing status_url; do not resubmit to check progress.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WorkAccepted"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "work"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "summary": "دریافت وضعیت، رویدادها و فهرست فایل‌ها",
  "description": "Required scope: files:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_work_id_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "work"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "لغو کار",
  "description": "Required scope: work:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_work_id_cancel",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "work"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "in": "query",
    "name": "path",
    "schema": {
      "type": "string"
    },
    "description": "Exact artifact manifest file path; required unless bundle=1."
  },
  {
    "in": "query",
    "name": "bundle",
    "schema": {
      "enum": [
        "1"
      ]
    }
  }
]

{
  "summary": "دریافت فایل خروجی یا بستهٔ کامل",
  "description": "Required scope: files:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_work_id_files",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "path",
      "schema": {
        "type": "string"
      },
      "description": "Exact artifact manifest file path; required unless bundle=1."
    },
    {
      "in": "query",
      "name": "bundle",
      "schema": {
        "enum": [
          "1"
        ]
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Artifact file",
      "content": {
        "application/octet-stream": {
          "schema": {
            "type": "string",
            "format": "binary"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "work"
  ]
}

{
  "summary": "پروژه‌های دانشی مشترک حساب",
  "description": "Required scope: knowledge:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_knowledge",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "knowledge"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ساخت پروژهٔ دانشی در حساب",
  "description": "Required scope: knowledge:write. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "post__v1_knowledge",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/KnowledgeCreate"
        },
        "example": {
          "name": "راهنمای محصول",
          "instructions": "پاسخ‌ها را با توجه به راهنمای محصول بنویس."
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "knowledge"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "summary": "دریافت فایل تصویر یا صدای ذخیره‌شدهٔ پروژه",
  "description": "Required scope: files:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_files_id_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Stored media file",
      "content": {
        "application/octet-stream": {
          "schema": {
            "type": "string",
            "format": "binary"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "files"
  ]
}

{
  "summary": "موجودی مشترک حساب",
  "description": "Required scope: usage:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_balance",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [],
  "responses": {
    "200": {
      "description": "The account balance shared by Sarovi products.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Balance"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "balance"
  ]
}

{
  "summary": "مصرف پروژه در ۳۰ روز گذشته",
  "description": "Required scope: usage:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_usage",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "usage"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "summary": "گزارش و وضعیت درخواست پروژه",
  "description": "Required scope: usage:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_requests_id_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "requests"
  ]
}

[
  {
    "in": "query",
    "name": "idempotency_key",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{1,128}$"
    },
    "description": "The original request key. Only receipts submitted with the current API credential are returned. This does not repeat generation."
  }
]

{
  "summary": "Recover a request receipt after lost response headers",
  "description": "Required scope: usage:read. Credits are shared with the Sarovi account. See /developers/docs for limits and billing.",
  "operationId": "get__v1_requests_lookup",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "idempotency_key",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^[A-Za-z0-9._:-]{1,128}$"
      },
      "description": "The original request key. Only receipts submitted with the current API credential are returned. This does not repeat generation."
    }
  ],
  "responses": {
    "200": {
      "description": "Billing metadata only. An empty data array means no receipt was found; it does not prove the original request was uncharged.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "maxItems": 1,
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "idempotency_key",
                    "endpoint",
                    "state",
                    "credits",
                    "pending"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "idempotency_key": {
                      "type": "string"
                    },
                    "endpoint": {
                      "type": "string"
                    },
                    "state": {
                      "enum": [
                        "running",
                        "completed",
                        "failed"
                      ]
                    },
                    "status_code": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "credits": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "pending": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "requests"
  ]
}

{
  "summary": "فهرست ابرهای پروژه و بسته‌های آماده",
  "description": "Required scope: cloud:read. Starter has capped free infrastructure. Dedicated infrastructure requires an existing paid package and provider availability; AI credits are separate. See /developers/docs for limits and billing.",
  "operationId": "get__v1_cloud",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "cloud"
  ]
}

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ساخت Starter رایگان یا ابر اختصاصی",
  "description": "Required scope: cloud:write. Starter has capped free infrastructure. Dedicated infrastructure requires an existing paid package and provider availability; AI credits are separate. See /developers/docs for limits and billing.",
  "operationId": "post__v1_cloud",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CloudCreate"
        },
        "example": {
          "name": "فروشگاه من",
          "plan": "starter"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Starter created and ready."
    },
    "202": {
      "description": "Accepted; poll status until terminal completion.",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "cloud"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "summary": "حذف دائمی ابر و سایت‌های آن",
  "description": "Required scope: cloud:write. Starter has capped free infrastructure. Dedicated infrastructure requires an existing paid package and provider availability; AI credits are separate. See /developers/docs for limits and billing.",
  "operationId": "delete__v1_cloud_id_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CloudDelete"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "cloud"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "summary": "وضعیت ابر و سلامت سرویس‌ها",
  "description": "Required scope: cloud:read. Starter has capped free infrastructure. Dedicated infrastructure requires an existing paid package and provider availability; AI credits are separate. See /developers/docs for limits and billing.",
  "operationId": "get__v1_cloud_id_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "cloud"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "name": "siteId",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "summary": "حذف دائمی سایت و انتشارهای آن",
  "description": "Required scope: cloud:hosting. Starter has capped free infrastructure. Dedicated infrastructure requires an existing paid package and provider availability; AI credits are separate. See /developers/docs for limits and billing.",
  "operationId": "delete__v1_cloud_id_sites_siteId_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "siteId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CloudDelete"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "cloud"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "name": "siteId",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]

{
  "summary": "وضعیت و URL انتشار سایت",
  "description": "Required scope: cloud:read. Starter has capped free infrastructure. Dedicated infrastructure requires an existing paid package and provider availability; AI credits are separate. See /developers/docs for limits and billing.",
  "operationId": "get__v1_cloud_id_sites_siteId_",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "siteId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "cloud"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "name": "Idempotency-Key",
    "in": "header",
    "schema": {
      "type": "string",
      "maxLength": 128
    },
    "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
  }
]

{
  "summary": "ادامهٔ آماده‌سازی همان ابر",
  "description": "Required scope: cloud:write. Starter has capped free infrastructure. Dedicated infrastructure requires an existing paid package and provider availability; AI credits are separate. See /developers/docs for limits and billing.",
  "operationId": "post__v1_cloud_id_retry",
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
        "type": "string",
        "maxLength": 128
      },
      "description": "Stable unique key per logical request. Replays JSON below 1 MB for 24 hours; otherwise returns REQUEST_ALREADY_ACCEPTED."
    }
  ],
  "responses": {
    "202": {
      "description": "Accepted; poll status until terminal completion.",
      "headers": {
        "X-Request-ID": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error. 400 invalid input; 401 invalid key; 402 balance or budget; 403 scope/plan/account; 404 resource; 409 idempotency conflict; 429 rate/concurrency; 5xx service/provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  },
  "tags": [
    "cloud"
  ]
}

[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  }
]