openapi: 3.1.0
info:
  title: Donghsin Oriental Construction Public API
  summary: Read-only facts for 東興國際建設有限公司 (donghsin.com)
  description: "Public REST API for 東興國際建設有限公司 (Oriental Construction Co., Ltd., donghsin.com), a Zhubei, Hsinchu County residential developer. Current project: 蒔光APM (Shiguang APM). All documented endpoints are public GET. No API key, OAuth, or session is required. There are no write, webhook, or MCP endpoints. 售價以現場與合約為準。本 API 不提供報價或庫存數字。 Human docs: https://donghsin.com/developers. Canonical facts: https://donghsin.com/llms.txt."
  version: 1.0.0
  contact:
    name: 東興國際建設有限公司 (+886-3-6587442)
    url: "https://donghsin.com/contact"
  license:     name: Factual lookup of donghsin.com content; not a software license
  termsOfService: "https://donghsin.com/terms-of-service"
externalDocs:
  description: Donghsin developer resources — 東興國際建設公開 API
  url: "https://donghsin.com/developers"
servers:
  - url: "https://donghsin.com"
    description: Production (donghsin.com)
tags:
  - name: Donghsin
    description: 東興國際建設有限公司 / Oriental Construction public resources
security: []
paths:
  /api/v1:
    get:
      tags:         - Donghsin
      summary: List API catalog
      description: "Discovery document: publisher, docs, OpenAPI URLs, and reachable GET paths."
      operationId: listCatalog
      security: []
      responses:
        200:
          description: OK
          content:             application/json:               schema:                 $ref: "#/components/schemas/Catalog"
        404:
          description: No resource at this path
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
        405:
          description: Method not allowed. This API is GET-only.
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
  /api/v1/company:
    get:
      tags:         - Donghsin
      summary: Get company
      description: "Legal name, tax ID, NAP, and builder approach. This is Oriental Construction, not Builder.io."
      operationId: getCompany
      security: []
      responses:
        200:
          description: OK
          content:             application/json:               schema:                 $ref: "#/components/schemas/Company"
        404:
          description: No resource at this path
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
        405:
          description: Method not allowed. This API is GET-only.
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
  /api/v1/projects:
    get:
      tags:         - Donghsin
      summary: List projects
      description: Portfolio. The active listing is 蒔光APM. Planning projects have no sale details.
      operationId: listProjects
      security: []
      responses:
        200:
          description: OK
          content:             application/json:               schema:                 $ref: "#/components/schemas/ProjectList"
        404:
          description: No resource at this path
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
        405:
          description: Method not allowed. This API is GET-only.
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
  /api/v1/projects/{slug}:
    get:
      tags:         - Donghsin
      summary: Get project by slug
      description: Use slug shiguang-apm for the current Zhubei HSR District 16-unit 華廈.
      operationId: GetProjectBySlug
      security: []
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            enum:
              - shiguang-apm
              - shiguang-zhuke
              - zhuke-biancheng
      responses:
        200:
          description: OK
          content:             application/json:               schema:                 $ref: "#/components/schemas/ProjectDetail"
        404:
          description: No resource at this path
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
        405:
          description: Method not allowed. This API is GET-only.
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
  /api/v1/contact:
    get:
      tags:         - Donghsin
      summary: Get contact
      description: "Phone, showroom, company address, hours, Google form, and LINE staff links."
      operationId: getContact
      security: []
      responses:
        200:
          description: OK
          content:             application/json:               schema:                 $ref: "#/components/schemas/Contact"
        404:
          description: No resource at this path
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
        405:
          description: Method not allowed. This API is GET-only.
          content:             application/problem+json:               schema:                 $ref: "#/components/schemas/Problem"
components:
  schemas:
    Problem:
      type: object
      additionalProperties: false
      required:
        - type
        - title
        - status
        - detail
        - code
        - hint
        - docs
        - openapi
        - catalog
      properties:
        type:
          type: string
          format: uri
        title:           type: string
        status:           type: integer
        detail:           type: string
        code:
          type: string
          enum:
            - not_found
            - method_not_allowed
            - bad_request
            - not_acceptable
        hint:
          type: string
          description: What an agent should do next
        instance:           type: string
        docs:
          type: string
          format: uri
        openapi:
          type: string
          format: uri
        catalog:
          type: string
          format: uri
    Catalog:
      type: object
      additionalProperties: true
    Company:
      type: object
      additionalProperties: true
    ProjectList:
      type: object
      required:         - projects
      properties:
        projects:
          type: array
          items:             $ref: "#/components/schemas/Project"
    Project:
      type: object
      additionalProperties: true
    ProjectDetail:
      type: object
      additionalProperties: true
    Contact:
      type: object
      additionalProperties: true
