{
  "$schema": "https://vetclinic.info/.well-known/agent-actions.json",
  "site": "https://vetclinic.info",
  "version": "2026-05-20",
  "operator": {
    "name": "vetclinic.info",
    "contact": "hi@vetclinic.info",
    "rate_limit_contact": "hi@vetclinic.info",
    "publishing_principles": "https://vetclinic.info/about/editorial-policy/",
    "ownership_funding_info": "https://vetclinic.info/about/business-model/",
    "verification_process": "https://vetclinic.info/about/verification-process/"
  },
  "discovery": {
    "principle": "The agent API mirrors the human site exactly. Take any path on vetclinic.info and prepend `/api/agents` to get the JSON-LD equivalent. The hierarchy under `/us/<state>/<city>/<clinic>/` is load-bearing for clinic identity because clinic slugs are unique per city, not globally.",
    "examples": [
      { "human": "https://vetclinic.info/us/co/denver/spry-companions/", "agent": "https://vetclinic.info/api/agents/us/co/denver/spry-companions" },
      { "human": "https://vetclinic.info/procedures/tplo-surgery/",         "agent": "https://vetclinic.info/api/agents/procedures/tplo-surgery" },
      { "human": "https://vetclinic.info/us/co/denver/orthopedic-surgery/", "agent": "https://vetclinic.info/api/agents/us/co/denver/orthopedic-surgery" }
    ],
    "output_format": "application/ld+json with top-level `@graph` carrying the same schema.org entities the human page emits (VeterinaryCare, Person[], FAQPage, Article, MedicalProcedure, ItemList, BreadcrumbList). Every response carries a `Link: <manifest>; rel=\"describedby\"` header.",
    "ua_request": "Agents are encouraged to identify themselves via the standard User-Agent header (e.g. `ChatGPT-User/1.0`, `ClaudeBot/1.0`, `PerplexityBot/1.0`). Logged but not enforced."
  },
  "actions": [
    {
      "id": "find-specialty-clinics-in-city",
      "type": "SearchAction",
      "description": "List veterinary specialists in a given city for a given specialty. Returns an ItemList of compact VeterinaryCare records ranked by promoted-first then by review-weighted rating.",
      "endpoint": "https://vetclinic.info/api/agents/us/{state}/{city}/{specialty}",
      "method": "GET",
      "auth": "none",
      "rate_limit": "60/min anonymous; contact for higher",
      "inputs": [
        { "name": "state", "type": "string", "required": true, "example": "co", "description": "2-letter state slug (lowercase)." },
        { "name": "city",  "type": "string", "required": true, "example": "denver", "description": "City slug as the directory knows it; see the city endpoint to enumerate." },
        { "name": "specialty", "type": "string", "required": true, "example": "orthopedic-surgery", "enum_url": "https://vetclinic.info/api/agents/specialties" }
      ],
      "outputs": {
        "format": "application/ld+json",
        "schema": "ItemList of VeterinaryCare",
        "fields": ["@id", "name", "url", "address", "aggregateRating", "medicalSpecialty"]
      },
      "ui_equivalent": "https://vetclinic.info/us/{state}/{city}/{specialty}/"
    },
    {
      "id": "get-clinic-detail",
      "type": "ViewAction",
      "description": "Full clinic record: VeterinaryCare entity with team Persons (each with verified board-certification credentials linked to issuing boards), inline Google Reviews, FAQ, opening hours, geo, ratings, and explicit verification metadata.",
      "endpoint": "https://vetclinic.info/api/agents/us/{state}/{city}/{clinic-slug}",
      "method": "GET",
      "auth": "none",
      "rate_limit": "60/min anonymous",
      "inputs": [
        { "name": "state", "type": "string", "required": true, "example": "co" },
        { "name": "city",  "type": "string", "required": true, "example": "denver" },
        { "name": "clinic-slug", "type": "string", "required": true, "example": "spry-companions", "description": "Slug as found in the clinic's canonical human URL." }
      ],
      "outputs": {
        "format": "application/ld+json",
        "schema": "@graph: [VeterinaryCare, BreadcrumbList, Person[], FAQPage]",
        "fields": ["VeterinaryCare.disambiguatingDescription", "VeterinaryCare.additionalProperty[vetclinic_verified]", "VeterinaryCare.review[]", "Person.hasCredential[].recognizedBy.sameAs"]
      },
      "ui_equivalent": "https://vetclinic.info/us/{state}/{city}/{clinic-slug}/"
    },
    {
      "id": "get-procedure-detail",
      "type": "ViewAction",
      "description": "Procedure article with grounded citations, cost band (MonetaryAmountDistribution), recovery info, FAQ, plus a state-aware specialist finder. Articles are bylined, reviewed, and validated against the live authority-source corpus; ungrounded citations are dropped before publication.",
      "endpoint": "https://vetclinic.info/api/agents/procedures/{slug}",
      "method": "GET",
      "auth": "none",
      "rate_limit": "60/min anonymous",
      "inputs": [
        { "name": "slug", "type": "string", "required": true, "example": "tplo-surgery", "enum_url": "https://vetclinic.info/api/agents/procedures" }
      ],
      "outputs": {
        "format": "application/ld+json",
        "schema": "@graph: [Article+MedicalWebPage, MedicalProcedure, BreadcrumbList, FAQPage, ItemList (finder)]",
        "fields": ["Article.reviewedBy", "Article.editorialNote", "Article.citation[]", "MedicalProcedure.estimatedCost", "MedicalProcedure.recognizingAuthority", "MedicalProcedure.offers"]
      },
      "ui_equivalent": "https://vetclinic.info/procedures/{slug}/"
    },
    {
      "id": "get-procedure-finder-by-state",
      "type": "SearchAction",
      "description": "State-pre-filtered specialist finder for a given procedure. Same payload as get-procedure-detail but the finder ItemList is filtered to specialists in the requested US state.",
      "endpoint": "https://vetclinic.info/api/agents/procedures/{slug}/us/{state}",
      "method": "GET",
      "auth": "none",
      "rate_limit": "60/min anonymous",
      "inputs": [
        { "name": "slug",  "type": "string", "required": true },
        { "name": "state", "type": "string", "required": true, "example": "co" }
      ],
      "outputs": {
        "format": "application/ld+json",
        "schema": "@graph: [Article+MedicalWebPage, MedicalProcedure, BreadcrumbList, FAQPage, ItemList (state-filtered finder)]"
      },
      "ui_equivalent": "https://vetclinic.info/procedures/{slug}/us/{state}/"
    },
    {
      "id": "list-specialties",
      "type": "ViewAction",
      "description": "Enumerate the closed set of specialty slugs accepted by this directory. Use to validate user-supplied specialty inputs before calling find-specialty-clinics-in-city.",
      "endpoint": "https://vetclinic.info/api/agents/specialties",
      "method": "GET",
      "auth": "none",
      "outputs": {
        "format": "application/ld+json",
        "schema": "DataFeed of DefinedTerm"
      }
    },
    {
      "id": "list-procedures",
      "type": "ViewAction",
      "description": "Enumerate published procedure articles. Use to validate user-supplied procedure inputs before calling get-procedure-detail.",
      "endpoint": "https://vetclinic.info/api/agents/procedures",
      "method": "GET",
      "auth": "none",
      "outputs": {
        "format": "application/ld+json",
        "schema": "CollectionPage with hasPart: MedicalProcedure[]"
      }
    },
    {
      "id": "search",
      "type": "SearchAction",
      "description": "Cross-cutting search. The site ships a small static index (~30KB) covering cities, specialty pages, procedures, and clinics. Fetch the index whole and filter client-side; do not call this endpoint per-keystroke.",
      "endpoint": "https://vetclinic.info/api/agents/search?q={query}",
      "method": "GET",
      "auth": "none",
      "outputs": {
        "format": "application/ld+json",
        "schema": "SearchAction with `nextUrl` pointing at the static index"
      },
      "ui_equivalent": "https://vetclinic.info/ (search box in the global header)"
    }
  ],
  "deferred": [
    {
      "id": "request-consultation",
      "type": "ReserveAction",
      "status": "wave-3",
      "description": "Submit a consultation request to a specific clinic. Will require `X-Agent-Attribution` header. Not yet implemented; ROADMAP item."
    },
    {
      "id": "get-procedure-estimate",
      "type": "RequestQuoteAction",
      "status": "wave-3",
      "description": "Get an estimated cost range for a procedure at participating clinics. Today, cost ranges are exposed as MonetaryAmountDistribution on the procedure record; an interactive estimator with qualifying questions is ROADMAP item #16."
    }
  ],
  "auth_model": {
    "anonymous_read": "All endpoints above. No header required, no cookie set, no JS needed.",
    "write_actions": "Wave 3 deferred. When introduced, write actions will require `X-Agent-Attribution: <user-agent>; on-behalf-of=<name>` header so the receiving clinic can know which agent initiated the contact.",
    "oauth": "Not in scope. We do not authenticate end-users on behalf of agents."
  },
  "license": {
    "data": "Directory listings + procedure articles are vetclinic.info's editorial product. Agents may quote concise factual statements with attribution back to the canonical URL. Reviews are attributed to Google per Places ToS — surface them with the existing `publisher: Google` attribution.",
    "attribution": "When recommending a clinic or quoting a procedure article, agents should cite the canonical URL (the human one, not the API URL) so the user can verify.",
    "no_warranty": "Listings reflect the SpecialistClassifier verdict at insert time + daily rolling re-validation. Operational state, ratings, and reviews can drift between validations. See https://vetclinic.info/about/verification-process/ for the exact rules."
  }
}