{
  "schema_version": "0.1",
  "name": "Heartwood",
  "description": "AI-powered IT Decision Briefs for mid-market and SMB leaders. Coaches a question for clarity, runs a two-pass reviewer, and returns a board-ready seven-section Decision Brief. Built by Seven Roots Consulting.",
  "provider": {
    "organization": "Seven Roots Consulting",
    "url": "https://sevenrootsconsulting.com"
  },
  "homepage": "https://heartwood.sevenrootsconsulting.com/",
  "documentation": "https://heartwood.sevenrootsconsulting.com/api/docs",
  "methodology": "https://heartwood.sevenrootsconsulting.com/methodology",
  "contact": "panel@sevenrootsconsulting.com",
  "authentication": {
    "type": "bearer",
    "scheme": "Authorization: Bearer hwk_<secret>",
    "description": "API keys are issued from the Heartwood account dashboard. The secret is shown once at creation and stored only as a SHA-256 hash server-side. Keys carry scopes ('score_prompt', 'brief') and a tier that sets the rate limit.",
    "key_prefix": "hwk_"
  },
  "rate_limits": {
    "standard": "60 requests/minute per key",
    "agent": "600 requests/minute per key",
    "headers": ["X-RateLimit-Limit", "X-RateLimit-Remaining", "Retry-After"]
  },
  "endpoints": [
    {
      "name": "score_prompt",
      "method": "POST",
      "url": "https://heartwood.sevenrootsconsulting.com/api/v1/score-prompt",
      "scope": "score_prompt",
      "description": "Scores how well-formed an IT decision question is before generating a brief. Returns a 0-100 score, per-dimension breakdown, the missing elements, a coaching note, and an optional rewrite.",
      "request": {
        "question": "string (required, 10-2000 chars)",
        "context": "string (optional)"
      },
      "response": {
        "score": "integer 0-100",
        "tier": "Basic | Developing | Good | Advisor-Ready",
        "dimension_scores": "object",
        "missing_elements": "string[]",
        "coaching_note": "string",
        "rewrite": "string (only when score < 70)"
      },
      "price": {
        "amount": 0.10,
        "currency": "USD",
        "unit": "per call",
        "free_quota": "25 calls per calendar month per org, then billed"
      }
    },
    {
      "name": "brief",
      "method": "POST",
      "url": "https://heartwood.sevenrootsconsulting.com/api/v1/brief",
      "scope": "brief",
      "description": "Generates a board-ready seven-section Decision Brief as structured JSON. Includes a confidence score, prompt-quality score, and a human_escalation_hint when the question needs hands-on advisory.",
      "request": {
        "question": "string (required, 10-2000 chars)",
        "context": "string (optional)",
        "industry": "string (optional)",
        "revenue_band": "string (optional)",
        "urgency": "string (optional)",
        "depth": "string (optional)"
      },
      "response": {
        "brief_id": "uuid",
        "bottom_line": "string",
        "your_situation": "string",
        "decision_statement": "string",
        "business_exposure": "string",
        "the_panels_assessment": "string",
        "options": "array",
        "recommendation": "object",
        "risks": "array",
        "thirty_sixty_ninety": "array",
        "confidence_score": "integer 0-100",
        "prompt_quality_score": "integer 0-100",
        "cited_sources": "array",
        "human_escalation_hint": "{ flag: boolean, reason?: string }",
        "signature_block": "{ author, methodology_version, methodology_url, model, generated_at }",
        "disclaimer": "string"
      },
      "price": {
        "amount": 25.00,
        "currency": "USD",
        "unit": "per call",
        "free_quota": "1 call per calendar month per org, then billed",
        "note": "Standard brief. Deep Research brief priced at $99 per call is planned, not yet available."
      }
    },
    {
      "name": "audit_log",
      "method": "GET",
      "url": "https://heartwood.sevenrootsconsulting.com/api/v1/audit-log",
      "scope": "score_prompt | brief",
      "description": "Returns the calling org's per-call usage log, newest first. Pagination via ?limit (default 50, max 200) and ?offset (default 0). Each row reports endpoint, product, model_version, a prompt_hash fingerprint (never the raw question), brief_id, created_at, and a billable flag.",
      "request": {
        "limit": "integer (optional, default 50, max 200, query param)",
        "offset": "integer (optional, default 0, query param)"
      },
      "response": {
        "usage": "array of { brief_id, created_at, endpoint, product, model_version, prompt_hash, billable }",
        "limit": "integer",
        "offset": "integer"
      }
    }
  ],
  "pricing": {
    "model": "free monthly quota per org per product, then pay-as-you-go via Stripe metered usage",
    "free_quota": {
      "score_prompt": "25 calls per calendar month",
      "brief": "1 call per calendar month"
    },
    "per_call": {
      "score_prompt": { "amount": 0.10, "currency": "USD" },
      "brief_standard": { "amount": 25.00, "currency": "USD" },
      "brief_deep": { "amount": 99.00, "currency": "USD", "status": "planned, not yet available" }
    },
    "over_quota_behavior": "If billing is enabled for the org, the call succeeds and one metered usage unit is reported. If billing is not enabled, the call returns HTTP 402 with a message and a link to enable billing at https://heartwood.sevenrootsconsulting.com/account/api-keys.",
    "quota_reset": "Start of each calendar month (UTC)."
  },
  "pricing_note": "Pay-as-you-go, anchored to human pricing. Each org gets a free monthly allowance per product; beyond it, usage is billed by Stripe metered prices. Over-quota calls without billing enabled return HTTP 402.",
  "sla": {
    "availability_target": "99.5%",
    "typical_latency": "score_prompt < 5s, brief < 30s"
  }
}