openapi: 3.0.0
info:
  title: Paul Woodhouse Agentic Advisory API
  description: Machine-readable interface for GEO consulting and agentic commerce services.
  version: 1.0.0
  contact:
    name: Paul Woodhouse
    url: https://paulwoodhouse.com
    email: mr@paulwoodhouse.com
servers:
  - url: https://paulwoodhouse.com/api/v1
    description: Production server

paths:
  /manifest:
    get:
      operationId: getKnowledgeGraph
      summary: Retrieve the Knowledge Graph Manifest
      description: Returns the full JSON-LD entity definition for Paul Woodhouse Advisory, including Organization, Person, and Service schemas.
      tags:
        - Discovery
      responses:
        '200':
          description: A JSON-LD object defining the organization and services.
          content:
            application/ld+json:
              schema:
                type: object
                properties:
                  "@context":
                    type: string
                    example: https://schema.org
                  "@graph":
                    type: array
                    items:
                      type: object

  /quote:
    post:
      operationId: submitConsultingInquiry
      summary: Initiate an Agentic Consultation Inquiry
      description: Accepts a SeekAction object to begin a machine-led consulting request. Returns structured acknowledgment with reference ID.
      tags:
        - Actions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
            examples:
              strategy:
                summary: SOSTAC® Strategic Planning Inquiry
                value:
                  query: "Optimize my Shopify store for Gemini and ChatGPT discovery"
                  agentName: "John Smith"
                  agentEmail: "john@example.com"
              audit:
                summary: GEO Readiness / Entity Architecture Audit
                value:
                  query: "Audit my site for AI agent readiness"
                  agentName: "Jane Doe"
      responses:
        '201':
          description: Intent captured and structured for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          description: Invalid request - missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /availability:
    get:
      operationId: getAvailability
      summary: Check Consultant Availability
      description: Returns real-time availability for advisory sprints and audits.
      tags:
        - Scheduling
      parameters:
        - name: service
          in: query
          description: Filter availability by service type
          schema:
            type: string
            enum:
              - audit
              - strategy
              - implementation
        - name: weeks
          in: query
          description: Number of weeks to look ahead
          schema:
            type: integer
            default: 4
            minimum: 1
            maximum: 12
      responses:
        '200':
          description: Available slots in ISO 8601 format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityResponse'

components:
  schemas:
    QuoteRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The raw human intent or business objective.
          example: "Optimize my Shopify store for Gemini"
        agentName:
          type: string
          description: Name of the person or agent making the request.
          example: "John Smith"
        agentEmail:
          type: string
          format: email
          description: Contact email for follow-up.
          example: "john@example.com"
        context:
          type: object
          properties:
            platform:
              type: string
              description: Relevant platform if applicable.
              example: "Shopify"
            urgency:
              type: string
              enum: [low, medium, high]
              default: medium
            budget:
              type: string
              description: Budget range if known.
              example: "$15,000 - $50,000"

    QuoteResponse:
      type: object
      properties:
        status:
          type: string
          enum: [received, processing, error]
          example: received
        seekAction:
          $ref: '#/components/schemas/SeekAction'
        acknowledgment:
          type: object
          properties:
            message:
              type: string
              example: "Your agentic inquiry has been captured and structured."
            expectedResponseTime:
              type: string
              example: "24-48 hours"
            referenceId:
              type: string
              example: "PW-ABC123XYZ"
        enrichedData:
          type: object
          properties:
            detectedEntities:
              type: array
              items:
                type: string
              example: ["Shopify (SoftwareApplication)", "Gemini (SoftwareApplication)"]
            suggestedServices:
              type: array
              items:
                type: string
              example: ["SOSTAC® Strategic Planning", "GEO Readiness / Entity Architecture"]

    SeekAction:
      type: object
      description: Schema.org SeekAction representing captured intent.
      properties:
        "@context":
          type: string
          example: https://schema.org
        "@type":
          type: string
          example: SeekAction
        agent:
          type: object
          properties:
            "@type":
              type: string
              example: Person
            name:
              type: string
              example: "John Smith"
            email:
              type: string
              example: "john@example.com"
        query:
          type: string
          example: "Optimize my Shopify store for Gemini"
        object:
          type: object
          properties:
            "@type":
              type: string
              example: Thing
            name:
              type: string
              example: "Consulting Inquiry"
        actionStatus:
          type: string
          example: "http://schema.org/ActiveActionStatus"
        startTime:
          type: string
          format: date-time

    AvailabilityResponse:
      type: object
      properties:
        consultant:
          type: string
          example: "Paul Woodhouse"
        timezone:
          type: string
          example: "America/New_York"
        slots:
          type: array
          items:
            type: object
            properties:
              start:
                type: string
                format: date-time
              end:
                type: string
                format: date-time
              service:
                type: string
                example: "strategy"
              available:
                type: boolean

    ErrorResponse:
      type: object
      properties:
        "@context":
          type: string
          example: https://schema.org
        "@type":
          type: string
          example: Error
        description:
          type: string
          example: "Invalid request: 'query' field is required"
        actionStatus:
          type: string
          example: "http://schema.org/FailedActionStatus"

tags:
  - name: Discovery
    description: Entity and knowledge graph endpoints
  - name: Actions
    description: Agentic transaction endpoints
  - name: Scheduling
    description: Availability and booking endpoints