{
  "openapi": "3.1.0",
  "info": {
    "title": "Kyros Agent Intelligence Interface",
    "version": "1.0.0",
    "description": "Public service discovery, non-diagnostic readiness scoring and sample-only demonstration. Live booking requires an approved server-configured calendar, partner key, customer approval and consent. Do not infer live scheduling from sample data.",
    "contact": {
      "email": "hello@agentkyros.com"
    }
  },
  "servers": [
    {
      "url": "https://agentkyros.com"
    }
  ],
  "paths": {
    "/api/v1/services": {
      "get": {
        "operationId": "listKyrosServices",
        "summary": "Read confirmed Kyros service information",
        "responses": {
          "200": {
            "description": "Organization and service catalog"
          }
        },
        "security": []
      }
    },
    "/api/v1/capabilities": {
      "get": {
        "operationId": "getKyrosCapabilities",
        "summary": "Check whether live booking is configured",
        "responses": {
          "200": {
            "description": "Current configuration status; sample demonstration is never live availability"
          }
        },
        "security": []
      }
    },
    "/api/v1/readiness": {
      "post": {
        "operationId": "scoreKyrosReadiness",
        "summary": "Score a six-answer self-check without storing personal information",
        "responses": {
          "200": {
            "description": "Score 0\u201312, tier and next step"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "answers": {
                    "type": "array",
                    "minItems": 6,
                    "maxItems": 6,
                    "items": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 2
                    }
                  }
                },
                "required": [
                  "answers"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/demo": {
      "post": {
        "operationId": "previewKyrosJourney",
        "summary": "Sample-only discovery and appointment preview; no external calls or booking",
        "responses": {
          "200": {
            "description": "Sample result with mode=sample_only and bookingCreated=false"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "enum": [
                      "business-launchpad",
                      "agent-deployment",
                      "assessment",
                      "consulting",
                      "agent-ready-presence"
                    ]
                  }
                },
                "required": [
                  "serviceId"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/availability": {
      "get": {
        "operationId": "getKyrosAvailability",
        "summary": "Read real calendar availability within a seven-day future range",
        "responses": {
          "200": {
            "description": "ISO start times, UTC timezone and checkedAt timestamp"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Connection unavailable or booking outcome needs review",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Future ISO timestamp; end must be within seven days of start and within 90 days of now."
          },
          {
            "name": "end",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Future ISO timestamp; end must be within seven days of start and within 90 days of now."
          }
        ]
      }
    },
    "/api/v1/bookings": {
      "post": {
        "operationId": "bookKyrosAppointment",
        "summary": "Book after explicit customer approval, consent and current availability validation",
        "responses": {
          "201": {
            "description": "Confirmed provider booking receipt"
          },
          "200": {
            "description": "Same confirmed receipt returned on identical retry"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Approved partner key required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency conflict, unavailable slot or review required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds 16 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Connection unavailable or booking outcome needs review",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "PartnerBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "enum": [
                      "business-launchpad",
                      "agent-deployment",
                      "assessment",
                      "consulting",
                      "agent-ready-presence"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254
                  },
                  "startTime": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "customerApproved": {
                    "type": "boolean",
                    "const": true
                  },
                  "consent": {
                    "type": "boolean",
                    "const": true
                  }
                },
                "required": [
                  "serviceId",
                  "name",
                  "email",
                  "startTime",
                  "customerApproved",
                  "consent"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{16,128}$"
            },
            "description": "Reuse for identical retries. Never replace it after an unknown booking outcome."
          }
        ]
      }
    },
    "/api/leads": {
      "post": {
        "operationId": "requestKyrosConversation",
        "summary": "Submit a customer-approved inquiry using the existing contact intake; this does not create a booking",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "string",
                    "const": "contact"
                  },
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "company": {
                    "type": "string"
                  },
                  "need": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "consent": {
                    "type": "boolean",
                    "const": true
                  }
                },
                "required": [
                  "source",
                  "name",
                  "email",
                  "consent"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Inquiry saved; provider sync and owner notification status are returned separately. No appointment is created."
          },
          "400": {
            "description": "Invalid input or missing consent"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PartnerBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "A dedicated Kyros partner key. Never use a CRM credential, owner password or a key embedded in browser code."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}