{ "openapi": "3.1.0", "info": { "title": "Kyros Agent Intelligence Interface", "version": "1.1.0", "description": "Kyros public service discovery for Business Launchpad, forward-deployed AI engineering and related services. Readiness scoring and sample-only demonstration are public. Live booking requires an approved server-configured calendar, partner key, customer approval and consent. Do not infer live scheduling from sample data. A2A 1.0 JSON-RPC discovery is at /.well-known/agent-card.json and /a2a; see /developers. Breaking REST changes use a new major URL. Deprecated interfaces will advertise Deprecation and Sunset headers before removal.", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceCatalog" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } } } }, "security": [] } }, "/api/v1/readiness": { "post": { "operationId": "scoreKyrosReadiness", "summary": "Score a six-answer self-check without storing personal information", "responses": { "200": { "description": "Score 0\u201310, tier and next step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Demo" } } } }, "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", "forward-deployed-ai" ] } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "200": { "description": "Same confirmed receipt returned on identical retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "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", "forward-deployed-ai" ] }, "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadReceipt" } } } }, "400": { "description": "Invalid input or missing consent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadError" } } } } } } }, "/api/v1/answers": { "get": { "operationId": "answerKyrosQuestion", "summary": "Retrieve published answers with sources", "security": [], "responses": { "200": { "description": "Public information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedAnswers" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } } ] } }, "/api/v1/quote-preview": { "post": { "operationId": "previewKyrosPricing", "summary": "Return pricing guidance only; never a binding quote", "security": [], "responses": { "200": { "description": "Public information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingGuidance" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "string", "enum": [ "business-launchpad", "forward-deployed-ai", "agent-deployment", "assessment", "consulting", "agent-ready-presence" ] } }, "required": ["serviceId"] } } } } } } }, "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"] }, "Service": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "pricing": { "type": "string" } }, "required": ["id", "name", "summary", "url", "pricing"] }, "ServiceCatalog": { "type": "object", "properties": { "organization": { "type": "string" }, "approach": { "type": "string" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } }, "required": ["organization", "approach", "services"] }, "Capabilities": { "type": "object", "properties": { "version": { "type": "string" }, "booking": { "enum": ["configured", "not_configured"] }, "serviceDiscovery": { "type": "boolean" }, "readinessScoring": { "type": "boolean" }, "demo": { "const": "sample_only" }, "documentation": { "type": "string", "format": "uri" }, "a2a": { "type": "object", "properties": { "protocolVersion": { "type": "string" }, "binding": { "type": "string" }, "agentCard": { "type": "string", "format": "uri" }, "endpoint": { "type": "string", "format": "uri" }, "mode": { "type": "string" } }, "required": [ "protocolVersion", "binding", "agentCard", "endpoint", "mode" ] }, "questions": { "type": "string" }, "quotes": { "type": "string" }, "bookingRequires": { "type": "array", "items": { "type": "string" } } }, "required": [ "version", "booking", "serviceDiscovery", "readinessScoring", "demo", "documentation", "a2a", "questions", "quotes", "bookingRequires" ] }, "Readiness": { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 10 }, "maximum": { "const": 10 }, "tier": { "enum": ["Foundational", "Emerging", "Ready to Scale"] }, "interpretation": { "type": "string" }, "nextStep": { "type": "string", "format": "uri" } }, "required": ["score", "maximum", "tier", "interpretation", "nextStep"] }, "Demo": { "type": "object", "properties": { "mode": { "const": "sample_only" }, "noSideEffects": { "type": "boolean" }, "service": { "type": "string" }, "source": { "type": "string", "format": "uri" }, "nextStep": { "type": "string" }, "sampleBooking": { "type": "object", "properties": { "startTime": { "type": "string", "format": "date-time" }, "status": { "const": "preview_only_not_booked" } }, "required": ["startTime", "status"] }, "bookingCreated": { "const": false } }, "required": [ "mode", "noSideEffects", "service", "source", "nextStep", "sampleBooking", "bookingCreated" ] }, "Availability": { "type": "object", "properties": { "timezone": { "type": "string" }, "starts": { "type": "array", "items": { "type": "string", "format": "date-time" } }, "checkedAt": { "type": "string", "format": "date-time" }, "note": { "type": "string" } }, "required": ["timezone", "starts", "checkedAt", "note"] }, "Booking": { "type": "object", "properties": { "status": { "const": "confirmed" }, "bookingId": { "type": "string" }, "startTime": { "type": "string", "format": "date-time" }, "serviceId": { "type": "string" } }, "required": ["status", "bookingId", "startTime", "serviceId"] }, "PublishedAnswers": { "type": "object", "properties": { "mode": { "const": "published_answers" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" }, "source": { "type": "string", "format": "uri" } }, "required": ["question", "answer", "source"] } }, "fallback": { "type": "string" }, "contact": { "type": "string", "format": "uri" } }, "required": ["mode", "answers", "fallback", "contact"] }, "PricingGuidance": { "type": "object", "properties": { "mode": { "const": "pricing_guidance_only" }, "bindingQuote": { "const": false }, "serviceId": { "type": "string" }, "service": { "type": "string" }, "pricing": { "type": "string" }, "publishedPrice": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount", "currency", "basis"] }, "source": { "type": "string", "format": "uri" }, "scopeQuestions": { "type": "array", "items": { "type": "string" } }, "nextStep": { "type": "string", "format": "uri" }, "note": { "type": "string" } }, "required": [ "mode", "bindingQuote", "serviceId", "service", "pricing", "source", "scopeQuestions", "nextStep", "note" ] }, "LeadReceipt": { "type": "object", "properties": { "success": { "const": true }, "pdfDelivery": { "type": "string" }, "ghlSync": { "type": "string" }, "emailNotification": { "type": "string" } }, "required": ["success", "ghlSync", "emailNotification"] }, "LeadError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } }, "externalDocs": { "description": "Kyros developer guide and A2A quickstart", "url": "https://agentkyros.com/developers" } }