openapi: 3.1.0
info:
  title: Ashraf Al-Khawaja Public Jordanian Legal Information API
  version: 1.0.0
  description: |
    واجهة عامة للمعلومات القانونية الأولية المرتبطة بالقانون الأردني من مكتب المحامي أشرف الخواجة ومشاركوه.
    لا تنشئ هذه الواجهة علاقة محامٍ وموكل، ولا تقدم رأياً قانونياً نهائياً أو قانوناً أجنبياً أو ضماناً للنتيجة.
    لا ترسل كلمات مرور أو رموز وصول أو بيانات دفع أو أرقاماً وطنية أو مستندات سرية.
  contact:
    name: Ashraf Al-Khawaja & Associates
    email: Alkhwajalawfirm@gmail.com
    url: https://alkhwajalawfirm.com/
  license:
    name: Public informational interface; source attribution required
    url: https://alkhwajalawfirm.com/privacy-policy?lang=ar
servers:
  - url: https://alkhwajalawfirm.com
    description: Production public origin
paths:
  /api/gemini:
    post:
      operationId: askJordanianLegalAssistant
      summary: Ask the public legal assistant
      description: Ask for preliminary general information connected to Jordanian law. The response includes a disclaimer and may include source links and follow-up questions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Preliminary answer with disclaimer, sources, and related questions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvisorResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit reached
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/chat:
    post:
      operationId: askJordanianLegalAssistantAlias
      summary: Ask the public legal assistant (alias)
      description: Alias of /api/gemini with the same public request and response contract.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Preliminary answer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvisorResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/chat/analyze-documents:
    post:
      operationId: analyzePublicLegalDocuments
      summary: Preliminary analysis of PDF or image documents
      description: Analyze up to three PDF, JPEG, or PNG files in memory for preliminary issue spotting. Do not upload confidential or unnecessary documents. The result is not legal advice.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentAnalysisRequest'
      responses:
        '200':
          description: Preliminary document analysis envelope
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      data:
                        type: object
                        properties:
                          json:
                            $ref: '#/components/schemas/DocumentAnalysisResponse'
        '400':
          description: Invalid document request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /court-fees:
    get:
      operationId: openJordanianCourtFeesCalculator
      summary: Open the Jordanian court-fees calculator
      description: Public bilingual web calculator with indicative procedures and a notice to confirm the final amount with the competent court.
      parameters:
        - name: lang
          in: query
          required: false
          schema:
            type: string
            enum: [ar, en]
            default: ar
      responses:
        '200':
          description: Calculator web page
          content:
            text/html:
              schema:
                type: string
  /court-fees-index.json:
    get:
      operationId: getJordanianCourtFeesIndex
      summary: Get calculator procedures and legal-basis metadata
      description: Machine-readable public index for the indicative Jordanian court-fees calculator.
      responses:
        '200':
          description: Calculator index
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    ChatMessage:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
          enum: [user, assistant]
        content:
          type: string
          minLength: 1
          maxLength: 4000
    ChatRequest:
      type: object
      required: [language, messages]
      properties:
        language:
          type: string
          enum: [ar, en]
          default: ar
        messages:
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: '#/components/schemas/ChatMessage'
    Document:
      type: object
      required: [name, mimeType, dataBase64]
      properties:
        name:
          type: string
        mimeType:
          type: string
          enum: [application/pdf, image/jpeg, image/png]
        dataBase64:
          type: string
          description: Base64-encoded document content; maximum 5 MiB per document and 3 documents per request.
    DocumentAnalysisRequest:
      type: object
      required: [language, question, documents]
      properties:
        language:
          type: string
          enum: [ar, en]
          default: ar
        question:
          type: string
          minLength: 1
          maxLength: 3000
        documents:
          type: array
          minItems: 1
          maxItems: 3
          items:
            $ref: '#/components/schemas/Document'
    Source:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
          enum: [article]
        title:
          type: string
        excerpt:
          type: string
        url:
          type: string
          format: uri
        matchedOn:
          type: array
          items:
            type: string
    AdvisorResponse:
      type: object
      required: [answer, disclaimer, grounded, sources, followUpQuestions, relatedQuestions]
      properties:
        answer:
          type: string
        disclaimer:
          type: string
        grounded:
          type: boolean
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
        followUpQuestions:
          type: array
          items:
            type: string
        relatedQuestions:
          type: array
          items:
            type: string
        policy:
          type: object
          additionalProperties: true
    DocumentAnalysisResponse:
      type: object
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string