{
  "openapi": "3.1.0",
  "info": {
    "title": "VYE US launch newsletter API",
    "version": "1.0.0",
    "description": "A small, unauthenticated endpoint for requesting VYE US launch-newsletter updates. Call it only after the person has explicitly asked to subscribe. This is not a product, ordering, payment, customer-account, or commerce API. Versioning uses the /api/v1/ URL path and X-API-Version response header. Version 1 is currently active and is not deprecated. Before retirement or a breaking change, VYE will publish the deprecation status here and signal it with Deprecation and Sunset response headers; clients should not assume an unannounced retirement. The endpoint permits 10 requests per IP per hour and 3 requests per email address per 24 hours, returning 429 with Retry-After and RateLimit headers when a limit is exceeded."
  },
  "servers": [
    {
      "url": "https://getvye.com"
    }
  ],
  "paths": {
    "/api/v1/newsletter-signup": {
      "get": {
        "operationId": "getVyeNewsletterApiMetadata",
        "x-api-version": "1",
        "summary": "Read newsletter API metadata",
        "description": "Returns the public operation, consent boundary, and rate-limit policy without reading or changing subscriber data.",
        "responses": {
          "200": {
            "description": "Public metadata for the newsletter endpoint.",
            "headers": {
              "X-API-Version": {
                "$ref": "#/components/headers/XApiVersion"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewsletterApiMetadata"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "subscribeToVyeLaunchNewsletter",
        "x-api-version": "1",
        "summary": "Request VYE US launch-newsletter updates",
        "description": "Submit an email address only when the person has clearly requested VYE launch-newsletter updates. Do not call this operation to market to someone without their request, and do not treat it as a purchase or product-availability operation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewsletterSignupRequest"
              },
              "example": {
                "email": "name@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The newsletter request was accepted.",
            "headers": {
              "X-API-Version": {
                "schema": {
                  "type": "string",
                  "example": "1"
                  }
                },
                "RateLimit-Limit": {
                  "$ref": "#/components/headers/RateLimitLimit"
                },
                "RateLimit-Remaining": {
                  "$ref": "#/components/headers/RateLimitRemaining"
                },
                "RateLimit-Reset": {
                  "$ref": "#/components/headers/RateLimitReset"
                }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewsletterSignupResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request body or email address is invalid.",
            "headers": {
              "X-API-Version": {
                "$ref": "#/components/headers/XApiVersion"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "405": {
            "description": "Only POST is supported.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                }
              },
              "X-API-Version": {
                "$ref": "#/components/headers/XApiVersion"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "The request exceeded the IP or email rate limit.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "X-API-Version": {
                "$ref": "#/components/headers/XApiVersion"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "503": {
            "description": "The newsletter service is temporarily unavailable.",
            "headers": {
              "X-API-Version": {
                "$ref": "#/components/headers/XApiVersion"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "The newsletter request could not be completed.",
            "headers": {
              "X-API-Version": {
                "$ref": "#/components/headers/XApiVersion"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "XApiVersion": {
        "description": "The major version of the versioned newsletter API.",
        "schema": {
          "type": "string",
          "example": "1"
        }
      },
      "RateLimitLimit": {
        "description": "The configured request limits: 10 per IP per hour and 3 per email address per 24 hours.",
        "schema": {
          "type": "string",
          "example": "10;w=3600, 3;w=86400"
        }
      },
      "RateLimitRemaining": {
        "description": "The remaining requests in the more restrictive applicable window.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 9
        }
      },
      "RateLimitReset": {
        "description": "Unix time when the later applicable rate-limit window resets.",
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": 1788800400
        }
      },
      "RetryAfter": {
        "description": "Number of seconds to wait before retrying after a 429 response.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "example": 3600
        }
      }
    },
    "schemas": {
      "NewsletterSignupRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "The email address of a person who explicitly requested launch updates."
          }
        }
      },
      "NewsletterSignupResponse": {
        "type": "object",
        "required": [
          "message",
          "new"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "new": {
            "type": "boolean",
            "description": "Whether this request created a new newsletter record."
          }
        }
      },
      "NewsletterApiMetadata": {
        "type": "object",
        "required": [
          "name",
          "api_version",
          "operation",
          "consent_required",
          "rate_limits",
          "documentation_url"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "api_version": {
            "type": "string"
          },
          "operation": {
            "type": "string"
          },
          "consent_required": {
            "type": "boolean"
          },
          "rate_limits": {
            "type": "object",
            "required": ["per_ip", "per_email"],
            "properties": {
              "per_ip": {
                "$ref": "#/components/schemas/RateLimitPolicy"
              },
              "per_email": {
                "$ref": "#/components/schemas/RateLimitPolicy"
              }
            }
          },
          "documentation_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "RateLimitPolicy": {
        "type": "object",
        "required": ["limit", "window_seconds"],
        "properties": {
          "limit": {
            "type": "integer",
            "minimum": 1
          },
          "window_seconds": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code",
          "resolution",
          "documentation_url"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "resolution": {
            "type": "string"
          },
          "documentation_url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    },
    "responses": {
      "InvalidRequest": {
        "description": "The request body or email address is invalid.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "Only POST is supported.",
        "headers": {
          "Allow": {
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The newsletter service is temporarily unavailable.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "SignupFailed": {
        "description": "The newsletter request could not be completed.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    }
  }
}