{
  "openapi": "3.1.0",
  "info": {
    "title": "File US Taxes public agent API",
    "version": "1.0.0",
    "summary": "Eligibility, prices and waitlist sign-up for assistants.",
    "description": "Public, read-mostly API for File U.S. Taxes LLC (remote federal tax preparation, launching for the 2027 season). It returns eligibility, the fixed price list and joins the waitlist. It never accepts or returns tax documents, Social Security numbers or account numbers. Identity, consent, engagement-letter signing and payment happen with the person in the client portal when it opens. Until then, the hand-off page is the waitlist form at https://fileustaxes.com/get-started/. A tax preparer reviews every return. The same operations are exposed as an MCP server at https://fileustaxes.com/mcp (see /.well-known/mcp/server-card.json).",
    "contact": { "name": "File US Taxes", "email": "info@fileustaxes.com", "url": "https://fileustaxes.com/agents/" },
    "termsOfService": "https://fileustaxes.com/terms-of-service/",
    "x-last-reviewed": "2026-11-18"
  },
  "servers": [{ "url": "https://fileustaxes.com", "description": "Production" }],
  "externalDocs": { "description": "Agent interface documentation (EN)", "url": "https://fileustaxes.com/agents/" },
  "tags": [
    { "name": "eligibility", "description": "Who we serve" },
    { "name": "prices", "description": "Fixed prices (same data as /services.json)" },
    { "name": "signup", "description": "Waitlist sign-up" }
  ],
  "paths": {
    "/api/eligibility": {
      "get": {
        "operationId": "checkEligibility",
        "tags": ["eligibility"],
        "summary": "Check whether we can prepare a federal return",
        "description": "Send either state (two-letter US state code of the person's residence) or abroad=true (a US citizen living outside the United States). Send one, not both. The result is eligible true or false (DC is served). No personal or tax data is needed or accepted.",
        "parameters": [
          { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "examples": ["CA"] }, "description": "Two-letter state code, for example CA." },
          { "name": "abroad", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true only for a US citizen living abroad." }
        ],
        "responses": {
          "200": { "description": "Eligibility result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Eligibility" }, "examples": { "oregon": { "summary": "Oregon (not served)", "value": { "eligible": false, "basis": "state_not_served", "message_en": "No. We do not prepare federal returns for residents of Oregon or Nevada.", "message_es": "No. No preparamos declaraciones federales para residentes de Oregón o Nevada.", "next_step_en": "No next step with us for this state.", "next_step_es": "No hay un siguiente paso con nosotros para este estado.", "languages": ["en", "es"], "scope": "federal returns", "preparer_review": "A tax preparer reviews every return.", "checked_on": "2026-11-18" } } } } } },
          "400": { "description": "Invalid or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "options": { "summary": "CORS preflight", "responses": { "204": { "description": "No content" } } }
    },
    "/api/prices": {
      "get": {
        "operationId": "getPrices",
        "tags": ["prices"],
        "summary": "Fixed prices in USD",
        "description": "Same numbers as https://fileustaxes.com/services.json and /pricing/ (both read one source file). Early rates apply through early_price_through.",
        "parameters": [
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": ["en", "es"], "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Price list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prices" } } } },
          "400": { "description": "Invalid lang", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "options": { "summary": "CORS preflight", "responses": { "204": { "description": "No content" } } }
    },
    "/api/signup": {
      "post": {
        "operationId": "startSignup",
        "tags": ["signup"],
        "summary": "Join the 2027 waitlist",
        "description": "Adds the person to the waitlist (the firm emails them when filing opens). Send consent=true only after the person has said yes. Oregon and Nevada residents are refused. Do not send tax documents or identifiers in any field. The person completes identity checks, the engagement letter and payment in the client portal when it opens.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" }, "examples": { "waitlist": { "value": { "name": "Jane Example", "email": "jane@example.com", "filing_type": "individual", "meeting": "unsure", "lang": "en", "state": "CA", "consent": true } } } } } },
        "responses": {
          "200": { "description": "Waitlisted, refused, or needs a team check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResult" } } } },
          "400": { "description": "Validation error or consent missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limit; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Sign-up not reachable; use handoff_url", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResult" } } } }
        }
      },
      "options": { "summary": "CORS preflight", "responses": { "204": { "description": "No content" } } }
    }
  },
  "components": {
    "schemas": {
      "Eligibility": {
        "type": "object",
        "required": ["eligible", "basis", "message_en", "message_es"],
        "properties": {
          "eligible": { "type": ["boolean", "null"], "description": "true or false." },
          "basis": { "type": "string", "enum": ["state_resident", "us_citizen_abroad", "state_not_served", "needs_team_check"] },
          "message_en": { "type": "string" },
          "message_es": { "type": "string" },
          "next_step_en": { "type": "string" },
          "next_step_es": { "type": "string" },
          "languages": { "type": "array", "items": { "type": "string" } },
          "scope": { "type": "string" },
          "preparer_review": { "type": "string" },
          "checked_on": { "type": "string", "format": "date" }
        }
      },
      "Prices": {
        "type": "object",
        "required": ["currency", "early_price_through", "services"],
        "properties": {
          "currency": { "type": "string", "enum": ["USD"] },
          "early_price_through": { "type": "string", "format": "date" },
          "lang": { "type": "string", "enum": ["en", "es"] },
          "last_reviewed": { "type": "string", "format": "date" },
          "source": { "type": "string", "format": "uri" },
          "pricing_page": { "type": "string", "format": "uri" },
          "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }
        }
      },
      "Service": {
        "type": "object",
        "required": ["id", "name", "description", "prices"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "prices": {
            "type": "object",
            "properties": {
              "no_meeting": { "$ref": "#/components/schemas/PriceTier" },
              "with_30_min_meeting": { "$ref": "#/components/schemas/PriceTier" },
              "flat": { "$ref": "#/components/schemas/PriceTier" }
            }
          },
          "note": { "type": "string" }
        }
      },
      "PriceTier": {
        "type": "object",
        "required": ["early", "regular"],
        "properties": {
          "early": { "type": "number" },
          "regular": { "type": "number" },
          "starting_from": { "type": "boolean" }
        }
      },
      "SignupRequest": {
        "type": "object",
        "required": ["name", "email", "filing_type", "consent"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 120 },
          "email": { "type": "string", "format": "email", "maxLength": 200 },
          "filing_type": { "type": "string", "enum": ["individual", "married", "self-employed", "business", "abroad", "other"] },
          "meeting": { "type": "string", "enum": ["no-meeting", "meeting", "unsure"], "default": "unsure" },
          "lang": { "type": "string", "enum": ["en", "es"], "default": "en" },
          "state": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "Two-letter residence state. Send state or abroad." },
          "abroad": { "type": "boolean", "description": "true only for a US citizen living abroad." },
          "consent": { "type": "boolean", "description": "Must be true, and only after the person agrees to join the waitlist." }
        }
      },
      "SignupResult": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": { "type": "string", "enum": ["waitlisted", "refused", "needs_team_check", "unavailable"] },
          "eligible": { "type": ["boolean", "null"] },
          "basis": { "type": "string" },
          "message_en": { "type": "string" },
          "message_es": { "type": "string" },
          "next_step_en": { "type": "string" },
          "next_step_es": { "type": "string" },
          "handoff_url": { "type": ["string", "null"], "format": "uri" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "retry_after": { "type": "integer" }
        }
      }
    }
  }
}
