{
  "openapi": "3.1.0",
  "info": {
    "title": "Vagus Lab Public Data API",
    "version": "1.0.0",
    "summary": "Read-only editorial data on vagus nerve stimulation devices and articles.",
    "description": "A static, unauthenticated, read-only API publishing the same editorial data as the Vagus Lab site: our scored device comparison and the index of published research articles. Device scores are editorial scores authored by Vagus Lab, not consumer ratings. Vagus Lab earns affiliate commission on some device purchases; scores are never adjusted by commission.",
    "contact": {
      "name": "Vagus Lab",
      "url": "https://vaguslab.net/contact/"
    },
    "license": {
      "name": "Free to use with attribution to Vagus Lab (https://vaguslab.net)",
      "url": "https://vaguslab.net/terms/"
    }
  },
  "servers": [
    {
      "url": "https://vaguslab.net"
    }
  ],
  "security": [],
  "paths": {
    "/api/public/devices.json": {
      "get": {
        "operationId": "getDevices",
        "summary": "Scored comparison of consumer VNS devices",
        "description": "The six devices from the comparison roundup, ranked by editorial score, with prices, badges, pros and cons, and merchant return terms where the merchant publishes them.",
        "responses": {
          "200": {
            "description": "Device list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceList"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint moved or retired"
          }
        }
      }
    },
    "/api/public/articles.json": {
      "get": {
        "operationId": "getArticles",
        "summary": "Index of published articles",
        "description": "Every published article with its URL, category, and evidence grade. Article bodies are not included: fetch the article URL with Accept: text/markdown for clean full text.",
        "responses": {
          "200": {
            "description": "Article index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleList"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint moved or retired"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DeviceList": {
        "type": "object",
        "required": [
          "publisher",
          "count",
          "devices"
        ],
        "properties": {
          "publisher": {
            "type": "string"
          },
          "publisherUrl": {
            "type": "string",
            "format": "uri"
          },
          "source": {
            "type": "string",
            "format": "uri",
            "description": "Page this data is published on"
          },
          "scoreScale": {
            "type": "string",
            "examples": [
              "0-10"
            ]
          },
          "scoreType": {
            "type": "string",
            "description": "What the score is and is not"
          },
          "disclosure": {
            "type": "string",
            "description": "FTC affiliate disclosure"
          },
          "pricesCheckedAt": {
            "type": "string",
            "format": "date"
          },
          "currency": {
            "type": "string",
            "examples": [
              "USD"
            ]
          },
          "count": {
            "type": "integer"
          },
          "devices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Device"
            }
          }
        }
      },
      "Device": {
        "type": "object",
        "required": [
          "rank",
          "name",
          "brand",
          "editorialScore",
          "priceUsd"
        ],
        "properties": {
          "rank": {
            "type": "integer",
            "description": "1 is the highest scoring device"
          },
          "name": {
            "type": "string"
          },
          "brand": {
            "type": "string"
          },
          "mpn": {
            "type": "string"
          },
          "badge": {
            "type": "string",
            "description": "Use-case label, e.g. Best Overall"
          },
          "editorialScore": {
            "type": "number",
            "minimum": 0,
            "maximum": 10
          },
          "priceUsd": {
            "type": "number"
          },
          "description": {
            "type": "string",
            "description": "What the device physically is"
          },
          "image": {
            "type": "string",
            "format": "uri"
          },
          "pros": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "merchantUrl": {
            "type": "string",
            "format": "uri"
          },
          "reviewUrl": {
            "type": "string",
            "format": "uri",
            "description": "Our analysis of this device"
          },
          "returnTerms": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ReturnTerms"
              },
              {
                "type": "null"
              }
            ],
            "description": "Present only where the merchant publishes the terms and our page states them"
          }
        }
      },
      "ReturnTerms": {
        "type": "object",
        "required": [
          "days",
          "country",
          "buyerPaysReturnShipping",
          "source"
        ],
        "properties": {
          "days": {
            "type": "integer"
          },
          "country": {
            "type": "string"
          },
          "buyerPaysReturnShipping": {
            "type": "boolean"
          },
          "source": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ArticleList": {
        "type": "object",
        "required": [
          "publisher",
          "count",
          "articles"
        ],
        "properties": {
          "publisher": {
            "type": "string"
          },
          "publisherUrl": {
            "type": "string",
            "format": "uri"
          },
          "editorialPolicy": {
            "type": "string",
            "format": "uri"
          },
          "contentNote": {
            "type": "string"
          },
          "markdownNote": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "articles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Article"
            }
          }
        }
      },
      "Article": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "excerpt": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "category": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "evidenceGrade": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "strong",
              "promising",
              "preliminary",
              "theoretical",
              null
            ]
          },
          "hasAffiliateLinks": {
            "type": "boolean"
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}