# Public information paths are relative to the /api server mount.

about:
  get:
    tags: [Common]
    summary: Get About Us content
    description: |
      Returns the localized About Us content.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8431&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">App</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116242&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8431&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116242&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    operationId: getAboutUs
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Localized About Us content.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/AboutSuccessResponse' }
            example:
              key: success
              message: تم بنجاح
              status: 200
              data:
                description: نبذة عن المنصة
      '400':
        description: Missing or invalid secret key/language header.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples: &info-validation-examples
              invalidLanguage:
                value: { key: fail, message: "لغه غير صحيحة", status: 400 }
              requestRejected:
                value: { key: fail, message: "حدث خطا", status: 400 }
      '500':
        description: Unexpected server error while retrieving About content.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
            example:
              key: exception
              message: حدث خطأ، يرجى المحاولة مرة أخرى
              status: 500

fqs:
  get:
    tags: [Common]
    summary: List frequently asked questions
    description: |
      Uses the existing route name `/fqs`.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=10447-72966&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">App</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10449-64386&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=10447-72966&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10449-64386&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    operationId: listFrequentlyAskedQuestions
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Localized FAQ list ordered newest first.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/FaqsSuccessResponse' }
            example:
              key: success
              message: الأسئلة الشائعة
              status: 200
              data:
                - id: "665f1c2a9b4e1d0012ab34d0"
                  question: كيف يمكنني استخدام التطبيق؟
                  answer: يمكنك إنشاء حساب ثم تسجيل الدخول.
      '400':
        description: Missing or invalid secret key/language header.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples: *info-validation-examples
      '500': { $ref: '#/shared-server-error' }

privacy:
  get:
    tags: [Common]
    summary: Get Privacy Policy
    description: |
      Returns the localized Privacy Policy content.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8779&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">App</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8779&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    operationId: getPrivacyPolicy
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Localized privacy policy text.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/PrivacySuccessResponse' }
            example:
              key: success
              message: "سياسة الخصوصية"
              status: 200
              data: "سياسة الخصوصية الخاصة بالمنصة"
      '400':
        description: Missing or invalid secret key/language header.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples: *info-validation-examples
      '500': { $ref: '#/shared-server-error' }

terms:
  get:
    tags: [Common]
    summary: Get Terms and Conditions
    description: |
      Returns the localized Terms and Conditions content.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8712&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">App</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116254&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    x-figma:
      app: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8712&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      web: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116254&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038"
    operationId: getTermsAndConditions
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Localized terms and conditions content.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/TermsSuccessResponse' }
            example:
              key: success
              message: الشروط والأحكام
              status: 200
              data:
                terms: الشروط والأحكام الخاصة باستخدام المنصة
      '400':
        description: Missing or invalid secret key/language header.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples: *info-validation-examples
      '500': { $ref: '#/shared-server-error' }

intros:
  get:
    tags: [Common]
    summary: List application intro screens
    description: |
      Paginated catalogue of localized intro screens ordered newest first.
      Same screen is used by client and provider onboarding.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-6157&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Client Mobile</a><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-6157&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Provider Mobile</a></div>
    x-figma:
      clientMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-6157&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      clientMobileNodeId: "9064:6157"
      providerMobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-6157&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      providerMobileNodeId: "9064:6157"
    operationId: listIntroScreens
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
      - name: page
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 1 }
      - name: limit
        in: query
        required: false
        schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    responses:
      '200':
        description: Paginated localized intro screens ordered newest first.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/IntroListResponse' }
            example:
              key: success
              message: الصفحات الافتتاحية
              status: 200
              data:
                - id: "665f1c2a9b4e1d0012ab34d1"
                  title: اكتشف الخدمات
                  description: تصفح الخدمات المتاحة بسهولة.
                  image: "https://example.com/assets/uploads/intros/intro-01.png"
              paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Pagination validation failed.
        content:
          application/json:
            schema: { $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
              invalidLimit:
                value: { key: fail, message: "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", status: 400 }
      '500': { $ref: '#/shared-server-error' }

shared-server-error:
  description: Unexpected server error. No stack trace is returned.
  content:
    application/json:
      schema: { $ref: '../openapi.yaml#/components/schemas/ErrorResponse' }
      example: { key: exception, message: "حدث خطأ", status: 500 }
