openapi: 3.0.3
info:
  title: FactLens API
  version: 1.0.0
  description: |
    FactLens API for submitting content analysis requests.

    This API currently accepts both:
    - Structured payloads (recommended): url/title/text/source
    - Legacy payloads (deprecated): content

    Legacy payload support will be removed in a future version. New clients should
    migrate to the structured payload format.
servers:
  - url: https://factlens.io
    description: Production
  - url: https://test-analyse-share-content-a7f6177425e6.herokuapp.com
    description: Test
paths:
  /api/share-content:
    post:
      summary: Submit shared content for analysis
      description: |
        Accepts either structured payload or legacy payload.

        Validation rule:
        - At least one of url, text, or content must be provided.
      operationId: shareContent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ShareContentStructuredRequest'
                - $ref: '#/components/schemas/ShareContentLegacyRequest'
            examples:
              structured:
                summary: Structured payload (recommended)
                value:
                  url: https://www.example.com/article
                  title: Example Article Title
                  text: Selected excerpt from the article.
                  source: ios_app
              legacy:
                summary: Legacy payload (deprecated)
                value:
                  content: https://www.example.com/article Check this out!
      responses:
        '200':
          description: Analysis request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareContentSuccessResponse'
              examples:
                accepted:
                  summary: Success response
                  value:
                    status: success
                    received_content: https://www.example.com/article\nSelected excerpt from the article.
                    url: https://factlens.io/550e8400-e29b-41d4-a716-446655440000
                    processing: true
                    received_payload:
                      url: https://www.example.com/article
                      title: Example Article Title
                      text: Selected excerpt from the article.
                      source: ios_app
        '400':
          description: Missing or invalid request content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                empty:
                  value:
                    status: error
                    message: No content, url, or text provided
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal:
                  value:
                    status: error
                    message: Internal server error
components:
  schemas:
    ShareContentStructuredRequest:
      type: object
      description: Preferred payload shape for new clients.
      additionalProperties: false
      properties:
        url:
          type: string
          description: Source URL to analyze.
          example: https://www.example.com/article
        title:
          type: string
          description: Optional title from the client.
          example: Example Article Title
        text:
          type: string
          description: Optional selected text or summary from client.
          example: Selected excerpt from the article.
        source:
          type: string
          description: Optional client identifier.
          enum: [ios_app, android_app, web_browser, legacy, unknown]
          default: unknown
      anyOf:
        - required: [url]
        - required: [text]

    ShareContentLegacyRequest:
      type: object
      description: |
        Deprecated payload shape kept for backward compatibility.

        Use ShareContentStructuredRequest for all new integrations.
      deprecated: true
      additionalProperties: false
      required: [content]
      properties:
        content:
          type: string
          description: |
            Legacy combined field that may contain URL and text together.
            Server normalizes this internally to url/title/text/source.
          example: https://www.example.com/article Check this out!

    ShareContentSuccessResponse:
      type: object
      required: [status, received_content, url, processing]
      properties:
        status:
          type: string
          enum: [success]
        received_content:
          type: string
          description: Normalized input used by backend processing.
        url:
          type: string
          format: uri
          description: URL to the generated analysis page.
        processing:
          type: boolean
          description: Always true when request is accepted for async processing.
        received_payload:
          type: object
          description: Normalized structured payload (present for accepted requests).
          required: [url, title, text, source]
          properties:
            url:
              type: string
            title:
              type: string
            text:
              type: string
            source:
              type: string
        enrichment:
          type: object
          additionalProperties: true
          description: Optional enrichment metadata if URL enrichment was applied.

    ErrorResponse:
      type: object
      required: [status, message]
      properties:
        status:
          type: string
          enum: [error]
        message:
          type: string
