{
  "openapi": "3.1.0",
  "info": {
    "title": "VertoDigital Agent API",
    "version": "1.0.0",
    "description": "Public, anonymous, rate-limited API surface for AI agents interacting with VertoDigital. Covers a health check, a contact-enquiry endpoint, a structured case-study index, and the Free B2B AI Visibility Checker, an async job API: POST /agent/readiness/checks returns 202 Accepted with a job_id and a status URL (also in the Location header) to poll until the report is ready. Full page *content* is deliberately not duplicated here - agents should use /llms.txt (LLM-readable site index), the /markdown/{path} mirror (any page as clean markdown), /.well-known/api-catalog (RFC 9727 API catalog), and the VertoDigital MCP server at https://mcp.vertodigital.com/mcp for that. The case-study index is a narrow, deliberate exception to that rule: it returns structured metadata (name, stat, industry, URLs) for paginated browsing, not case-study body text, so it doesn't duplicate what the markdown mirror already serves. Versioning and deprecation policy: the paths below (unversioned, under /agent/*) always mirror the current major version - v1 today - and are the recommended integration surface. The health, contact and case-study operations are also pinned at /agent/v1/openapi.json under /agent/v1/* for a caller that wants its integration to survive a future v2 unchanged. A breaking change ships as /agent/v2/* while /agent/v1/* keeps working; only then does /agent/v1/* become deprecated, at which point its responses carry a Deprecation: true header and a Sunset header with the retirement date, announced here and in /llms.txt at least 90 days ahead. Every response from those operations also carries an API-Version header (currently 1) so a caller can detect which version actually served it without parsing the body.",
    "termsOfService": "https://vertodigital.com/terms",
    "contact": {
      "name": "VertoDigital",
      "url": "https://vertodigital.com/contact",
      "email": "paul.green@vertodigital.com"
    }
  },
  "servers": [
    { "url": "https://vertodigital.com" }
  ],
  "x-versioning-policy": {
    "scheme": "url-path-major-version",
    "current_version": "1",
    "recommended_integration_path": "/agent",
    "pinned_version_paths": { "1": "/agent/v1" },
    "version_response_header": "API-Version",
    "deprecation_process": {
      "description": "A breaking change ships as a new major version path (e.g. /agent/v2) alongside the existing one - nothing on the current version breaks the day a new version ships. Only once a version is actually retired do its responses carry the two headers below, with the notice period given here as a minimum.",
      "minimum_notice_days": 90,
      "response_headers": ["Deprecation", "Sunset"],
      "announced_at": [
        "https://vertodigital.com/agent/openapi.json#info.description",
        "https://vertodigital.com/llms.txt",
        "https://vertodigital.com/developers"
      ]
    }
  },
  "externalDocs": {
    "description": "LLM-readable site index",
    "url": "https://vertodigital.com/llms.txt"
  },
  "tags": [
    { "name": "meta", "description": "Service status" },
    { "name": "contact", "description": "Contact and enquiry submission" },
    { "name": "case-studies", "description": "Structured, paginated case study index" },
    { "name": "readiness", "description": "Free B2B AI Visibility Checker: start an AI agent readiness check as an async job (202 Accepted) and poll for the result" }
  ],
  "paths": {
    "/agent/health": {
      "get": {
        "operationId": "getHealth",
        "tags": ["meta"],
        "summary": "Service health check",
        "description": "Anonymous, unauthenticated, generously rate-limited (300 requests/minute per caller IP - high enough that no legitimate poller should ever see a 429). Returns service status and a map of related discovery endpoints. Does not probe upstream dependencies (HubSpot, Resend) or report which secrets are configured.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Service is reachable",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" },
              "Deprecation": { "$ref": "#/components/headers/Deprecation" },
              "Sunset": { "$ref": "#/components/headers/Sunset" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "headers": {
              "Allow": {
                "description": "Methods this endpoint accepts",
                "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the caller may retry",
                "schema": { "type": "integer" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimited" }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/contact": {
      "post": {
        "operationId": "submitEnquiry",
        "tags": ["contact"],
        "summary": "Submit a contact enquiry on behalf of a user",
        "description": "Anonymous, rate-limited (5 requests/minute and 50 requests/day per caller IP). No authentication required. Returns 200 once the enquiry has been delivered (CRM + internal notification) - the response is only sent after upstream delivery succeeds, so a 200 guarantees delivery rather than merely accepting the request for later. Supports Idempotency-Key: retrying the same request with the same key and body replays the original response (marked with an Idempotent-Replayed header) instead of submitting a second enquiry - safe to do after a timeout or dropped connection. Reusing a key with a different body returns 409.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Caller-generated key (e.g. a UUID), up to 200 characters. Retrying this call with the same key and an identical request body within 24h replays the first call's response rather than submitting a duplicate enquiry. Reusing the key with a different body returns 409.",
            "schema": { "type": "string", "maxLength": 200 }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["fromName", "fromEmail", "message"],
                "properties": {
                  "fromName": { "type": "string", "minLength": 1, "maxLength": 100 },
                  "fromEmail": { "type": "string", "format": "email", "maxLength": 254 },
                  "organization": { "type": "string", "maxLength": 100 },
                  "topic": {
                    "type": "string",
                    "enum": ["assessment", "services", "partnership", "press", "careers", "general"],
                    "default": "general"
                  },
                  "message": { "type": "string", "minLength": 10, "maxLength": 2000 },
                  "agentId": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "Self-asserted identifier for the calling agent. Not verified."
                  }
                }
              },
              "example": {
                "fromName": "Ada Lovelace",
                "fromEmail": "ada@example.com",
                "organization": "Analytical Engines Ltd",
                "topic": "services",
                "message": "We'd like to discuss a marketing analytics engagement.",
                "agentId": "agent-123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enquiry delivered",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" },
              "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" },
              "Deprecation": { "$ref": "#/components/headers/Deprecation" },
              "Sunset": { "$ref": "#/components/headers/Sunset" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactAccepted" }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValidationError" }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key reused with a different request body",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "413": {
            "description": "Request body too large",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the caller may retry",
                "schema": { "type": "integer" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimited" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "502": {
            "description": "Upstream delivery error",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/case-studies": {
      "get": {
        "operationId": "listCaseStudies",
        "tags": ["case-studies"],
        "summary": "List case studies (paginated)",
        "description": "Structured, cursor-paginated index of VertoDigital case studies - name, headline stat, industry, and detail URLs for each, parsed live from the same curated index case-studies.html and the MCP server's vertodigital_search_case_studies tool are built from. Anonymous, unauthenticated, generously rate-limited (300 requests/minute per caller IP).",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor from a previous response's next_cursor. Omit to start from the beginning.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum items to return per page.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated case study list",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CaseStudyList" }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "headers": {
              "Allow": {
                "description": "Methods this endpoint accepts",
                "schema": { "type": "string", "const": "GET, OPTIONS" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the caller may retry",
                "schema": { "type": "integer" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimited" }
              }
            }
          },
          "502": {
            "description": "Source index temporarily unavailable",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/readiness/checks": {
      "post": {
        "operationId": "startReadinessCheck",
        "tags": [
          "readiness"
        ],
        "summary": "Start an AI agent readiness check (async job)",
        "description": "Starts a Free B2B AI Visibility Checker scan of a company's website: a 0-100 score for how well buyers' AI agents can research the company, evaluate its product and reach sales, with evidence-backed findings. A scan takes longer than one request, so this is an async job. A new check returns 202 Accepted with a job_id, a status_url and a Location header pointing at GET /agent/readiness/checks/{job_id}: poll it every Retry-After seconds until status is complete or failed, then read report_json_url (the report as JSON) or report_url (the human page). A public check of a domain already scanned in the last 24 hours returns 200 with the cached report instead of starting a new job. Anonymous. Rate limits per caller IP: 60 requests a minute, plus 3 new checks and 3 comparisons a day without a Turnstile token. Not mirrored under /agent/v1.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "Website to check, as a domain or URL (example.com or https://www.example.com/). Subdomains fold into the main domain. In compare mode, the competitor's domain."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "public",
                      "compare"
                    ],
                    "default": "public",
                    "description": "public: check one company and publish its report. compare: check two companies side by side (set compare_with)."
                  },
                  "compare_with": {
                    "type": "string",
                    "description": "Compare mode only: your own company's domain, checked side by side with the competitor in domain."
                  },
                  "turnstile_token": {
                    "type": "string",
                    "description": "Cloudflare Turnstile token sent by the checker's own web page. Agents omit it; the lower daily limits then apply."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Check accepted and queued. Poll status_url (also in the Location header) until status is complete or failed.",
            "headers": {
              "Location": {
                "description": "Path of this job's status resource: /agent/readiness/checks/{job_id}",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before the first poll",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessCheckAccepted"
                }
              }
            },
            "links": {
              "PollCheck": {
                "operationId": "getReadinessCheck",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Poll this job's status with the job_id from the response body (the same resource as status_url and the Location header)"
              }
            }
          },
          "200": {
            "description": "This domain was checked in the last 24 hours: the cached report, no new job",
            "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"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessCheckCached"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, such as a domain that can't be parsed or a compare check of a company against itself",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessError"
                }
              }
            }
          },
          "403": {
            "description": "Reports for this domain are not published",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: per-minute or daily limit reached",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the caller may retry",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessError"
                }
              }
            }
          },
          "503": {
            "description": "The checker has reached its daily capacity; try again tomorrow",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessError"
                }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/readiness/checks/{job_id}": {
      "get": {
        "operationId": "getReadinessCheck",
        "tags": [
          "readiness"
        ],
        "summary": "Poll an AI agent readiness check",
        "description": "Status of a check started with POST /agent/readiness/checks. While status is queued or running the response carries Retry-After (seconds) and a progress object; once complete it carries report_url and report_json_url, and once failed an error. Never cached (Cache-Control: no-store). Most checks finish within a minute.",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "description": "job_id from the 202 response",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{22}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current job status",
            "headers": {
              "Retry-After": {
                "description": "Present while status is queued or running: seconds to wait before polling again",
                "schema": {
                  "type": "integer"
                }
              },
              "Cache-Control": {
                "description": "Always no-store",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessCheckStatus"
                }
              }
            }
          },
          "404": {
            "description": "No check with this job_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessError"
                }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/readiness/reports/{slug}": {
      "get": {
        "operationId": "getReadinessReport",
        "tags": [
          "readiness"
        ],
        "summary": "Get a published AI agent readiness report",
        "description": "The full report behind report_json_url: score, verdict, per-module and per-check results with evidence, top fixes and the simulated buyer-agent journey. slug is the domain with dots as hyphens (example-com).",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Report slug, e.g. example-com",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessReport"
                }
              }
            }
          },
          "404": {
            "description": "No published report for this slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessError"
                }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/readiness/compare/{compare_id}": {
      "get": {
        "operationId": "getReadinessComparison",
        "tags": [
          "readiness"
        ],
        "summary": "Get a side-by-side readiness comparison",
        "description": "The result of a compare-mode check: both companies' reports. The compare_id is the last segment of the report_url a completed compare job returns.",
        "parameters": [
          {
            "name": "compare_id",
            "in": "path",
            "required": true,
            "description": "Comparison id",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{22}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The comparison",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessComparison"
                }
              }
            }
          },
          "404": {
            "description": "No comparison with this id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessError"
                }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/v1/health": {
      "get": {
        "operationId": "getHealthV1",
        "tags": ["meta"],
        "summary": "Service health check (v1, pinned)",
        "description": "Version-pinned alias of getHealth (GET /agent/health), served at a URL-versioned path so an integration keeps working unchanged even after a future v2 ships. Identical behavior otherwise: anonymous, unauthenticated, generously rate-limited (300 requests/minute per caller IP).",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Service is reachable",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" },
              "Deprecation": { "$ref": "#/components/headers/Deprecation" },
              "Sunset": { "$ref": "#/components/headers/Sunset" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "headers": {
              "Allow": {
                "description": "Methods this endpoint accepts",
                "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the caller may retry",
                "schema": { "type": "integer" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimited" }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/v1/contact": {
      "post": {
        "operationId": "submitEnquiryV1",
        "tags": ["contact"],
        "summary": "Submit a contact enquiry on behalf of a user (v1, pinned)",
        "description": "Version-pinned alias of submitEnquiry (POST /agent/contact), served at a URL-versioned path so an integration keeps working unchanged even after a future v2 ships. Identical behavior otherwise, including rate limits and Idempotency-Key support.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Caller-generated key (e.g. a UUID), up to 200 characters. Retrying this call with the same key and an identical request body within 24h replays the first call's response rather than submitting a duplicate enquiry. Reusing the key with a different body returns 409.",
            "schema": { "type": "string", "maxLength": 200 }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["fromName", "fromEmail", "message"],
                "properties": {
                  "fromName": { "type": "string", "minLength": 1, "maxLength": 100 },
                  "fromEmail": { "type": "string", "format": "email", "maxLength": 254 },
                  "organization": { "type": "string", "maxLength": 100 },
                  "topic": {
                    "type": "string",
                    "enum": ["assessment", "services", "partnership", "press", "careers", "general"],
                    "default": "general"
                  },
                  "message": { "type": "string", "minLength": 10, "maxLength": 2000 },
                  "agentId": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "Self-asserted identifier for the calling agent. Not verified."
                  }
                }
              },
              "example": {
                "fromName": "Ada Lovelace",
                "fromEmail": "ada@example.com",
                "organization": "Analytical Engines Ltd",
                "topic": "services",
                "message": "We'd like to discuss a marketing analytics engagement.",
                "agentId": "agent-123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enquiry delivered",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" },
              "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" },
              "Deprecation": { "$ref": "#/components/headers/Deprecation" },
              "Sunset": { "$ref": "#/components/headers/Sunset" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactAccepted" }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValidationError" }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key reused with a different request body",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "413": {
            "description": "Request body too large",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the caller may retry",
                "schema": { "type": "integer" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimited" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "502": {
            "description": "Upstream delivery error",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/agent/v1/case-studies": {
      "get": {
        "operationId": "listCaseStudiesV1",
        "tags": ["case-studies"],
        "summary": "List case studies (paginated, v1 pinned)",
        "description": "Version-pinned alias of listCaseStudies (GET /agent/case-studies), served at a URL-versioned path so an integration keeps working unchanged even after a future v2 ships. Identical behavior otherwise.",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor from a previous response's next_cursor. Omit to start from the beginning.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum items to return per page.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated case study list",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CaseStudyList" }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "headers": {
              "Allow": {
                "description": "Methods this endpoint accepts",
                "schema": { "type": "string", "const": "GET, OPTIONS" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the caller may retry",
                "schema": { "type": "integer" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "RateLimit": { "$ref": "#/components/headers/RateLimit" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimited" }
              }
            }
          },
          "502": {
            "description": "Source index temporarily unavailable",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "components": {
    "headers": {
      "ApiVersion": {
        "description": "The major API version that served this response (see x-versioning-policy at the document root, and the policy note in info.description).",
        "schema": { "type": "string", "const": "1" }
      },
      "Deprecation": {
        "description": "Present only once this API version has been deprecated (per x-versioning-policy); absent otherwise.",
        "schema": { "type": "string", "const": "true" }
      },
      "Sunset": {
        "description": "Present only once this API version has been deprecated - the HTTP-date this version stops being served (RFC 8594). Absent otherwise.",
        "schema": { "type": "string", "format": "date-time" }
      },
      "RateLimitLimit": {
        "description": "The request quota for the current rate-limit window (RFC draft-ietf-httpapi-ratelimit-headers).",
        "schema": { "type": "integer" }
      },
      "RateLimitRemaining": {
        "description": "Requests remaining in the current rate-limit window.",
        "schema": { "type": "integer" }
      },
      "RateLimitReset": {
        "description": "Seconds until the current rate-limit window resets.",
        "schema": { "type": "integer" }
      },
      "RateLimitPolicy": {
        "description": "Every quota policy applied to this endpoint, as an IETF structured-field list (current draft-ietf-httpapi-ratelimit-headers): \"<name>\";q=<quota>;w=<window-seconds>. Example: \"per-minute\";q=5;w=60, \"per-day\";q=50;w=86400.",
        "schema": { "type": "string" }
      },
      "RateLimit": {
        "description": "Remaining quota in the currently binding policy, as an IETF structured field (current draft-ietf-httpapi-ratelimit-headers): \"<name>\";r=<remaining>;t=<seconds-until-reset>. Example: \"per-minute\";r=4;t=37. Carries the same numbers as RateLimit-Remaining/RateLimit-Reset.",
        "schema": { "type": "string" }
      },
      "IdempotentReplayed": {
        "description": "Present and \"true\" only when this response is a replay of an earlier call with the same Idempotency-Key; absent on a first-time response.",
        "schema": { "type": "string", "const": "true" }
      }
    },
    "schemas": {
      "ReadinessCheckAccepted": {
        "type": "object",
        "required": [
          "job_id",
          "status",
          "status_url",
          "poll_after_seconds"
        ],
        "properties": {
          "job_id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{22}$",
            "description": "Job identifier"
          },
          "status": {
            "type": "string",
            "const": "queued"
          },
          "status_url": {
            "type": "string",
            "format": "uri",
            "description": "Absolute URL to poll: GET /agent/readiness/checks/{job_id}"
          },
          "poll_after_seconds": {
            "type": "integer",
            "description": "Suggested polling interval"
          }
        }
      },
      "ReadinessCheckCached": {
        "type": "object",
        "required": [
          "status",
          "cached",
          "report_url",
          "report_json_url"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "complete"
          },
          "cached": {
            "type": "boolean",
            "const": true
          },
          "report_url": {
            "type": "string",
            "format": "uri",
            "description": "The report page"
          },
          "report_json_url": {
            "type": "string",
            "format": "uri",
            "description": "The report as JSON: GET /agent/readiness/reports/{slug}"
          }
        }
      },
      "ReadinessCheckStatus": {
        "type": "object",
        "required": [
          "status",
          "progress"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "complete",
              "failed"
            ]
          },
          "progress": {
            "type": [
              "object",
              "null"
            ],
            "description": "Scan progress, null before the scan starts",
            "properties": {
              "step": {
                "type": "string"
              },
              "done": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            }
          },
          "report_url": {
            "type": "string",
            "format": "uri",
            "description": "Present when status is complete: the report page"
          },
          "report_json_url": {
            "type": "string",
            "format": "uri",
            "description": "Present when status is complete: the report as JSON (for a comparison, GET /agent/readiness/compare/{compare_id})"
          },
          "error": {
            "type": "string",
            "description": "Present when status is failed"
          }
        }
      },
      "ReadinessReport": {
        "type": "object",
        "description": "A readiness report. The main fields are listed; the methodology is at https://vertodigital.com/b2b-ai-visibility-checker/tool/how-it-works.",
        "properties": {
          "domain": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "companyName": {
            "type": "string"
          },
          "homepageUrl": {
            "type": "string"
          },
          "methodologyVersion": {
            "type": "string"
          },
          "startedAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "verdict": {
            "type": "string"
          },
          "modules": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "topFixes": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "journey": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "dropOff": {
            "type": "string",
            "description": "Where a buyer's AI agent stopped"
          }
        },
        "additionalProperties": true
      },
      "ReadinessComparison": {
        "type": "object",
        "required": [
          "id",
          "created_at",
          "a",
          "b"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "a": {
            "$ref": "#/components/schemas/ReadinessReport"
          },
          "b": {
            "$ref": "#/components/schemas/ReadinessReport"
          }
        }
      },
      "ReadinessError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in plain words (or not_found / rate_limited)"
          }
        }
      },
      "ContactAccepted": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "const": "accepted" },
          "reference": { "type": "string", "pattern": "^enq_[0-9a-f]{16}$" },
          "receivedAt": { "type": "string", "format": "date-time" }
        }
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "const": "invalid_request" },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          }
        }
      },
      "RateLimited": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "const": "rate_limited" },
          "message": { "type": "string" },
          "retryAfter": { "type": "integer", "description": "Seconds" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["ok", "degraded"] },
          "service": { "type": "string" },
          "version": { "type": "string" },
          "time": { "type": "string", "format": "date-time" },
          "endpoints": {
            "type": "object",
            "properties": {
              "contact": { "type": "string", "format": "uri" },
              "openapi": { "type": "string", "format": "uri" },
              "catalog": { "type": "string", "format": "uri" },
              "mcp": { "type": "string", "format": "uri" }
            }
          }
        }
      },
      "CaseStudyItem": {
        "type": "object",
        "required": ["name", "stat", "industry", "slug", "url", "markdown_url", "description"],
        "properties": {
          "name": { "type": "string", "description": "Client name" },
          "stat": { "type": "string", "description": "Headline result, e.g. \"2.3x Pipeline in 90 Days\"" },
          "industry": { "type": "string", "description": "Industry grouping heading, e.g. \"Cybersecurity\"" },
          "slug": { "type": "string", "description": "Path segment under /case-studies/, e.g. \"case-studies/ironscales\"" },
          "url": { "type": "string", "format": "uri", "description": "Human-facing case study page" },
          "markdown_url": { "type": "string", "format": "uri", "description": "Full case study content as markdown - fetch this (or the equivalent vertodigital_get_page MCP tool call) for the complete write-up" },
          "description": { "type": "string", "description": "One-line summary" }
        }
      },
      "CaseStudyList": {
        "type": "object",
        "required": ["items", "count", "total", "has_more", "next_cursor"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/CaseStudyItem" } },
          "count": { "type": "integer", "description": "Number of items in this page" },
          "total": { "type": "integer", "description": "Total case studies across all pages" },
          "has_more": { "type": "boolean" },
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Opaque cursor for the next page - pass as ?cursor=. Null when has_more is false."
          }
        }
      }
    }
  }
}
