openapi: 3.0.0
info:
  title: HNCB De-identification API (via Fusion)
  version: 1.0.0
  description: |
    Fusion-facing contract for the reversible PII de-identification demo.

    - POST /tokenize  — full round trip: de-identify → agent reasons on tokens → restore.
    - POST /restore   — re-identify a tokenized text on its own (egress-only).

    Callers hit the Fusion listener and send only the JSON body; Fusion injects the
    backend `x-api-key`. Direct calls to the backend require `x-api-key` (see ApiKeyAuth).

    Note: if /tokenize already returns `final`, a standalone /restore is only needed
    when the flow is split into ingress-only tokenize + egress restore.

servers:
  - url: https://aus-design.sandbox.fusion.services.axway.com:4443
    description: Fusion listener — send body only; gateway injects the key
  - url: https://hncb-deid.apim-apac-demo.com
    description: Backend (custom domain) — direct calls require x-api-key

paths:
  /tokenize:
    post:
      summary: De-identify a query, reason on tokens, and restore identity (round trip)
      operationId: deidentifyRoundTrip
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - query
              properties:
                query:
                  type: string
                  description: Advisor's natural-language query (may contain PII).
                  example: 請幫我整理王小明最近三個月的理財往來，並給我下次拜訪話術。
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - final
                  - deidentified_prompt
                  - agent_tokenized
                  - session_id
                properties:
                  final:
                    type: string
                    description: Restored answer shown to the advisor (identity re-attached).
                    example: "（客戶：王小明）\n根據最近90天的客戶往來紀錄，以下是建議的拜訪話術重點：…"
                  deidentified_prompt:
                    type: string
                    description: Tokenized prompt sent to the cloud (PII replaced by tokens).
                    example: 請幫我整理CUST_264978最近三個月的理財往來，並給我下次拜訪話術。
                  agent_tokenized:
                    type: string
                    description: The agent's talking points — tokens only, no PII.
                    example: "根據客戶近期活動分析，以下是建議的拜訪話術重點：…"
                  session_id:
                    type: string
                    description: Vault session correlating this request's tokens.
                    example: 9d15023985154d79a477d4e5b8b2c87c
        "400":
          description: Missing/invalid body (query required)
        "401":
          description: Unauthorized (backend-direct call without a valid x-api-key)

  /restore:
    post:
      summary: Restore (detokenize) identity in a tokenized text
      operationId: restoreIdentity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - session_id
                - text
              properties:
                session_id:
                  type: string
                  description: The session_id returned by /tokenize.
                  example: 9d15023985154d79a477d4e5b8b2c87c
                text:
                  type: string
                  description: Tokenized text (e.g. the agent's answer) to re-identify.
                  example: 針對客戶 CUST_264978 的保守型投資組合，建議…
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - final
                  - restored
                properties:
                  final:
                    type: string
                    description: Text with identity re-attached (envelope + inline tokens).
                    example: "（客戶：王小明）\n針對客戶 王小明 的保守型投資組合，建議…"
                  restored:
                    type: integer
                    description: Number of tokens restored for this session.
                    example: 1
        "400":
          description: Missing session_id or text
        "401":
          description: Unauthorized (backend-direct call without a valid x-api-key)

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        Shared secret (`tokenize_api_key`) for direct backend calls; Fusion injects
        it on the gateway path, so Fusion-facing callers omit it.