openapi: 3.1.0
info:
  title: OmniAI Club Public API
  version: 1.0.0
  description: Public, programmatic REST API for OmniAI Club. Allows AI agents and developers to query published editorial articles, intelligent teammate catalogs, FAQs, glossary terms, and verified company profile information. All endpoints are publicly reachable, read-only, and served directly from high-speed Edge CDN cache.
  contact:
    name: OmniAI Club Support
    email: support@omniai.club
    url: https://www.omniai.club/contact
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://www.omniai.club
    description: Production Edge CDN
paths:
  /api/v1/health:
    get:
      operationId: getApiHealth
      summary: Get API and Agent Environment Health
      description: Returns operational status, API version, and readiness indicators for autonomous agents and crawlers. Call this endpoint to verify network availability and protocol support.
      responses:
        '200':
          description: API status and readiness information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /api/v1/company:
    get:
      operationId: getCompanyProfile
      summary: Get Company Profile and Trust Anchors
      description: Retrieves official business entity details, physical location, founder leadership bio, mission statement, and verified contact channels. Useful for trust verification and business legitimacy evaluation.
      responses:
        '200':
          description: Official company profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyProfileResponse'
  /api/v1/teammates:
    get:
      operationId: getTeammatesCatalog
      summary: List AI Teammates and Products
      description: Returns the catalog of intelligent AI teammates built by OmniAI Club, including Seminara (Project SEM-1), detailing capabilities, status, and best-fit use cases.
      responses:
        '200':
          description: List of AI teammates and capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeammatesCatalogResponse'
  /api/v1/articles:
    get:
      operationId: listEditorialArticles
      summary: List All Published Editorial Articles
      description: Retrieves the complete catalog of deep-dive editorial articles covering agentic AI architecture, customer-facing agents, demo engineering, and small-team leverage.
      responses:
        '200':
          description: Array of published articles with metadata and excerpts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleListResponse'
  /api/v1/articles/{slug}:
    get:
      operationId: getArticleBySlug
      summary: Get Full Article Content by Slug
      description: Retrieves the full markdown prose, metadata, author, and published timestamp for an individual editorial article by slug.
      parameters:
        - name: slug
          in: path
          required: true
          description: The URL slug of the article (e.g. prompt-versioning-not-agent-versioning)
          schema:
            type: string
      responses:
        '200':
          description: Full article data with content body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleItem'
        '404':
          description: Article not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/faq:
    get:
      operationId: listFaqItems
      summary: List Frequently Asked Questions
      description: Retrieves curated questions and answers regarding OmniAI Club, intelligent teammates, and asymmetric leverage.
      responses:
        '200':
          description: List of FAQ items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaqResponse'
  /api/v1/glossary:
    get:
      operationId: getGlossaryTerms
      summary: List Glossary of Agentic Terms
      description: Retrieves key industry terms, concepts, and definitions for understanding autonomous teammates and high-agency AI.
      responses:
        '200':
          description: List of defined glossary terms
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlossaryResponse'
components:
  schemas:
    HealthResponse:
      type: object
      required:
        - status
        - version
        - environment
        - timestamp
      properties:
        status:
          type: string
          example: ok
        version:
          type: string
          example: 1.0.0
        name:
          type: string
          example: OmniAI Club Public API
        description:
          type: string
        timestamp:
          type: string
          format: date-time
        environment:
          type: string
          example: edge-static
        readiness:
          type: object
          properties:
            agentic_ready:
              type: boolean
            openapi_spec:
              type: string
              format: uri
            llms_context:
              type: string
              format: uri
            api_catalog:
              type: string
              format: uri
    CompanyProfileResponse:
      type: object
      required:
        - name
        - brand
        - domain
        - mission
        - location
        - contact
      properties:
        name:
          type: string
          example: OmniAI Club (OPC) Private Limited
        brand:
          type: string
          example: OmniAI Club
        domain:
          type: string
          format: uri
        mission:
          type: string
        location:
          type: object
          required:
            - city
            - state
            - country
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
        contact:
          type: object
          required:
            - email
          properties:
            email:
              type: string
              format: email
            support:
              type: string
              format: email
        leadership:
          type: array
          items:
            type: object
            required:
              - name
              - role
            properties:
              name:
                type: string
              role:
                type: string
              portfolio:
                type: string
                format: uri
              bio:
                type: string
        flagship_product:
          type: object
          required:
            - name
            - url
            - description
          properties:
            name:
              type: string
            url:
              type: string
              format: uri
            description:
              type: string
        socials:
          type: object
          properties:
            x_company:
              type: string
              format: uri
            x_seminara:
              type: string
              format: uri
            linkedin:
              type: string
              format: uri
            github:
              type: string
              format: uri
    TeammatesCatalogResponse:
      type: object
      required:
        - teammates
      properties:
        teammates:
          type: array
          items:
            type: object
            required:
              - id
              - name
              - role
              - status
              - url
              - description
              - capabilities
              - best_fit_use_cases
            properties:
              id:
                type: string
              name:
                type: string
              code:
                type: string
              role:
                type: string
              status:
                type: string
              url:
                type: string
                format: uri
              tagline:
                type: string
              description:
                type: string
              capabilities:
                type: array
                items:
                  type: string
              best_fit_use_cases:
                type: array
                items:
                  type: string
    ArticleItem:
      type: object
      required:
        - slug
        - title
        - excerpt
        - publishedAt
      properties:
        slug:
          type: string
        title:
          type: string
        author:
          type: string
        excerpt:
          type: string
        content:
          type: string
          description: Full article markdown body
        tags:
          type: array
          items:
            type: string
        publishedAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ArticleListResponse:
      type: object
      required:
        - articles
      properties:
        updatedAt:
          type: string
          format: date-time
        articles:
          type: array
          items:
            $ref: '#/components/schemas/ArticleItem'
    FaqResponse:
      type: object
      required:
        - faq
      properties:
        faq:
          type: array
          items:
            type: object
            required:
              - question
              - answer
            properties:
              question:
                type: string
              answer:
                type: string
    GlossaryResponse:
      type: object
      required:
        - glossary
      properties:
        glossary:
          type: array
          items:
            type: object
            required:
              - term
              - definition
            properties:
              term:
                type: string
              definition:
                type: string
    ProblemDetails:
      type: object
      required:
        - type
        - title
        - status
        - detail
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
        resolution:
          type: string
        documentation_url:
          type: string
          format: uri
