KSM Model™ Assessment API

API Documentation

Overview

Run the full KSM assessment (scan + scoring + AI narrative) via a single authenticated HTTP call. The API returns the same JSON payload the in-app report consumes, including scores, grades, maturity levels, pillar breakdowns, and AI-generated narrative with a 90-day roadmap.

Endpoint

POST https://ksm-model.lovable.app/api/public/ksm/audit

Use https://project--f82ce3bc-2e17-4ecc-9a98-7a861a1579fc.lovable.app if you need a stable URL that survives renames.

Authentication

Send your API key as a Bearer token in the Authorization header:

Authorization: Bearer <KSM_API_KEY>

Keep KSM_API_KEY server-side. Anyone with this key can run assessments (which call paid AI models).

Request

Content-Type: application/json

{
  "company": "Acme Inc.",
  "url": "https://acme.com",
  "advanced": {
    "industry": "B2B SaaS",
    "market": "US",
    "competitors": "competitor-a.com, competitor-b.com"
  }
}

Field	Type	Required	Notes
`company`	string	yes	1–200 chars
`url`	string	yes	1–500 chars; bare domains accepted
`advanced.industry`	string	no	1–200 chars
`advanced.market`	enum	no	`"US"` \| `"Global"` \| `"Regional"`
`advanced.competitors`	string	no	1–500 chars, comma-separated

Response

200 OK

{
  "scanId": "uuid",
  "payload": {
    "company": "Acme Inc.",
    "url": "acme.com",
    "overall": 72.4,
    "grade": "B",
    "maturity": { "name": "Operational" },
    "pillars": [
      { "score": 78.0, "name": "Structured Extractability", "tag": "SE" }
    ],
    "narrative": "…",
    "brand": {
      "primaryColor": "#…",
      "headingFont": "…",
      "bodyFont": "…"
    }
  }
}

Error codes

Status	Meaning
`400`	Invalid JSON or input validation failed
`401`	Missing or invalid Bearer token
`405`	Method not allowed (only POST is supported)
`500`	Assessment pipeline failed

Example (cURL)

curl -X POST https://ksm-model.lovable.app/api/public/ksm/audit \
  -H "Authorization: Bearer $KSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"Acme Inc.","url":"https://acme.com"}'

A full assessment typically takes 20–60 seconds (live crawl + Claude narrative generation).

Response payload fields

Field	Type	Description
`scanId`	string	Unique identifier for this assessment run
`payload.company`	string	Company name as provided
`payload.url`	string	Normalized domain
`payload.overall`	number	Overall KSM score (0–100)
`payload.grade`	string	Letter grade (A–F)
`payload.maturity.name`	string	Maturity stage name
`payload.pillars`	array	Three pillar scores with names and tags
`payload.narrative`	string	AI-generated narrative and 90-day roadmap
`payload.brand`	object	Detected brand colors and fonts (if available)