{
  "openapi": "3.1.0",
  "info": {
    "title": "Supergood Solutions public API",
    "version": "1.2.0",
    "summary": "Public reads of the rate card, service list and blog (paginated), NLWeb /ask search over the blog, the fit-check POST with Idempotency-Key, and a sandbox that sends nothing.",
    "description": "The fit check is POST https://api.supergood.solutions/api/v1/intake. Two GET documents, /pricing.json and /services.json, are static files on https://supergood.solutions. No API key, bearer token, or account is required. See https://supergood.solutions/auth.md.\n\nIdempotency. POST /api/v1/intake accepts an Idempotency-Key header (1 to 200 printable characters, no spaces). A retry with the same key and the same body within 24 hours does not send a second email. The same key with a different body is 422 idempotency_conflict. Without the header, each POST sends one email.\n\nSandbox. POST /api/v1/sandbox/intake takes the same body, runs the same validation and sends nothing.\n\nRate limits. Every intake response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. A 429 adds Retry-After. /api/v1/intake allows 10 requests per 10 minutes per IP and /api/v1/sandbox/intake allows 30. The limit is kept in memory per server instance, so treat it as approximate.\n\nVersioning. The API is version 1 and every intake response carries API-Version: 1. This document is 1.1.0. 1.1.0 added the Idempotency-Key header, the sandbox, the RateLimit headers and the JSON 404, and removed nothing. The unversioned paths /api/intake and /api/sandbox/intake are aliases of the v1 paths and keep working. A breaking change ships as a new path, for example /api/v2/intake. The old path keeps working for at least 90 days after the change is announced on https://supergood.solutions/developers/ and in this description, and during those 90 days it returns Deprecation and Sunset headers. Adding a response field or an optional request field is not a breaking change. pricing.json and services.json are unpaged and cannot send Sunset or Deprecation headers (GitHub Pages), so a change to them is announced on the developers page.\n\nThe same fit check is the submit_fit_check tool on the MCP server at https://api.supergood.solutions/api/mcp (card: https://supergood.solutions/.well-known/mcp/server-card.json).\n\nDeprecation and Sunset. During a deprecation window the old path adds a Deprecation header and a Sunset header (an HTTP date). Neither is sent today because nothing is deprecated.",
    "contact": {
      "name": "Ryan Sandoval",
      "url": "https://supergood.solutions/start/",
      "email": "ryan@supergood.solutions"
    }
  },
  "servers": [
    {
      "url": "https://api.supergood.solutions",
      "description": "Intake API host. Fit check, sandbox, and the JSON index at GET /."
    },
    {
      "url": "https://api.supergood.solutions/api/v1/{environment}",
      "description": "Sandbox environment. GET returns a sandbox index and POST /intake here is POST /api/v1/sandbox/intake. Same validation as production, sends nothing, no live data touched.",
      "variables": {
        "environment": {
          "default": "sandbox",
          "enum": [
            "sandbox"
          ],
          "description": "The only environment served under this base path."
        }
      }
    },
    {
      "url": "https://supergood.solutions",
      "description": "Static JSON documents served by GitHub Pages."
    }
  ],
  "tags": [
    {
      "name": "reads",
      "description": "Side-effect free JSON documents."
    },
    {
      "name": "intake",
      "description": "Fit-check submission. Each accepted POST emails Ryan."
    },
    {
      "name": "sandbox",
      "description": "Same validation as the fit check. Sends nothing."
    },
    {
      "name": "search",
      "description": "Blog listing and question answering over the blog. Side-effect free."
    }
  ],
  "paths": {
    "/pricing.json": {
      "get": {
        "operationId": "getPricing",
        "tags": [
          "reads"
        ],
        "summary": "Read the published rate card.",
        "description": "Returns the same offers as https://supergood.solutions/pricing/ in one JSON document. No query parameters. Not paged. Safe to call. No auth.",
        "security": [],
        "responses": {
          "200": {
            "description": "The full rate card.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricingDocument"
                }
              }
            }
          }
        }
      },
      "servers": [
        {
          "url": "https://supergood.solutions",
          "description": "Static JSON documents served by GitHub Pages."
        }
      ]
    },
    "/services.json": {
      "get": {
        "operationId": "getServices",
        "tags": [
          "reads"
        ],
        "summary": "Read the published service list.",
        "description": "Returns the five public services in one JSON document. No query parameters. Not paged. Safe to call. No auth.",
        "security": [],
        "responses": {
          "200": {
            "description": "The full service list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServicesDocument"
                }
              }
            }
          }
        }
      },
      "servers": [
        {
          "url": "https://supergood.solutions",
          "description": "Static JSON documents served by GitHub Pages."
        }
      ]
    },
    "/": {
      "get": {
        "operationId": "getIntakeIndex",
        "tags": [
          "reads"
        ],
        "summary": "List the intake host's endpoints.",
        "description": "Returns a JSON index of the endpoints on the intake host. No side effects. No auth.",
        "security": [],
        "servers": [
          {
            "url": "https://api.supergood.solutions"
          }
        ],
        "responses": {
          "200": {
            "description": "The endpoint index.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntakeIndex"
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests from one IP in a minute. Retry-After gives the seconds to wait.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          }
        }
      },
      "servers": [
        {
          "url": "https://api.supergood.solutions",
          "description": "Intake API host."
        }
      ]
    },
    "/api/v1/intake": {
      "post": {
        "operationId": "submitFitCheck",
        "tags": [
          "intake"
        ],
        "summary": "Submit one fit-check inquiry.",
        "description": "Emails the inquiry to Ryan Sandoval. Send one request per person. Send an Idempotency-Key header so a retry cannot send a second email. No auth. Browser pages on https://supergood.solutions receive Access-Control-Allow-Origin for this URL. The form at /start/ will not submit until 3 seconds after the first field focus. A body with elapsedMs under 3000 or a filled company field returns 200 and sends no email, so do not treat elapsedMs as a server-side lock. Leave company as an empty string. Put the employer in companyName. To test without sending anything, use POST /api/v1/sandbox/intake.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FitCheckRequest"
              },
              "example": {
                "name": "Ada Lovelace",
                "email": "ada@example.com",
                "company": "",
                "companyName": "Example Co",
                "role": "Ops lead",
                "handoff": "A Monday report rebuilt by hand from three spreadsheets.",
                "currentState": "Entirely manual",
                "teamSize": "2-5",
                "timeline": "Next quarter",
                "budget": "$4k-$10k (one workflow)",
                "source": "supergood.solutions/start",
                "elapsedMs": 3000,
                "paysForTools": "Yes"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The inquiry was accepted. Ryan reads it and replies.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckAccepted"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            }
          },
          "400": {
            "description": "The body or the Idempotency-Key header was rejected. error is json when the body is not a JSON object, required when name, email, or handoff is missing, email when the address is not valid, paysForTools when the value is not Yes, Not sure, or No, and idempotency_key when the Idempotency-Key header is not 1 to 200 printable characters with no spaces. Read hint, fix the request, and send once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "examples": {
                  "required": {
                    "summary": "Missing required field",
                    "value": {
                      "ok": false,
                      "error": "required",
                      "message": "Name, email and handoff are required.",
                      "hint": "Include non-empty \"name\", \"email\" and \"handoff\" (the work you want handed off)."
                    }
                  },
                  "email": {
                    "summary": "Email did not parse",
                    "value": {
                      "ok": false,
                      "error": "email",
                      "message": "The email address does not look valid.",
                      "hint": "Use an address like you@company.com."
                    }
                  },
                  "idempotency_key": {
                    "summary": "Bad Idempotency-Key",
                    "value": {
                      "ok": false,
                      "error": "idempotency_key",
                      "message": "The Idempotency-Key header is not valid.",
                      "hint": "Send 1 to 200 printable ASCII characters with no spaces, such as a UUID, or leave the header out."
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            }
          },
          "403": {
            "description": "A browser request from an origin other than supergood.solutions. Call from a server, or use the form at /start/.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "example": {
                  "ok": false,
                  "error": "origin",
                  "message": "Browser requests from this origin are not allowed.",
                  "hint": "Submit from https://supergood.solutions/start/, or call the API from a server (no Origin header)."
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            }
          },
          "429": {
            "description": "More than 10 requests from one IP in 10 minutes. Retry-After gives the seconds to wait.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "example": {
                  "ok": false,
                  "error": "rate_limited",
                  "message": "Too many requests from this address.",
                  "hint": "Wait for the number of seconds in Retry-After and try again."
                }
              }
            }
          },
          "405": {
            "description": "The method was not POST. Send POST with Content-Type application/json. A GET to this URL returns this error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "example": {
                  "ok": false,
                  "error": "method",
                  "message": "This endpoint only accepts POST.",
                  "hint": "Send a POST request with a JSON body."
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Allow": {
                "description": "Allowed methods.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "POST"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "The endpoint is not configured. Try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            }
          },
          "502": {
            "description": "The email could not be delivered. Try again in a minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            }
          },
          "409": {
            "description": "A request with this Idempotency-Key is still being processed. Wait a few seconds and retry with the same key.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "example": {
                  "ok": false,
                  "error": "idempotency_in_progress",
                  "message": "A request with this Idempotency-Key is still being processed.",
                  "hint": "Wait a few seconds, then retry with the same key and body."
                }
              }
            }
          },
          "422": {
            "description": "This Idempotency-Key was already used with a different body. Use a new key for a different inquiry.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "example": {
                  "ok": false,
                  "error": "idempotency_conflict",
                  "message": "This Idempotency-Key was already used with a different request body.",
                  "hint": "Use a new Idempotency-Key for a different request, or resend the original body."
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      }
    },
    "/api/v1/sandbox/intake": {
      "post": {
        "operationId": "submitFitCheckSandbox",
        "tags": [
          "sandbox"
        ],
        "summary": "Validate a fit-check body. Sends nothing.",
        "description": "Runs the same validation as POST /api/v1/intake and returns 200 without sending an email. The spam traps are off, so a body is judged on its fields only. Use it to build and test a client. Each IP gets 30 requests per 10 minutes. Idempotency-Key is checked for format and has no other effect. No auth.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FitCheckRequest"
              },
              "example": {
                "name": "Ada Lovelace",
                "email": "ada@example.com",
                "company": "",
                "companyName": "Example Co",
                "role": "Ops lead",
                "handoff": "A Monday report rebuilt by hand from three spreadsheets.",
                "currentState": "Entirely manual",
                "teamSize": "2-5",
                "timeline": "Next quarter",
                "budget": "$4k-$10k (one workflow)",
                "source": "supergood.solutions/start",
                "elapsedMs": 3000,
                "paysForTools": "Yes"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The body is valid. No email was sent.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxAccepted"
                },
                "example": {
                  "ok": true,
                  "sandbox": true,
                  "message": "Valid. Sandbox: no email was sent."
                }
              }
            }
          },
          "400": {
            "description": "The body or the Idempotency-Key header was rejected. error is json when the body is not a JSON object, required when name, email, or handoff is missing, email when the address is not valid, paysForTools when the value is not Yes, Not sure, or No, and idempotency_key when the Idempotency-Key header is not 1 to 200 printable characters with no spaces. Read hint, fix the request, and send once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "examples": {
                  "required": {
                    "summary": "Missing required field",
                    "value": {
                      "ok": false,
                      "error": "required",
                      "message": "Name, email and handoff are required.",
                      "hint": "Include non-empty \"name\", \"email\" and \"handoff\" (the work you want handed off)."
                    }
                  },
                  "email": {
                    "summary": "Email did not parse",
                    "value": {
                      "ok": false,
                      "error": "email",
                      "message": "The email address does not look valid.",
                      "hint": "Use an address like you@company.com."
                    }
                  },
                  "idempotency_key": {
                    "summary": "Bad Idempotency-Key",
                    "value": {
                      "ok": false,
                      "error": "idempotency_key",
                      "message": "The Idempotency-Key header is not valid.",
                      "hint": "Send 1 to 200 printable ASCII characters with no spaces, such as a UUID, or leave the header out."
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            }
          },
          "403": {
            "description": "A browser request from an origin other than supergood.solutions. Call from a server, or use the form at /start/.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "example": {
                  "ok": false,
                  "error": "origin",
                  "message": "Browser requests from this origin are not allowed.",
                  "hint": "Submit from https://supergood.solutions/start/, or call the API from a server (no Origin header)."
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            }
          },
          "429": {
            "description": "More than 30 requests from one IP in 10 minutes. Retry-After gives the seconds to wait.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "example": {
                  "ok": false,
                  "error": "rate_limited",
                  "message": "Too many requests from this address.",
                  "hint": "Wait for the number of seconds in Retry-After and try again."
                }
              }
            }
          },
          "405": {
            "description": "The method was not POST. Send POST with Content-Type application/json. A GET to this URL returns this error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                },
                "example": {
                  "ok": false,
                  "error": "method",
                  "message": "This endpoint only accepts POST.",
                  "hint": "Send a POST request with a JSON body."
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Allow": {
                "description": "Allowed methods.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "POST"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      },
      "servers": [
        {
          "url": "https://api.supergood.solutions",
          "description": "Sandbox path on the intake host."
        }
      ]
    },
    "/api/v1/posts": {
      "get": {
        "operationId": "listPosts",
        "tags": [
          "search"
        ],
        "summary": "List blog posts, newest first, one page at a time.",
        "description": "Cursor pagination. Send limit (1-50, default 20). For the next page send the next_cursor value from the previous page as cursor. next_cursor is null on the last page, and a Link header with rel=\"next\" carries the same URL. No side effects. No auth.",
        "security": [],
        "servers": [
          {
            "url": "https://api.supergood.solutions"
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size, 1 to 50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque next_cursor from the previous page. Omit for the first page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of posts.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Link": {
                "description": "RFC 8288 link to the next page, rel=\"next\". Absent on the last page.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostPage"
                }
              }
            }
          },
          "400": {
            "description": "limit out of range or cursor not valid.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          },
          "405": {
            "description": "Only GET and HEAD are served.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests from one IP in a minute.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          },
          "502": {
            "description": "The blog index could not be read.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          }
        }
      }
    },
    "/ask": {
      "get": {
        "operationId": "askQuestionGet",
        "tags": [
          "search"
        ],
        "summary": "Ask a question and get the blog posts that answer it (NLWeb 0.55, GET).",
        "description": "NLWeb /ask in list mode. Send exactly one of query or q. Add streaming=true, or Accept: text/event-stream, for SSE. No side effects. No auth.",
        "security": [],
        "servers": [
          {
            "url": "https://api.supergood.solutions"
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "The question, 2 to 500 characters. Send this or q.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 500
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Alias of query.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 500
            }
          },
          {
            "name": "top_k",
            "in": "query",
            "required": false,
            "description": "How many posts to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 5
            }
          },
          {
            "name": "streaming",
            "in": "query",
            "required": false,
            "description": "true returns text/event-stream.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "site",
            "in": "query",
            "required": false,
            "description": "Optional. Only supergood.solutions is answered.",
            "schema": {
              "type": "string",
              "enum": [
                "supergood.solutions"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching posts. JSON by default; Server-Sent Events (start, result per post, complete) when streaming is requested.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AskResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "event: start, then event: result once per post (data is an AskResult plus query_id), then event: complete."
                }
              }
            }
          },
          "400": {
            "description": "Missing or too-long question, both query and q sent, a site other than supergood.solutions, or invalid JSON.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 questions from one IP in a minute.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          },
          "502": {
            "description": "The blog index could not be read.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "askQuestion",
        "tags": [
          "search"
        ],
        "summary": "Ask a question and get the blog posts that answer it (NLWeb 0.55).",
        "description": "NLWeb /ask in list mode with the structured 0.55 body. Set prefer.streaming to true, or send Accept: text/event-stream, for SSE. No side effects. No auth.",
        "security": [],
        "servers": [
          {
            "url": "https://api.supergood.solutions"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AskRequest"
              },
              "example": {
                "query": {
                  "text": "How should I add guardrails to an agent in production?"
                },
                "top_k": 3,
                "meta": {
                  "version": "0.55"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matching posts. JSON by default; Server-Sent Events (start, result per post, complete) when streaming is requested.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AskResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "event: start, then event: result once per post (data is an AskResult plus query_id), then event: complete."
                }
              }
            }
          },
          "400": {
            "description": "Missing or too-long question, both query and q sent, a site other than supergood.solutions, or invalid JSON.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          },
          "429": {
            "description": "More than 60 questions from one IP in a minute.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          },
          "502": {
            "description": "The blog index could not be read.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "API-Version": {
                "$ref": "#/components/headers/APIVersion"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitCheckError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PricingDocument": {
        "type": "object",
        "description": "The published rate card. Same offers as https://supergood.solutions/pricing/. Served as a static file.",
        "additionalProperties": false,
        "required": [
          "provider",
          "url",
          "currency",
          "updated",
          "offers",
          "tooling"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "description": "Name of the business that publishes the rate card."
          },
          "url": {
            "type": "string",
            "description": "Human-readable pricing page this document mirrors.",
            "format": "uri"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code for the numeric prices."
          },
          "updated": {
            "type": "string",
            "description": "Calendar date the document was last edited, YYYY-MM-DD.",
            "format": "date"
          },
          "offers": {
            "type": "array",
            "description": "Every offer, in the order published on the pricing page.",
            "items": {
              "$ref": "#/components/schemas/Offer"
            },
            "minItems": 1
          },
          "tooling": {
            "type": "string",
            "description": "Who pays for software, APIs and seats. Plain-language statement, not a price."
          }
        }
      },
      "Offer": {
        "type": "object",
        "description": "One priced offer. An offer carries price (fixed) or priceFrom (starting price), not both. Gain-share and credit fields appear only on the offers they apply to.",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "unit",
          "summary"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable machine identifier, for example fit-check, sidekick-session, setup-sprint, sidekick-monthly, quick-scan or build."
          },
          "name": {
            "type": "string",
            "description": "Display name of the offer."
          },
          "price": {
            "type": "number",
            "description": "Fixed price in currency. Present when the offer has a single price.",
            "minimum": 0
          },
          "priceFrom": {
            "type": "number",
            "description": "Lowest published price in currency. The quoted price can be higher.",
            "minimum": 0
          },
          "unit": {
            "type": "string",
            "description": "What the price is charged per, for example one-time, workflow or month."
          },
          "summary": {
            "type": "string",
            "description": "One or two sentences describing the offer and its terms."
          },
          "url": {
            "type": "string",
            "description": "Page where the offer starts, when it has one.",
            "format": "uri"
          },
          "creditedTowardBuildIfSignedWithinDays": {
            "type": "integer",
            "description": "Days after the Quick Scan within which signing a build credits the Quick Scan fee toward it.",
            "minimum": 0
          },
          "gainSharePercent": {
            "$ref": "#/components/schemas/Range",
            "description": "Share of measured gain over an agreed baseline, as a percentage range."
          },
          "gainShareCapMultiple": {
            "type": "number",
            "description": "Gain share is capped at this multiple of the monthly retainer.",
            "minimum": 0
          },
          "minimumMonths": {
            "type": "integer",
            "description": "Minimum commitment in months.",
            "minimum": 0
          }
        }
      },
      "Range": {
        "type": "object",
        "description": "An inclusive numeric range.",
        "additionalProperties": false,
        "required": [
          "min",
          "max"
        ],
        "properties": {
          "min": {
            "type": "number",
            "description": "Lower bound, inclusive."
          },
          "max": {
            "type": "number",
            "description": "Upper bound, inclusive."
          }
        }
      },
      "ServicesDocument": {
        "type": "object",
        "description": "The published service list. Five service pages with a one-line summary each. Served as a static file.",
        "additionalProperties": false,
        "required": [
          "provider",
          "url",
          "updated",
          "services"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "description": "Name of the business that publishes the service list."
          },
          "url": {
            "type": "string",
            "description": "Page that introduces the services this document lists.",
            "format": "uri"
          },
          "updated": {
            "type": "string",
            "description": "Calendar date the document was last edited, YYYY-MM-DD.",
            "format": "date"
          },
          "services": {
            "type": "array",
            "description": "Every public service page. Not paged.",
            "items": {
              "$ref": "#/components/schemas/Service"
            },
            "minItems": 1
          }
        }
      },
      "Service": {
        "type": "object",
        "description": "One public service page.",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "url",
          "summary"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable machine identifier, the page slug."
          },
          "name": {
            "type": "string",
            "description": "Display name of the service."
          },
          "url": {
            "type": "string",
            "description": "Canonical page for the service.",
            "format": "uri"
          },
          "summary": {
            "type": "string",
            "description": "One-line description of the service."
          }
        }
      },
      "FitCheckRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "email",
          "handoff"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Person to reply to."
          },
          "email": {
            "type": "string",
            "minLength": 1,
            "format": "email",
            "description": "Email Ryan should reply to."
          },
          "handoff": {
            "type": "string",
            "minLength": 1,
            "description": "The manual work they want off the team's plate, in their words."
          },
          "paysForTools": {
            "type": "string",
            "enum": [
              "Yes",
              "Not sure",
              "No"
            ],
            "description": "Are you OK paying for the software and tools your workflows run on, on your own accounts? The form and the MCP tool require it. The endpoint accepts a request without it."
          },
          "company": {
            "type": "string",
            "const": "",
            "description": "Honeypot. Send an empty string. The employer name goes in companyName."
          },
          "companyName": {
            "type": "string",
            "description": "Employer. Optional."
          },
          "role": {
            "type": "string",
            "description": "Job title. Optional."
          },
          "currentState": {
            "type": "string",
            "enum": [
              "",
              "Entirely manual",
              "Spreadsheets and a few Zaps",
              "A pilot that stalled",
              "Running, but we don't trust it",
              "Not sure yet"
            ],
            "description": "Where the work sits today. Optional. Empty string if unknown."
          },
          "teamSize": {
            "type": "string",
            "enum": [
              "",
              "Just me",
              "2-5",
              "6-20",
              "20+"
            ],
            "description": "How many people touch the work. Optional."
          },
          "timeline": {
            "type": "string",
            "enum": [
              "",
              "Just exploring",
              "Next quarter",
              "Now, it's blocking us"
            ],
            "description": "When they want to move. Optional."
          },
          "budget": {
            "type": "string",
            "enum": [
              "",
              "Under $4k (Quick Scan only)",
              "$4k-$10k (one workflow)",
              "$10k+ (multiple workflows)",
              "Not sure yet"
            ],
            "description": "Rough budget. Optional."
          },
          "source": {
            "type": "string",
            "description": "Where the request came from. The form sends supergood.solutions/start. The in-page tool sends supergood.solutions/webmcp."
          },
          "elapsedMs": {
            "type": "integer",
            "minimum": 0,
            "description": "Milliseconds since the person started the form. The function drops a value under 3000: it answers 200 and sends no email."
          }
        }
      },
      "FitCheckAccepted": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true,
            "description": "Always true on success."
          }
        },
        "description": "The inquiry was accepted. Also returned, with no email sent, when the form's spam checks drop it."
      },
      "FitCheckError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "error",
          "message",
          "hint"
        ],
        "description": "Every error from the API host (api.supergood.solutions). error is a stable code, message says what went wrong, hint says how to fix it.",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false,
            "description": "Always false on an error."
          },
          "error": {
            "type": "string",
            "enum": [
              "method",
              "origin",
              "not_found",
              "json",
              "required",
              "email",
              "paysForTools",
              "idempotency_key",
              "idempotency_conflict",
              "idempotency_in_progress",
              "rate_limited",
              "server",
              "send",
              "method_get",
              "method_ask",
              "cursor",
              "limit",
              "query",
              "site",
              "upstream"
            ],
            "description": "Stable error code. Branch on this value."
          },
          "message": {
            "type": "string",
            "description": "What went wrong, in a sentence."
          },
          "hint": {
            "type": "string",
            "description": "How to fix the request."
          }
        }
      },
      "SandboxAccepted": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "sandbox",
          "message"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true,
            "description": "Always true on success."
          },
          "sandbox": {
            "type": "boolean",
            "const": true,
            "description": "Always true: the request was validated and nothing was sent."
          },
          "message": {
            "type": "string",
            "description": "Plain-language confirmation that no email was sent."
          }
        },
        "description": "The body is valid. Returned by the sandbox endpoint. No email is sent."
      },
      "IntakeIndex": {
        "type": "object",
        "description": "JSON index of the endpoints on the intake host, returned by GET /.",
        "additionalProperties": false,
        "required": [
          "ok",
          "name",
          "version",
          "docs",
          "openapi",
          "endpoints"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true,
            "description": "Always true on success."
          },
          "name": {
            "type": "string",
            "description": "Name of the intake API."
          },
          "version": {
            "type": "string",
            "description": "API major version as a string, currently 1."
          },
          "docs": {
            "type": "string",
            "description": "Developer documentation page.",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "description": "Location of this OpenAPI document.",
            "format": "uri"
          },
          "endpoints": {
            "type": "array",
            "description": "Every endpoint on the intake host, including the MCP server.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "method",
                "url",
                "description"
              ],
              "properties": {
                "method": {
                  "type": "string",
                  "description": "HTTP method, for example GET or POST."
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Absolute URL of the endpoint."
                },
                "description": {
                  "type": "string",
                  "description": "What the endpoint does."
                }
              },
              "description": "One endpoint on the intake host."
            }
          }
        }
      },
      "Post": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url",
          "title",
          "datePublished",
          "section",
          "description"
        ],
        "description": "One blog post on https://supergood.solutions/blog/.",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL of the post. Append index.md-style twin by replacing the trailing slash with .md."
          },
          "title": {
            "type": "string",
            "description": "Headline."
          },
          "datePublished": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "First published, YYYY-MM-DD."
          },
          "section": {
            "type": [
              "string",
              "null"
            ],
            "description": "Blog section, such as Analysis or Guardrails."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "One- or two-sentence summary from the RSS feed. Null when the feed has not caught up with the post."
          }
        }
      },
      "PostPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "data",
          "page",
          "total"
        ],
        "description": "One page of posts, newest first.",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          },
          "page": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "limit",
              "next_cursor",
              "has_more"
            ],
            "properties": {
              "limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 50,
                "description": "Page size used."
              },
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Opaque cursor for the next page. Null on the last page."
              },
              "has_more": {
                "type": "boolean",
                "description": "True when another page follows."
              }
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of posts across all pages."
          }
        }
      },
      "AskRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "query"
        ],
        "description": "NLWeb 0.55 structured request.",
        "properties": {
          "query": {
            "type": "object",
            "additionalProperties": true,
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "type": "string",
                "minLength": 2,
                "maxLength": 500,
                "description": "The question, in plain language."
              },
              "site": {
                "type": "string",
                "enum": [
                  "supergood.solutions"
                ],
                "description": "Optional. Only supergood.solutions is answered."
              }
            }
          },
          "top_k": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 5,
            "description": "How many posts to return."
          },
          "prefer": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "streaming": {
                "type": "boolean",
                "default": false,
                "description": "True returns text/event-stream."
              },
              "mode": {
                "type": "string",
                "enum": [
                  "list"
                ],
                "description": "Only list mode is served."
              }
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "version": {
                "type": "string",
                "enum": [
                  "0.55"
                ]
              }
            }
          }
        }
      },
      "AskResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "@type",
          "url",
          "name",
          "site",
          "score",
          "description",
          "schema_object"
        ],
        "description": "One matching post, NLWeb result shape.",
        "properties": {
          "@type": {
            "type": "string",
            "const": "Article"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "name": {
            "type": "string"
          },
          "site": {
            "type": "string",
            "const": "supergood.solutions"
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Relevance relative to the best match (1)."
          },
          "description": {
            "type": "string"
          },
          "schema_object": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "schema.org BlogPosting."
            }
          }
        }
      },
      "AskResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "query_id",
          "query",
          "site",
          "mode",
          "total_results",
          "results",
          "_meta"
        ],
        "description": "NLWeb 0.55 list-mode response. Ranked by keyword match; no generated answer.",
        "properties": {
          "query_id": {
            "type": "string",
            "format": "uuid"
          },
          "query": {
            "type": "string"
          },
          "site": {
            "type": "string",
            "const": "supergood.solutions"
          },
          "mode": {
            "type": "string",
            "const": "list"
          },
          "total_results": {
            "type": "integer",
            "minimum": 0,
            "description": "Always equals results.length."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AskResult"
            }
          },
          "_meta": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "version",
              "response_type",
              "mode",
              "site"
            ],
            "properties": {
              "version": {
                "type": "string",
                "const": "0.55"
              },
              "response_type": {
                "type": "string",
                "const": "result"
              },
              "mode": {
                "type": "string",
                "const": "list"
              },
              "site": {
                "type": "string",
                "const": "supergood.solutions"
              }
            }
          }
        }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Optional. 1 to 200 printable ASCII characters, no spaces, such as a UUID. A retry with the same key and the same body within 24 hours does not send a second email. The same key with a different body returns 422 idempotency_conflict. Keys are scoped to the caller's IP address.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "pattern": "^[\\x21-\\x7e]+$",
          "examples": [
            "3b241101-e2bb-4255-8caf-4136c566a962"
          ]
        }
      }
    },
    "headers": {
      "RateLimitLimit": {
        "description": "Requests allowed in the current window.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "RateLimitRemaining": {
        "description": "Requests left in the current window.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimitReset": {
        "description": "Seconds until the window resets.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimitPolicy": {
        "description": "The policy as limit;w=window-seconds, for example 10;w=600.",
        "schema": {
          "type": "string"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before retrying. Sent on 429.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "APIVersion": {
        "description": "The API major version. Currently 1.",
        "schema": {
          "type": "string",
          "examples": [
            "1"
          ]
        }
      },
      "Deprecation": {
        "description": "Sent only on a path in a deprecation window. Not sent today.",
        "schema": {
          "type": "string"
        }
      },
      "Sunset": {
        "description": "HTTP date after which a deprecated path may stop working. Sent only in a deprecation window, at least 90 days ahead. Not sent today.",
        "schema": {
          "type": "string"
        }
      }
    }
  }
}
