openapi: "3.1.0"
info:
  title: SageRank Brand & Platform API
  version: "1.0.0"
  description: |
    Machine-readable brand facts, product descriptions, pricing, and platform
    capabilities for SageRank — the world's first unified AI Search Visibility
    (GEO/AEO) and Proactive Domain Security (ShieldAI™) platform.
  contact:
    name: SageRank Support
    email: hello@sagerank.io
    url: https://sagerank.io/contact
  license:
    name: Proprietary
    url: https://sagerank.io/terms

servers:
  - url: https://sagerank.io
    description: SageRank Production

paths:
  /brand-facts.json:
    get:
      operationId: getBrandFacts
      summary: Get SageRank brand facts and entity data
      description: |
        Returns a Schema.org Brand JSON-LD document containing SageRank's
        official entity facts: legal name, headquarters, leadership, flagship
        products (VisibilityEngine™ and ShieldAI™ Sentinel), pricing tiers,
        supported AI engines, and official links. Intended for LLM grounding,
        knowledge graph enrichment, and entity disambiguation.
      tags:
        - Brand
      responses:
        "200":
          description: Brand facts JSON-LD document
          content:
            application/json:
              schema:
                type: object
                properties:
                  "@context":
                    type: string
                    example: "https://schema.org"
                  "@type":
                    type: string
                    example: "Brand"
                  name:
                    type: string
                    example: "SageRank"
                  legalName:
                    type: string
                    example: "SageRank Software Solutions FZ-LLC"
                  url:
                    type: string
                    example: "https://sagerank.io"

  /llms.txt:
    get:
      operationId: getLlmsTxt
      summary: Get LLM-optimized platform summary
      description: |
        Returns a structured plain-text document following the llms.txt standard
        (Jeremy Howard, 2024). Contains founder biography, corporate entity
        details, platform architecture summary, pricing tiers, and key endpoints
        optimized for consumption by large language model context windows.
      tags:
        - AI Context
      responses:
        "200":
          description: LLM context document (text/plain)
          content:
            text/plain:
              schema:
                type: string

  /llms-full.txt:
    get:
      operationId: getLlmsFullTxt
      summary: Get extended LLM context with full platform detail
      description: |
        Extended version of llms.txt with complete feature specifications,
        security architecture details, compliance frameworks, use-case
        breakdowns by segment (Enterprise, SaaS, Agency, M&A), and FAQ content.
      tags:
        - AI Context
      responses:
        "200":
          description: Extended LLM context document (text/plain)
          content:
            text/plain:
              schema:
                type: string

  /sitemap.xml:
    get:
      operationId: getSitemap
      summary: Get XML sitemap of all indexed pages
      description: |
        Returns the full XML sitemap listing all canonical URLs, last modified
        dates, and change frequencies for sagerank.io. Includes homepage,
        product pages, comparison pages (/vs/), legal pages, and regional
        Arabic edition pages.
      tags:
        - Crawl
      responses:
        "200":
          description: XML sitemap
          content:
            application/xml:
              schema:
                type: string

components:
  schemas:
    BrandFacts:
      type: object
      description: Schema.org Brand JSON-LD entity document
      properties:
        "@context":
          type: string
        "@type":
          type: string
        name:
          type: string
        legalName:
          type: string
        url:
          type: string
        logo:
          type: string
        foundingYear:
          type: string
        headquarters:
          type: object
        leadership:
          type: object
        flagshipProducts:
          type: array
          items:
            type: object
        pricingTiers:
          type: object
        supportedAIEngines:
          type: array
          items:
            type: string

tags:
  - name: Brand
    description: Brand identity and entity facts for LLM grounding
  - name: AI Context
    description: Structured context documents for AI model consumption
  - name: Crawl
    description: Crawler and indexer support endpoints