{
  "openapi": "3.1.0",
  "info": {
    "title": "Seahawk Media public API",
    "version": "1.0.0",
    "summary": "Search seahawkmedia.com and run Seahawk's free website tools.",
    "description": "Public, unauthenticated, read-only endpoints. The same functions are available as tools on the MCP server at https://seahawkmedia.com/mcp (server card: https://seahawkmedia.com/mcp/server-card). Rate limits: results are cached (site checks and speed tests for an hour, search for 5 minutes); heavy use may receive 429 Too Many Requests with a Retry-After header from the edge, so honour it and retry later.",
    "contact": { "name": "Seahawk Media", "url": "https://seahawkmedia.com/contact-us/", "email": "nest@seahawkmedia.com" }
  },
  "servers": [{ "url": "https://seahawkmedia.com" }],
  "externalDocs": { "description": "Index of key pages for agents", "url": "https://seahawkmedia.com/llms.txt" },
  "paths": {
    "/ask": {
      "get": {
        "operationId": "ask",
        "summary": "Search the site (NLWeb ask)",
        "description": "Returns the pages of seahawkmedia.com that best match a plain-language query, ranked, as schema.org objects in the NLWeb response shape.",
        "parameters": [
          { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 500 }, "example": "wordpress maintenance plans" },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }
        ],
        "responses": {
          "200": { "description": "Ranked results (empty when nothing matched).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      },
      "post": {
        "operationId": "askPost",
        "summary": "Search the site (NLWeb ask), JSON body",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "maxLength": 500 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } } } } } },
        "responses": {
          "200": { "description": "Ranked results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/site-check": {
      "get": {
        "operationId": "checkWebsite",
        "summary": "Check a website",
        "description": "Fetches a public page and reports its HTTP status, HTTPS and redirect, security headers, SEO basics, WordPress detection (theme, plugins) and, with links=1, the status of the page's links. Powers https://seahawkmedia.com/tools/seo-checker/.",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "example": "example.com" },
          { "name": "links", "in": "query", "required": false, "schema": { "type": "string", "enum": ["1"] }, "description": "Set to 1 to also check every link on the page." }
        ],
        "responses": {
          "200": { "description": "The report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteCheck" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "422": { "description": "The address did not return a web page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "502": { "description": "The site could not be reached or timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/speed": {
      "get": {
        "operationId": "testPageSpeed",
        "summary": "Test page speed",
        "description": "Runs Google PageSpeed Insights on a public page: performance score, lab Core Web Vitals, field data where available and the top opportunities. Can take up to a minute. Powers https://seahawkmedia.com/tools/website-speed-test/.",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "example": "https://example.com/" },
          { "name": "strategy", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mobile", "desktop"], "default": "mobile" } }
        ],
        "responses": {
          "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeedResult" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "502": { "description": "PageSpeed could not test the page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "The speed test is unavailable; use the fallback link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": { "description": "Missing or invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "TooManyRequests": { "description": "Rate limited. Wait for Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "description": "What went wrong, in plain words." },
          "status": { "type": "integer" },
          "fallback": { "type": "string", "format": "uri", "description": "Where to run the same check instead." }
        }
      },
      "AskResponse": {
        "type": "object",
        "required": ["query_id", "results"],
        "properties": {
          "query_id": { "type": "string" },
          "query": { "type": "string" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/AskResult" } }
        }
      },
      "AskResult": {
        "type": "object",
        "required": ["url", "name", "site", "score"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "name": { "type": "string" },
          "site": { "type": "string", "const": "seahawkmedia.com" },
          "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relevance relative to the best match (1)." },
          "description": { "type": "string" },
          "schema_object": { "type": "object", "description": "The page as a schema.org WebPage, Article or Service.", "properties": { "@type": { "type": "string", "enum": ["WebPage", "Article", "Service"] }, "name": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" } } }
        }
      },
      "SiteCheck": {
        "type": "object",
        "required": ["url", "finalUrl", "status", "https", "checkedAt"],
        "properties": {
          "url": { "type": "string" },
          "finalUrl": { "type": "string" },
          "status": { "type": "integer" },
          "https": { "type": "boolean" },
          "httpsRedirect": { "type": ["boolean", "null"] },
          "server": { "type": ["string", "null"] },
          "poweredBy": { "type": ["string", "null"] },
          "securityHeaders": { "type": "object", "additionalProperties": true },
          "wordpress": { "type": "object", "additionalProperties": true, "properties": { "detected": { "type": "boolean" }, "themes": { "type": "array", "items": { "type": "object" } } } },
          "links": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "linkCount": { "type": "integer" },
          "linksChecked": { "type": "integer" },
          "checkedAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": true
      },
      "Metric": { "type": ["object", "null"], "properties": { "value": { "type": ["string", "null"] }, "score": { "type": ["number", "null"] } } },
      "FieldMetric": { "type": ["object", "null"], "properties": { "p75": { "type": "number" }, "category": { "type": "string" } } },
      "SpeedResult": {
        "type": "object",
        "required": ["url", "strategy", "score", "checkedAt"],
        "properties": {
          "url": { "type": "string" },
          "finalUrl": { "type": "string" },
          "strategy": { "type": "string", "enum": ["mobile", "desktop"] },
          "score": { "type": ["integer", "null"], "minimum": 0, "maximum": 100 },
          "lab": { "type": "object", "properties": { "fcp": { "$ref": "#/components/schemas/Metric" }, "lcp": { "$ref": "#/components/schemas/Metric" }, "tbt": { "$ref": "#/components/schemas/Metric" }, "cls": { "$ref": "#/components/schemas/Metric" }, "si": { "$ref": "#/components/schemas/Metric" }, "ttfb": { "$ref": "#/components/schemas/Metric" } } },
          "field": { "type": ["object", "null"], "properties": { "overall": { "type": ["string", "null"] }, "lcp": { "$ref": "#/components/schemas/FieldMetric" }, "inp": { "$ref": "#/components/schemas/FieldMetric" }, "cls": { "$ref": "#/components/schemas/FieldMetric" }, "fcp": { "$ref": "#/components/schemas/FieldMetric" }, "ttfb": { "$ref": "#/components/schemas/FieldMetric" } } },
          "opportunities": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "savings": { "type": ["string", "null"] } } } },
          "checkedAt": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}
