{
  "openapi": "3.1.0",
  "info": {
    "title": "أعربلي — Arabic Grammar & Syntactic Parser API",
    "description": "API رسمي من منصة أعربلي (https://a3rbly.com) لتحليل الجمل العربية نحوياً وصرفياً بدقة فائقة تتجاوز 99.9% مع التشكيل وتحديد أركان الجملة. يدعم الاستخدام المفتوح للضيوف والمصادقة للوكلاء والمطورين.",
    "version": "1.0.0",
    "contact": {
      "name": "أعربلي Support",
      "url": "https://a3rbly.com/developers",
      "email": "youssefdev74@gmail.com"
    },
    "x-when-to-use": [
      "Use when an agent or client needs word-by-word I'rab analysis of an Arabic sentence.",
      "Use for automatic diacritization (tashkeel) of Arabic text.",
      "Use for extracting grammatical roles (فاعل، مفعول، مبتدأ، خبر) in Arabic NLP pipelines."
    ]
  },
  "servers": [
    {
      "url": "https://hzproejhrfszrluuizax.supabase.co/functions/v1",
      "description": "خادم معالجة الإعراب الرئيسي (Supabase Edge Network)"
    }
  ],
  "paths": {
    "/parse-i3rab": {
      "post": {
        "operationId": "parseArabicSentence",
        "summary": "إعراب جملة عربية فورياً مع التحليل النحوي والتشكيل",
        "description": "تحليل الجملة العربية وتفكيكها إلى كلمات وتحديد موقع كل كلمة الإعرابي وحالتها وعلامتها الإعرابية مع شرح القاعدة.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "مفتاح تفادي التكرار الفريد لضمان معالجة الطلب مرة واحدة عند إعادة الإرسال في الشبكات الضعيفة",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["sentence"],
                "properties": {
                  "sentence": {
                    "type": "string",
                    "description": "الجملة أو النص العربي المراد إعرابه",
                    "example": "العلمُ نورٌ يضيءُ الدروبَ"
                  },
                  "action": {
                    "type": "string",
                    "enum": ["parse", "diacritize", "explain"],
                    "default": "parse",
                    "description": "نوع العملية المطلوبة"
                  },
                  "isGuest": {
                    "type": "boolean",
                    "default": true,
                    "description": "هل الطلب ضيف مفتوح بدون مفتاح API"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم التحليل والإعراب بنجاح",
            "headers": {
              "Idempotency-Key": {
                "description": "صدى مفتاح تفادي التكرار المستلم",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParseSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح (خطأ في المدخلات)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "خطأ في معالجة الخادم",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "security": [
          {},
          { "ApiKeyAuth": [] },
          { "OAuth2": ["parse:read"] }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "apikey",
        "description": "Self-serve API key generated from https://a3rbly.com/developers"
      },
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 authorization server metadata discovery at https://a3rbly.com/.well-known/oauth-authorization-server",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://hzproejhrfszrluuizax.supabase.co/auth/v1/token",
            "scopes": {
              "parse:read": "Syntactic dependency parsing",
              "grammar:read": "Grammar lookups",
              "tashkeel:write": "Diacritization"
            }
          }
        }
      }
    },
    "schemas": {
      "ParseSuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "sentence": { "type": "string" },
              "sentence_type": { "type": "string", "example": "جملة اسمية" },
              "words": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "word": { "type": "string" },
                    "role": { "type": "string", "example": "مبتدأ" },
                    "status": { "type": "string", "example": "مرفوع" },
                    "marker": { "type": "string", "example": "الضمة الظاهرة على آخره" },
                    "full_i3rab": { "type": "string" },
                    "explanation": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 7807 Structured Problem Details for HTTP APIs",
        "properties": {
          "type": { "type": "string", "format": "uri", "example": "https://a3rbly.com/errors/invalid-sentence" },
          "title": { "type": "string", "example": "Invalid Input Sentence" },
          "status": { "type": "integer", "example": 400 },
          "detail": { "type": "string", "example": "الجملة المدخلة فارغة أو لا تحتوي على كلمات عربية صالحة للإعراب." },
          "code": { "type": "string", "example": "INVALID_SENTENCE" },
          "instance": { "type": "string", "example": "/parse-i3rab" }
        },
        "required": ["type", "title", "status", "detail", "code"]
      }
    }
  }
}