openapi: 3.0.3
info:
  title: CiteFlow GEO API
  description: |
    CiteFlow provides Generative Engine Optimization (GEO) workflows and AI visibility audits.
    This API allows you to audit and optimize business visibility across AI-powered search tools.

    ## Capabilities
    - Run AI visibility audits for businesses
    - Check citation status across ChatGPT, Perplexity, and Google AI Overviews
    - Get GEO optimization recommendations

    ## Base URL
    https://citeflow.ma

  version: 1.0.0
  contact:
    email: hello@citeflow.ma
  license:
    name: Proprietary

servers:
  - url: https://citeflow.ma
    description: CiteFlow production

paths:
  /api/audit:
    post:
      operationId: runAudit
      summary: Run an AI visibility audit
      description: Submit a company name to run a free GEO audit across ChatGPT, Perplexity, and Google AI Overviews. Returns a visibility score (0-100) and gap analysis.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_name]
              properties:
                company_name:
                  type: string
                  description: Name of the company to audit
                  example: "Royal Mansour Marrakech"
                website_url:
                  type: string
                  description: Optional website URL for additional context
                  example: "https://royalmansour.com"
                email:
                  type: string
                  description: Optional email to receive the full audit report
                  example: "contact@royalmansour.com"
      responses:
        '200':
          description: Audit initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string

  /api/blog/posts:
    get:
      operationId: listBlogPosts
      summary: List blog posts
      description: Returns all published GEO blog posts.
      parameters:
        - name: lang
          in: query
          required: false
          schema:
            type: string
            enum: [fr, ar, en]
          description: Filter by language
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: Maximum posts to return
      responses:
        '200':
          description: List of blog posts
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    slug:
                      type: string
                    language:
                      type: string

  /api/indexnow/ping:
    post:
      operationId: pingIndexNow
      summary: Trigger IndexNow ping for content updates
      description: Notify search engines (Bing, Yandex, etc.) that content has been updated so they re-crawl. Requires admin API key.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: integer
                  description: Client ID to ping URLs for
                urls:
                  type: array
                  items:
                    type: string
                  description: Explicit URLs to ping (bypasses client lookup)
      responses:
        '200':
          description: Ping results

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key