openapi: 3.1.0
info:
  title: BRealm Agent-Readable API
  version: "1.0.0"
  description: |
    Public, machine-readable surface of brealm.com for AI agents and crawlers.

    Documents two categories of endpoints:

    1. **Static JSON endpoints under `/ai/`** — canonical context, products,
       pricing, capabilities, FAQ, and changelog. Cacheable, GET-only, no auth.
    2. **Form-based action endpoints** — existing PHP form handlers an agent
       can POST to in order to request consultations or contact a human.

    For human-readable orientation, see https://www.brealm.com/agent-guide.html
    For high-signal company summary, see https://www.brealm.com/llms.txt
  contact:
    name: BRealm
    email: info@brealm.com
    url: https://www.brealm.com
  license:
    name: Proprietary
servers:
  - url: https://www.brealm.com
    description: Production

tags:
  - name: discovery
    description: Static JSON endpoints describing the company and platform
  - name: forms
    description: Action endpoints (form-based) an agent can submit on behalf of a user

paths:
  /ai/context.json:
    get:
      tags: [discovery]
      summary: Company identity and canonical entrypoints
      responses:
        "200":
          description: Company context
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AIContext"

  /ai/products.json:
    get:
      tags: [discovery]
      summary: Service and product catalog
      responses:
        "200":
          description: Service catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  services:
                    type: array
                    items:
                      $ref: "#/components/schemas/Service"

  /ai/pricing.json:
    get:
      tags: [discovery]
      summary: Indicative pricing for AI servers, agents, custom dev, automation, cloud
      responses:
        "200":
          description: Pricing tiers and add-ons
          content:
            application/json:
              schema:
                type: object

  /ai/capabilities.json:
    get:
      tags: [discovery]
      summary: Platform capabilities, supported models, tech stack, industries
      responses:
        "200":
          description: Capabilities map
          content:
            application/json:
              schema:
                type: object

  /ai/faq.json:
    get:
      tags: [discovery]
      summary: FAQ in machine-readable form
      responses:
        "200":
          description: FAQ list
          content:
            application/json:
              schema:
                type: object

  /ai/changelog.json:
    get:
      tags: [discovery]
      summary: Recent product, AI, and company changes
      responses:
        "200":
          description: Changelog entries
          content:
            application/json:
              schema:
                type: object

  /contact.html:
    post:
      tags: [forms]
      summary: Submit a consultation / contact request
      description: |
        Submits a contact / consultation request to BRealm sales.
        This is the form behind https://www.brealm.com/contact.html
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/ContactForm"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/ContactForm"
      responses:
        "200":
          description: Submission accepted
          content:
            text/html:
              schema:
                type: string

components:
  schemas:
    AIContext:
      type: object
      properties:
        site: { type: string, example: "brealm.com" }
        name: { type: string }
        tagline: { type: string }
        summary: { type: string }
        url: { type: string, format: uri }
        languages:
          type: array
          items: { type: string }
        operations:
          type: array
          items: { type: object }
        subOrganizations:
          type: array
          items: { type: object }
        contact: { type: object }
        endpoints: { type: object }
        actions:
          type: array
          items: { type: object }

    Service:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        category:
          type: string
          enum: [private_ai_infrastructure, custom_dev, ai_agents, ai_orchestration, ai_observability, ai_integration, ai_smb, migration, automation, cloud, data, consulting, vertical_solution]
        url: { type: string, format: uri }
        shortDescription: { type: string }
        longDescription: { type: string }
        deploymentOptions:
          type: array
          items: { type: string }
        supportedModels:
          type: array
          items: { type: string }
        targetCustomers:
          type: array
          items: { type: string }
        integrations:
          type: array
          items: { type: string }

    ContactForm:
      type: object
      required: [name, email, message]
      properties:
        name: { type: string }
        email: { type: string, format: email }
        phone: { type: string }
        company: { type: string }
        country: { type: string }
        interest:
          type: string
          enum: [private_ai, ai_agents, custom_software, automation, cloud_migration, consulting, other]
        message: { type: string }
