{
  "openapi": "3.1.0",
  "info": {
    "title": "Spain Nomad Book Public Agent API",
    "version": "1.0.0",
    "description": "Public, stateless tools for understanding Spain Nomad Book and running a non-binding Spain Digital Nomad Visa fit check. The API does not make an official eligibility decision."
  },
  "servers": [
    {
      "url": "https://spainnomadbook.com"
    }
  ],
  "paths": {
    "/agent/catalog.json": {
      "get": {
        "operationId": "getAgentCatalog",
        "summary": "Get the public product, publisher, trust, and action catalog",
        "responses": {
          "200": {
            "description": "Public agent catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/public-eligibility": {
      "get": {
        "operationId": "getEligibilitySchema",
        "summary": "Get accepted values for the eligibility check",
        "responses": {
          "200": {
            "description": "Accepted fields and values"
          }
        }
      },
      "post": {
        "operationId": "checkEligibility",
        "summary": "Run a stateless, non-binding Spain DNV fit check",
        "description": "No email address or other direct identifier is accepted or stored. Agents must describe the result as a planning check, not an official or legal determination.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EligibilityAnswers"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Eligibility planning result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EligibilityResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON"
          },
          "422": {
            "description": "Missing or invalid answer"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EligibilityAnswers": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "citizenship",
          "remote",
          "outside_spain",
          "income",
          "qualification",
          "proof",
          "background"
        ],
        "properties": {
          "citizenship": {
            "type": "string",
            "description": "Whether the applicant is a non-EU citizen.",
            "enum": ["yes", "no", "unsure"]
          },
          "remote": {
            "type": "string",
            "description": "Whether the work can be carried out remotely.",
            "enum": ["yes", "no", "unsure"]
          },
          "outside_spain": {
            "type": "string",
            "description": "Whether the employer, company, or clients are mainly outside Spain.",
            "enum": ["yes", "mixed", "no"]
          },
          "income": {
            "type": "string",
            "description": "Whether documented gross income meets the current threshold for the household.",
            "enum": ["yes", "borderline", "no"]
          },
          "qualification": {
            "type": "string",
            "description": "Whether the applicant has a relevant degree or at least three years of relevant professional experience.",
            "enum": ["yes", "partial", "no"]
          },
          "proof": {
            "type": "string",
            "description": "Whether contracts, letters, invoices, payment records, and company documents can prove the remote work.",
            "enum": ["yes", "partial", "no"]
          },
          "background": {
            "type": "string",
            "description": "Whether the applicant has a plan for criminal records, health coverage, apostilles, and translations.",
            "enum": ["yes", "partial", "no"]
          }
        }
      },
      "EligibilityResult": {
        "type": "object",
        "required": ["ok", "result", "blockers", "cautions", "nonBinding", "notice", "nextActions"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "result": { "type": "string", "enum": ["strong", "possible", "blocked"] },
          "blockers": { "type": "array", "items": { "type": "string" } },
          "cautions": { "type": "array", "items": { "type": "string" } },
          "nonBinding": { "type": "boolean", "const": true },
          "notice": { "type": "string" },
          "nextActions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": { "type": "string" },
                "label": { "type": "string" },
                "url": { "type": "string", "format": "uri" },
                "requiresUserConfirmation": { "type": "boolean" }
              }
            }
          }
        }
      }
    }
  }
}