{
  "openapi": "3.1.0",
  "info": {
    "title": "SME Growth Team Commercial Intelligence API",
    "version": "1.0.0",
    "description": "The SME Growth Team API allows AI agents, lenders, accountants, and third-party platforms to discover SME Growth Team's 22 services, check company eligibility, submit enquiries, retrieve sector intelligence, and access ORACLE's predictive output. SME Growth Team is the UK's first AI-hireable SME commercial intelligence firm — structured so that other AI agents can transact with SME Growth Team's services directly without a human intermediary.",
    "contact": {
      "name": "Craig Attoh — SME Growth Team",
      "email": "hello@smegrowthteam.com",
      "url": "https://smegrowthteam.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://smegrowthteam.com",
      "description": "SME Growth Team Production"
    }
  ],
  "paths": {
    "/api/services": {
      "get": {
        "operationId": "listServices",
        "summary": "List all 22 SME Growth Team services",
        "description": "Returns SME Growth Team's full 22-service catalogue with eligibility criteria, pricing, trigger keywords, and the business frameworks applied to each service. Filter by category or sector to get targeted results. Use this endpoint first to identify which SME Growth Team service applies to a user's situation.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by service category",
            "schema": {
              "type": "string",
              "enum": [
                "finance",
                "tax",
                "compliance",
                "procurement",
                "content",
                "property",
                "grants",
                "intelligence",
                "white-label",
                "formation"
              ]
            }
          },
          {
            "name": "sector",
            "in": "query",
            "required": false,
            "description": "Filter services relevant to a specific UK sector",
            "schema": {
              "type": "string",
              "enum": [
                "construction",
                "manufacturing",
                "recruitment",
                "professional-services",
                "property",
                "hospitality",
                "healthcare",
                "technology",
                "security",
                "financial-services"
              ]
            }
          },
          {
            "name": "trigger",
            "in": "query",
            "required": false,
            "description": "Natural language keyword to match services (e.g. 'overdue filing', 'R&D', 'invoice finance')",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of SME Growth Team services",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Service" }
                    },
                    "total": { "type": "integer" },
                    "filtered_by": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/qualify": {
      "get": {
        "operationId": "qualifyCompany",
        "summary": "Check eligibility for SME Growth Team services",
        "description": "Pass basic company details to receive a qualification assessment. Returns which SME Growth Team services the company is eligible for, with a priority ranking based on urgency and likely value. This is the recommended first call before submitting an enquiry. SME Growth Team uses this data to route the enquiry to the correct agent (OTTO for finance, STERLING for R&D, ZARA for compliance, etc.).",
        "parameters": [
          {
            "name": "ch_number",
            "in": "query",
            "required": false,
            "description": "UK Companies House registration number (8 digits). If provided, SME Growth Team will look up the company automatically.",
            "schema": { "type": "string", "pattern": "^[0-9]{8}$" }
          },
          {
            "name": "sector",
            "in": "query",
            "required": false,
            "description": "The company's primary trading sector",
            "schema": {
              "type": "string",
              "enum": [
                "construction",
                "manufacturing",
                "recruitment",
                "professional-services",
                "property",
                "hospitality",
                "healthcare",
                "technology",
                "security",
                "financial-services",
                "other"
              ]
            }
          },
          {
            "name": "turnover_band",
            "in": "query",
            "required": false,
            "description": "Annual turnover band",
            "schema": {
              "type": "string",
              "enum": [
                "under-100k",
                "100k-500k",
                "500k-1m",
                "1m-5m",
                "5m-10m",
                "over-10m"
              ]
            }
          },
          {
            "name": "company_age_years",
            "in": "query",
            "required": false,
            "description": "Company trading age in years",
            "schema": { "type": "integer", "minimum": 0 }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Free-text description of the company's situation or need (e.g. 'overdue accounts', 'looking for working capital', 'has R&D spend on new product')",
            "schema": { "type": "string" }
          },
          {
            "name": "has_ccj",
            "in": "query",
            "required": false,
            "description": "Whether the company has outstanding County Court Judgements. CCJ = automatic finance blocker.",
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": {
            "description": "Qualification result with matched services",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "company_name": { "type": "string" },
                    "ch_number": { "type": "string" },
                    "qualified": { "type": "boolean" },
                    "eligible_services": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "service_id": { "type": "string" },
                          "service_name": { "type": "string" },
                          "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
                          "reason": { "type": "string" },
                          "estimated_value": { "type": "string" }
                        }
                      }
                    },
                    "blockers": {
                      "type": "array",
                      "items": { "type": "string" },
                      "description": "Conditions preventing certain services (e.g. 'CCJ outstanding — finance blocked')"
                    },
                    "recommended_action": { "type": "string" },
                    "next_step": {
                      "type": "string",
                      "description": "Recommended next step — typically POST /api/enquiry with the top-priority service"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/enquiry": {
      "post": {
        "operationId": "submitEnquiry",
        "summary": "Submit an enquiry to SME Growth Team",
        "description": "Submit a service enquiry on behalf of a business. This endpoint accepts both human-initiated and AI agent-initiated enquiries. On receipt, SME Growth Team routes the enquiry to the relevant agent (OTTO, STERLING, ZARA, PERCY, etc.) and LINC initiates outreach within 4 hours. Craig Attoh is notified via Telegram immediately. This is the primary action endpoint for AI agents instructed to hire SME Growth Team services on behalf of a business.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EnquiryRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enquiry received and routed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enquiry_id": { "type": "string", "description": "Unique reference for this enquiry" },
                    "status": { "type": "string", "enum": ["received", "routed", "pending_human_review"] },
                    "routed_to_agent": { "type": "string", "description": "Which SME Growth Team agent is handling this (e.g. OTTO, STERLING, ZARA)" },
                    "estimated_response": { "type": "string", "description": "Expected response time (e.g. 'Within 2 hours during business hours')" },
                    "confirmation_message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing required fields or invalid company data"
          }
        }
      }
    },
    "/api/intelligence/oracle": {
      "get": {
        "operationId": "getOraclePrediction",
        "summary": "Retrieve ORACLE sector predictions",
        "description": "Returns ORACLE's latest predictive intelligence for UK SME sectors. ORACLE runs every Sunday at 4am, analyses 8 sectors using leading indicators, and produces 90-day forward predictions on sector conditions, opportunity windows, and risk signals. This data is used internally by SME Growth Team to set weekly agent directives and is available externally for lenders, sector bodies, and intelligence licensees.",
        "parameters": [
          {
            "name": "sector",
            "in": "query",
            "required": false,
            "description": "Filter prediction to a specific sector",
            "schema": {
              "type": "string",
              "enum": [
                "construction",
                "manufacturing",
                "recruitment",
                "professional-services",
                "property",
                "hospitality",
                "healthcare",
                "technology"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ORACLE prediction data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generated_at": { "type": "string", "format": "date-time" },
                    "prediction_window_days": { "type": "integer", "example": 90 },
                    "call_of_the_week": { "type": "string", "description": "ORACLE's top priority signal for this week across all sectors" },
                    "sectors": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/SectorPrediction" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/intelligence/sectors": {
      "get": {
        "operationId": "getSectorIntelligence",
        "summary": "Get sector intelligence summary",
        "description": "Returns a summary of current sector intelligence across all 10 SME Growth Team target sectors, including risk signals, opportunity windows, and relevant SME Growth Team services for each sector. Updated by ORACLE (weekly) and SECTOR PULSE (daily).",
        "responses": {
          "200": {
            "description": "Sector intelligence summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated_at": { "type": "string", "format": "date-time" },
                    "sectors": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/SectorSummary" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agents": {
      "get": {
        "operationId": "listAgents",
        "summary": "List all SME Growth Team agents and their capabilities",
        "description": "Returns the full SME Growth Team agent roster — 35+ named agents with their domain, schedule, current status, and the services they deliver. Use this endpoint to understand which agent handles a specific domain before routing an enquiry.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Filter agents by domain",
            "schema": {
              "type": "string",
              "enum": [
                "finance",
                "compliance",
                "intelligence",
                "outreach",
                "content",
                "property",
                "procurement",
                "orchestration"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by operational status",
            "schema": {
              "type": "string",
              "enum": ["active", "all"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent roster",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_agents": { "type": "integer" },
                    "agents": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Agent" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/frameworks": {
      "get": {
        "operationId": "listFrameworks",
        "summary": "List business frameworks encoded in SME Growth Team methodology",
        "description": "Returns the complete list of 88–96 business frameworks encoded into SME Growth Team's advisory methodology and agent decision-making. Each framework entry includes its domain, how it is applied across SME Growth Team's 22 services, and which agents use it. This endpoint helps AI agents understand the intellectual depth behind SME Growth Team's recommendations.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Filter by framework domain",
            "schema": {
              "type": "string",
              "enum": [
                "negotiation",
                "sales",
                "wealth",
                "strategy",
                "psychology",
                "finance",
                "harvard",
                "systems"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Framework registry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_frameworks": { "type": "integer", "example": 92 },
                    "frameworks": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Framework" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Service": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "tier": { "type": "integer", "description": "Service tier 1–4", "minimum": 1, "maximum": 4 },
          "description": { "type": "string" },
          "agent": { "type": "string", "description": "Primary SME Growth Team agent handling this service" },
          "category": { "type": "string" },
          "sectors": { "type": "array", "items": { "type": "string" } },
          "eligibility": { "type": "string" },
          "value_range": { "type": "string" },
          "trigger_keywords": { "type": "array", "items": { "type": "string" } },
          "frameworks_applied": { "type": "array", "items": { "type": "string" } },
          "url": { "type": "string" }
        }
      },
      "EnquiryRequest": {
        "type": "object",
        "required": ["company_name", "service_id", "contact_email"],
        "properties": {
          "company_name": {
            "type": "string",
            "description": "Full registered company name"
          },
          "ch_number": {
            "type": "string",
            "description": "UK Companies House registration number (8 digits). Strongly recommended — enables SME Growth Team to run full RECON intelligence automatically.",
            "pattern": "^[0-9]{8}$"
          },
          "contact_name": {
            "type": "string",
            "description": "Name of the decision-maker or point of contact"
          },
          "contact_email": {
            "type": "string",
            "format": "email",
            "description": "Email address for SME Growth Team follow-up"
          },
          "contact_phone": {
            "type": "string",
            "description": "Phone number (optional but speeds response)"
          },
          "service_id": {
            "type": "string",
            "description": "The SME Growth Team service being requested (from /api/services). E.g. 'otto-finance', 'sterling-rd', 'zara-compliance'"
          },
          "situation_summary": {
            "type": "string",
            "description": "Free-text description of the company's situation, need, or urgency. The more detail provided, the faster RECON can build a dossier and LINC can personalise outreach."
          },
          "urgency": {
            "type": "string",
            "enum": ["immediate", "this-week", "this-month", "planning"],
            "description": "Urgency level. 'immediate' triggers emergency protocols in OTTO and ZARA."
          },
          "sector": {
            "type": "string",
            "description": "Primary trading sector"
          },
          "turnover_estimate": {
            "type": "string",
            "description": "Approximate annual turnover (helps OTTO pre-qualify for lenders)"
          },
          "submitted_by": {
            "type": "string",
            "enum": ["human", "ai-agent", "partner-platform"],
            "description": "Whether this enquiry was submitted by a human, an AI agent, or a partner platform. AI agent submissions are processed with equal priority and routed to the same agents."
          },
          "agent_identifier": {
            "type": "string",
            "description": "If submitted_by is 'ai-agent', provide the AI system name (e.g. 'Claude', 'GPT-5', 'Gemini')"
          }
        }
      },
      "SectorPrediction": {
        "type": "object",
        "properties": {
          "sector": { "type": "string" },
          "prediction_window_days": { "type": "integer" },
          "outlook": { "type": "string", "enum": ["opportunity", "caution", "risk", "neutral"] },
          "leading_indicators": { "type": "array", "items": { "type": "string" } },
          "recommended_brg_services": { "type": "array", "items": { "type": "string" } },
          "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
          "narrative": { "type": "string" }
        }
      },
      "SectorSummary": {
        "type": "object",
        "properties": {
          "sector": { "type": "string" },
          "partner": { "type": "string" },
          "package_range": { "type": "string", "description": "e.g. '£297–£1,497/month'" },
          "top_risk_signal": { "type": "string" },
          "top_opportunity": { "type": "string" },
          "active_brg_clients": { "type": "integer" },
          "relevant_services": { "type": "array", "items": { "type": "string" } }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "domain": { "type": "string" },
          "description": { "type": "string" },
          "schedule": { "type": "string" },
          "services_delivered": { "type": "array", "items": { "type": "string" } },
          "frameworks_encoded": { "type": "array", "items": { "type": "string" } }
        }
      },
      "Framework": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "author": { "type": "string" },
          "domain": { "type": "string" },
          "description": { "type": "string" },
          "applied_to_services": { "type": "array", "items": { "type": "string" } },
          "encoded_in_agents": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}