AI Recommendability API

Authentication

Send your API key on every request using either header:

• Authorization: Bearer YOUR_API_KEY
• X-Api-Key: YOUR_API_KEY

Free tier: 5 assessments per calendar month, partial report. Paid tiers unlock full reports (including AI Recommendability side-by-side) and higher limits.

Competitor-aware flow (recommended)

The same 3-step flow the wizard uses, programmatic:

1. (Optional) POST /assessment/suggest-competitors with {"companyName": "...", "location": "..."} → get AI-suggested competitors. Use this to pre-fill the wizard, or skip and supply your own.
2. POST /api/v1/assess with the subject business + a competitorConfig block (see below) → receive jobId
3. Poll GET /api/v1/jobs/:jobId every few seconds until status is completed or failed
4. Fetch report: GET /api/v1/reports/:assessmentId for the full or partial report JSON

competitorConfig schema

Pass this in the assess request body to define the two (or three) competitors your audit compares against:

{
  "count": 2,
  "assessmentDepth": "full",
  "suppliedCompetitors": [
    { "name": "Competitor A", "location": "Portland, OR", "website": "https://a.example" },
    { "name": "Competitor B", "location": "Portland, OR", "website": "https://b.example" }
  ]
}

• count — 1, 2 (default), or 3
• assessmentDepth — "shallow" (sample) or "full" (paid)
• suppliedCompetitors — array of competitor records. If omitted, the report runs against the subject business only and AI Recommendability will not include the side-by-side competitor sub-score.

Suggest competitors (pre-flight)

Use this endpoint to ask the same AI the wizard uses. Returns up to 2-3 suggested competitors in the subject's market with source attribution (LLM vs Google search fallback).

POST /assessment/suggest-competitors
{
  "companyName": "Acme Pools",
  "location": "Austin, TX"
}

→ 200 OK
{
  "competitors": [
    { "name": "BlueWave Pools", "footprintUrl": "...", "source": "llm" },
    { "name": "Sunset Pool Co", "footprintUrl": "...", "source": "search-fallback" }
  ],
  "source": "mixed",
  "debugNotes": ["gemini returned 2; search filled 0"]
}

Endpoints

• POST /api/v1/assess — Enqueue an assessment job
• GET /api/v1/jobs/:jobId — Get job status
• GET /api/v1/reports/:assessmentId — Get report by ID
• GET /api/v1/reports — List reports (query params: limit, offset)
• POST /assessment/suggest-competitors — Pre-flight: AI-suggested competitors