{
  "openapi": "3.1.0",
  "info": {
    "title": "Findvice API",
    "version": "1.0.0",
    "description": "Buy / Wait / Avoid decisions from Findvice. Invite-only: a key works only after Findvice has approved a plan for your account. Responses carry Findvice's own judgment and reasons; they never include provider prices, offers or store links."
  },
  "servers": [{ "url": "https://findvice.com/api/v1" }],
  "security": [{ "bearerKey": [] }],
  "paths": {
    "/me": {
      "get": {
        "summary": "Your key, limits and usage",
        "responses": { "200": { "description": "The key label, its limits and this month's request count." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/Limited" } }
      }
    },
    "/usage": {
      "get": {
        "summary": "Requests per day this month",
        "responses": { "200": { "description": "Limits, the month's total and one entry per day with requests and rejected counts." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/Limited" } }
      }
    },
    "/decisions": {
      "post": {
        "summary": "Decide Buy, Wait or Avoid for one product",
        "description": "Identify the product with at least one of url, query, gtin or modelNumber. Send an Idempotency-Key header (8 to 64 letters, digits, dashes or underscores) to retry safely: the same key and request returns the stored decision with Idempotent-Replay: true and no second analysis; the same key with a different request returns 422.",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" } } } },
        "responses": {
          "201": { "description": "A new decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionEnvelope" } } } },
          "200": { "description": "A replay of an earlier decision for the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionEnvelope" } } } },
          "400": { "description": "The request is invalid." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "413": { "description": "The request body is larger than 4 KB." },
          "415": { "description": "Send application/json." },
          "422": { "description": "The product could not be verified, has no current offers, or the Idempotency-Key was used with a different request." },
          "429": { "$ref": "#/components/responses/Limited" },
          "503": { "description": "Temporarily unavailable. Retry with the same Idempotency-Key." }
        }
      }
    },
    "/decisions/{id}": {
      "get": {
        "summary": "A decision your key created earlier",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "The stored decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No decision with that id exists for this key." }, "429": { "$ref": "#/components/responses/Limited" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "bearerKey": { "type": "http", "scheme": "bearer", "description": "Your Findvice API key, from the account page." } },
    "responses": {
      "Unauthorized": { "description": "The key is missing, invalid or revoked." },
      "Limited": { "description": "Per-minute limit or monthly allowance reached. See Retry-After." }
    },
    "schemas": {
      "DecisionRequest": {
        "type": "object", "additionalProperties": false,
        "properties": {
          "url": { "type": "string" }, "query": { "type": "string" }, "gtin": { "type": "string" }, "modelNumber": { "type": "string" },
          "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" },
          "waitingHorizonDays": { "type": "integer", "minimum": 1, "maximum": 3650 },
          "userContext": { "type": "object", "additionalProperties": false, "properties": { "targetPriceMinor": { "type": "string" }, "maxBudgetMinor": { "type": "string" } } }
        }
      },
      "Decision": {
        "type": "object",
        "required": ["id", "decision", "score", "confidence", "currency", "product", "reasons", "analyzedAt", "engineVersion", "rulesVersion"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "decision": { "type": "string", "enum": ["BUY", "WAIT", "AVOID"] },
          "score": { "type": "number", "minimum": 0, "maximum": 100 },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "currency": { "type": "string" },
          "product": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "brand": { "type": "string" }, "modelNumber": { "type": "string" } } },
          "recommendedAction": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string" }, "message": { "type": "string" } } },
          "reasons": { "type": "array", "items": { "type": "object", "required": ["type", "explanation"], "properties": { "type": { "type": "string" }, "explanation": { "type": "string" } } } },
          "analyzedAt": { "type": "string", "format": "date-time" },
          "engineVersion": { "type": "string" },
          "rulesVersion": { "type": "string" }
        }
      },
      "DecisionEnvelope": { "type": "object", "required": ["ok", "data"], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Decision" } } }
    }
  }
}
