{
  "openapi": "3.1.0",
  "info": {
    "title": "Toshiko Visa API",
    "version": "1.0.0",
    "description": "Visa requirements where every verified fact links to its official government source, with a verbatim snippet and a last-verified date. Two tiers per answer: `verified` (agent-verified pathway with evidence) and `guidance` (conservative rule-derived matrix that may over-state, never under-state, a requirement). GET /v1/coverage before integrating — it tells you honestly what is verified vs guidance.",
    "contact": {
      "url": "https://toshikovisa.com/developers"
    }
  },
  "servers": [
    {
      "url": "https://toshikovisa.com/api"
    }
  ],
  "paths": {
    "/v1/requirements": {
      "get": {
        "summary": "Visa requirement for a nationality → destination (optionally residence, visa type)",
        "parameters": [
          {
            "name": "nationality",
            "in": "query",
            "required": true,
            "description": "ISO-3166 alpha-2, slug or English name (e.g. IN, india)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "description": "Destination slug/code (thailand, TH), a Schengen member (france) or 'schengen'",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "residence",
            "in": "query",
            "required": false,
            "description": "Country of residence — decides WHERE you apply (defaults to nationality)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Visa-type code (defaults to the destination's visit type)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "api_key",
            "in": "query",
            "required": false,
            "description": "API key (or send X-API-Key header); keyless requests run on the demo tier",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Requirement with tier, outcome, evidence-carrying verified guide when available"
          },
          "404": {
            "description": "Unknown country / uncovered destination"
          }
        }
      }
    },
    "/v1/passports/{code}": {
      "get": {
        "summary": "One passport's visa-need outcome across every covered destination",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ISO-3166 alpha-2, slug or name"
          }
        ],
        "responses": {
          "200": {
            "description": "Per-destination outcomes (guidance tier)"
          },
          "404": {
            "description": "Unknown passport"
          }
        }
      }
    },
    "/v1/guides/{slug}": {
      "get": {
        "summary": "A full verified guide: steps, documents, fees, gotchas — each with official-source evidence",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verified guide"
          },
          "404": {
            "description": "No verified guide for that slug"
          }
        }
      }
    },
    "/v1/coverage": {
      "get": {
        "summary": "Coverage honesty: verified corridors per destination, nationalities covered, freshness ranges",
        "responses": {
          "200": {
            "description": "Coverage report generated from the live content set"
          }
        }
      }
    }
  }
}