{
 "openapi": "3.1.0",
 "info": {
  "title": "Taiwan Company Data API",
  "version": "1.0.0",
  "description": "Taiwan company registry, officers, filings, change history and relationship graph as English-keyed JSON. Same-name links are inferences with confidence. Guide: https://api.easylifehub.net/tw/skill.md",
  "license": {
   "name": "Data: Open Government Data License v1.0 (Taiwan)",
   "url": "https://data.gov.tw/license"
  }
 },
 "servers": [
  {
   "url": "https://api.easylifehub.net/tw"
  }
 ],
 "security": [
  {},
  {
   "apiKey": []
  },
  {
   "bearer": []
  }
 ],
 "paths": {
  "/v1/status": {
   "get": {
    "operationId": "getStatus",
    "summary": "Data month, counts and plans",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Status",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/search": {
   "get": {
    "operationId": "searchCompanies",
    "summary": "Search companies by name fragment or 8-digit ban",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Name fragment (3+ chars uses the index) or 8-digit ban",
      "schema": {
       "type": "string"
      },
      "example": "台灣積體電路"
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "City or county, e.g. 台北市",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "org_type",
      "in": "query",
      "required": false,
      "description": "Chinese organization type, e.g. 股份有限公司",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "active",
      "in": "query",
      "required": false,
      "description": "Only companies in the current tax registry",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Page size (anonymous max 20, keys max 200)",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 200
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "From next_offset",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Results",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}": {
   "get": {
    "operationId": "getCompany",
    "summary": "Company profile with officers, managers, filings and detected changes",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     }
    ],
    "responses": {
     "200": {
      "description": "Company",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Company"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/officers": {
   "get": {
    "operationId": "getOfficers",
    "summary": "Officers of a company",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     },
     {
      "name": "include_former",
      "in": "query",
      "required": false,
      "description": "Include officers no longer listed",
      "schema": {
       "type": "boolean"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Officers",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/related": {
   "get": {
    "operationId": "getRelated",
    "summary": "Related companies via shared officer names (with confidence), legal-entity board seats, same address, branches",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     },
     {
      "name": "min_confidence",
      "in": "query",
      "required": false,
      "description": "0 to 1, default 0.4",
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Max linked companies",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Related",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/graph": {
   "get": {
    "operationId": "getGraph",
    "summary": "Person/company graph (solid = registry fact, dashed = same-name inference)",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     },
     {
      "name": "depth",
      "in": "query",
      "required": false,
      "description": "1 or 2 (2 needs a key)",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 2
      }
     },
     {
      "name": "min_confidence",
      "in": "query",
      "required": false,
      "description": "Default 0.5",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "max_nodes",
      "in": "query",
      "required": false,
      "description": "10 to 400",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Graph",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/financials": {
   "get": {
    "operationId": "getFinancials",
    "summary": "Listed companies: monthly revenue, annual revenue, quarterly statements, dividends, insider holdings",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     }
    ],
    "responses": {
     "200": {
      "description": "Financials",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/group": {
   "get": {
    "operationId": "getGroup",
    "summary": "Inferred corporate group, branches with addresses, board shareholding split",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     }
    ],
    "responses": {
     "200": {
      "description": "Group",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/web": {
   "get": {
    "operationId": "getWebProfile",
    "summary": "Official website and social links with verification level",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     }
    ],
    "responses": {
     "200": {
      "description": "Web profile",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/announcements": {
   "get": {
    "operationId": "getAnnouncements",
    "summary": "Material announcements, newest first",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1 to 500",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Announcements",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/history": {
   "get": {
    "operationId": "getHistory",
    "summary": "Capital, representative and name history from filings, plus officers over time",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     }
    ],
    "responses": {
     "200": {
      "description": "History",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/report": {
   "get": {
    "operationId": "getReport",
    "summary": "Printable due-diligence report (HTML, print to PDF)",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "description": "en or zh",
      "schema": {
       "type": "string",
       "enum": [
        "en",
        "zh"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "HTML report",
      "content": {
       "text/html": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/companies/{ban}/signals": {
   "get": {
    "operationId": "getSignals",
    "summary": "Neutral checks worth a second look",
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     }
    ],
    "responses": {
     "200": {
      "description": "Signals",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/people": {
   "get": {
    "operationId": "getPeopleRoles",
    "summary": "Company roles under an exact registered name, clustered into likely-same-person groups",
    "parameters": [
     {
      "name": "name",
      "in": "query",
      "required": true,
      "description": "Exact full name as registered",
      "schema": {
       "type": "string",
       "minLength": 2,
       "maxLength": 40
      },
      "example": "魏哲家"
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Max roles",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "People",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/filings/setup": {
   "get": {
    "operationId": "listNewCompanies",
    "summary": "Newly approved companies",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "YYYY-MM-DD, default 30 days ago",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "YYYY-MM-DD",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "City prefix of address",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "min_capital",
      "in": "query",
      "required": false,
      "description": "Minimum capital in TWD",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "format",
      "in": "query",
      "required": false,
      "description": "json or csv (csv: pro plan)",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Page size (anonymous max 20, keys max 200)",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 200
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "From next_offset",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Filings",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/filings/change": {
   "get": {
    "operationId": "listChangeFilings",
    "summary": "Approved change filings",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "YYYY-MM-DD",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "YYYY-MM-DD",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "City prefix",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "format",
      "in": "query",
      "required": false,
      "description": "json or csv",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Page size (anonymous max 20, keys max 200)",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 200
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "From next_offset",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Filings",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/changes": {
   "get": {
    "operationId": "listChanges",
    "summary": "Detected month-over-month changes",
    "parameters": [
     {
      "name": "since",
      "in": "query",
      "required": false,
      "description": "YYYY-MM",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "ban",
      "in": "query",
      "required": false,
      "description": "Comma-separated bans (max 100)",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "field",
      "in": "query",
      "required": false,
      "description": "Field prefix: name, address, capital, org_type, hq_ban, tax_registry, officer_joined, officer_left, shares",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Page size (anonymous max 20, keys max 200)",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 200
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "From next_offset",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Changes",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/watches": {
   "get": {
    "operationId": "listWatches",
    "summary": "Your watched companies",
    "security": [
     {
      "apiKey": []
     },
     {
      "bearer": []
     }
    ],
    "responses": {
     "200": {
      "description": "Watches",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   },
   "post": {
    "operationId": "createWatches",
    "summary": "Watch companies and optionally set an HTTPS webhook",
    "security": [
     {
      "apiKey": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "bans": {
          "type": "array",
          "items": {
           "type": "string",
           "pattern": "^\\d{8}$"
          },
          "maxItems": 500
         },
         "webhook_url": {
          "type": "string",
          "format": "uri"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Created"
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/watches/{ban}": {
   "delete": {
    "operationId": "deleteWatch",
    "summary": "Stop watching",
    "security": [
     {
      "apiKey": []
     },
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "ban",
      "in": "path",
      "required": true,
      "description": "8-digit 統一編號",
      "schema": {
       "type": "string",
       "pattern": "^\\d{8}$"
      },
      "example": "22099131"
     }
    ],
    "responses": {
     "200": {
      "description": "Removed"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/watches/events": {
   "get": {
    "operationId": "listWatchEvents",
    "summary": "Detected changes for your watched companies",
    "security": [
     {
      "apiKey": []
     },
     {
      "bearer": []
     }
    ],
    "parameters": [
     {
      "name": "since",
      "in": "query",
      "required": false,
      "description": "YYYY-MM",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Page size (anonymous max 20, keys max 200)",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 200
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "From next_offset",
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Events",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/keys": {
   "post": {
    "operationId": "createFreeKey",
    "summary": "Get a free API key (shown once)",
    "security": [
     {}
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "label": {
          "type": "string",
          "maxLength": 80
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Key issued"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "x-api-key"
   },
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   }
  },
  "responses": {
   "Error": {
    "description": "Error",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "object",
         "required": [
          "code",
          "message"
         ],
         "properties": {
          "code": {
           "type": "string"
          },
          "message": {
           "type": "string"
          },
          "retry_after": {
           "type": "integer"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "schemas": {
   "Company": {
    "type": "object",
    "properties": {
     "ban": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "org_type": {
      "type": [
       "string",
       "null"
      ]
     },
     "org_type_en": {
      "type": [
       "string",
       "null"
      ]
     },
     "capital_twd": {
      "type": [
       "integer",
       "null"
      ]
     },
     "setup_date": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "address": {
      "type": [
       "string",
       "null"
      ]
     },
     "city": {
      "type": [
       "string",
       "null"
      ]
     },
     "hq_ban": {
      "type": [
       "string",
       "null"
      ]
     },
     "industries": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "code": {
         "type": "string"
        },
        "name": {
         "type": "string"
        }
       }
      }
     },
     "registry_presence": {
      "type": "object",
      "properties": {
       "tax_registry": {
        "type": "boolean"
       },
       "company_registry": {
        "type": "boolean"
       },
       "as_of": {
        "type": "string"
       },
       "note": {
        "type": "string"
       }
      }
     },
     "officers": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "managers": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "filings": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "detected_changes": {
      "type": "array",
      "items": {
       "type": "object"
      }
     }
    }
   }
  }
 }
}