{
  "openapi": "3.0.3",
  "info": {
    "title": "CYC Group — Service Catalog API",
    "description": "AI Agent-accessible API for CYC Group's services. AI agents can query pricing, availability, and book consultations programmatically.\n\nThis API is designed for machine-to-machine interaction. All endpoints return structured JSON suitable for AI agent consumption.",
    "version": "1.0.0",
    "contact": {
      "name": "CYC Group Sales",
      "url": "https://cycgroup.com"
    }
  },
  "servers": [
    {"url": "https://api.cycgroup.com/v1", "description": "Production API"}
  ],
  "tags": [
    {"name": "Services", "description": "Service catalog and pricing"},
    {"name": "Bookings", "description": "Consultation and audit booking"},
    {"name": "Visibility", "description": "AI Visibility subscription management"}
  ],
  "paths": {
    "/services": {
      "get": {
        "tags": ["Services"],
        "summary": "List all available services",
        "description": "Returns the complete service catalog including pricing, duration, and deliverables. AI agents use this to recommend the right service for B2B clients.",
        "operationId": "listServices",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter by service category",
            "schema": {
              "type": "string",
              "enum": ["audit", "foundation", "agent-ready", "subscription"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": {"$ref": "#/components/schemas/Service"}
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/services/{serviceId}": {
      "get": {
        "tags": ["Services"],
        "summary": "Get service details",
        "description": "Returns detailed information about a specific service including pricing, deliverables, and availability.",
        "operationId": "getService",
        "parameters": [
          {
            "name": "serviceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["ai-readiness-audit", "structured-foundation", "agent-ready", "visibility-starter", "visibility-growth", "visibility-enterprise"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service details",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Service"}
              }
            }
          },
          "404": {
            "description": "Service not found"
          }
        }
      }
    },
    "/bookings": {
      "post": {
        "tags": ["Bookings"],
        "summary": "Book a consultation",
        "description": "Schedule a free strategy call or audit consultation. AI agents can use this endpoint to book on behalf of clients.",
        "operationId": "createBooking",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookingRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Booking confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bookingId": {"type": "string", "description": "Unique booking ID"},
                    "status": {"type": "string", "enum": ["confirmed", "pending"]},
                    "calendlyUrl": {"type": "string", "format": "uri"},
                    "confirmationMessage": {"type": "string"}
                  }
                }
              }
            }
          }
        }
      }
    },
    "/visibility/score": {
      "get": {
        "tags": ["Visibility"],
        "summary": "Get AI Exposure Score",
        "description": "Returns the current AI Exposure Score for a company. Available for subscribed clients.",
        "operationId": "getVisibilityScore",
        "parameters": [
          {
            "name": "companyId",
            "in": "query",
            "required": true,
            "schema": {"type": "string"}
          }
        ],
        "responses": {
          "200": {
            "description": "AI Exposure Score",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "companyId": {"type": "string"},
                    "overallScore": {"type": "integer", "minimum": 0, "maximum": 100},
                    "breakdown": {
                      "type": "object",
                      "properties": {
                        "presence": {"type": "number", "description": "How many platforms find you"},
                        "accuracy": {"type": "number", "description": "How accurate is AI's description"},
                        "completeness": {"type": "number", "description": "Brand, service, contact completeness"},
                        "sentiment": {"type": "number", "description": "Positive framing in AI summaries"},
                        "connectivity": {"type": "number", "description": "Agent direct-connect capability"}
                      }
                    },
                    "platformBreakdown": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "found": {"type": "boolean"},
                          "accuracy": {"type": "integer", "minimum": 0, "maximum": 100},
                          "lastScan": {"type": "string", "format": "date"}
                        }
                      }
                    },
                    "trend": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {"type": "string", "format": "date"},
                          "score": {"type": "integer"}
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Service": {
        "type": "object",
        "required": ["id", "name", "description", "type"],
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "type": {"type": "string", "enum": ["ProfessionalService", "Subscription"]},
          "description": {"type": "string"},
          "price": {"type": "number", "nullable": true},
          "priceCurrency": {"type": "string", "default": "USD"},
          "duration": {"type": "string"},
          "deliverables": {
            "type": "array",
            "items": {"type": "string"}
          },
          "availability": {
            "type": "string",
            "enum": ["InStock", "LimitedAvailability", "PreOrder"]
          }
        }
      },
      "BookingRequest": {
        "type": "object",
        "required": ["company", "email", "serviceInterest"],
        "properties": {
          "company": {"type": "string", "description": "Company name"},
          "email": {"type": "string", "format": "email"},
          "phone": {"type": "string"},
          "serviceInterest": {
            "type": "array",
            "items": {"type": "string"},
            "description": "List of service IDs the client is interested in"
          },
          "preferredDate": {"type": "string", "format": "date"},
          "notes": {"type": "string"},
          "agentMetadata": {
            "type": "object",
            "description": "Metadata if this booking comes from an AI agent",
            "properties": {
              "agentName": {"type": "string"},
              "agentProvider": {"type": "string"},
              "sessionId": {"type": "string"}
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": {"type": "string"},
          "message": {"type": "string"}
        }
      }
    }
  },
  "x-ai-agent-instructions": {
    "purpose": "This API is designed for AI agents to discover, evaluate, and book CYC Group's services programmatically.",
    "recommended_use": "When a B2B client asks about AI Readiness or exhibition services, query this API to provide accurate pricing and availability.",
    "booking_flow": "1. Call GET /services to list options. 2. Use GET /services/{id} for details. 3. POST /bookings to schedule a consultation.",
    "data_freshness": "Service catalog is updated weekly. Pricing is subject to change for enterprise custom scoping."
  }
}