openapi: 3.0.3
info:
  title: HNCB De-identification API (tokenize / restore)
  version: 1.0.0
  description: |
    Ingress/egress transforms for the reversible PII de-identification round trip.

    Two access paths:
    - **Direct to the backend** (`hncb-deid.apim-apac-demo.com`): the caller MUST send
      the `x-api-key` shared secret (this spec's `ApiKeyAuth`).
    - **Via Fusion** (the gateway listener): the gateway injects `x-api-key` on the
      backend leg, so the portal/UI caller sends only the JSON body — no key. For that
      path, treat the security requirement as satisfied by the gateway.

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

# Backend-direct requirement. Fusion callers omit the header (the gateway adds it).
security:
  - ApiKeyAuth: []

paths:
  /tokenize:
    post:
      summary: Tokenize a query (de-identify PII before it leaves for the cloud)
      operationId: tokenizeQuery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  example: 請幫我整理王小明最近三個月的理財往來，並給我下次拜訪話術。
      responses:
        "200":
          description: Successful tokenization response
          content:
            application/json:
              schema:
                type: object
                properties:
                  deidentified_prompt:
                    type: string
                    description: The query with PII replaced by tokens.
                    example: 請幫我整理CUST_264978最近三個月的理財往來，並給我下次拜訪話術。
                  session_id:
                    type: string
                    description: Correlates this request's tokens for later /restore.
                    example: 9d15023985154d79a477d4e5b8b2c87c
                  tokens:
                    type: array
                    items:
                      type: object
                      properties:
                        token:
                          type: string
                          example: CUST_264978
                        type:
                          type: string
                          description: Entity type detected (PERSON, TW_ROC_ID).
                          example: PERSON
        "400":
          description: Missing/invalid body (query required)
        "401":
          description: Unauthorized (missing/invalid API key)
        "502":
          description: Detector unavailable

  /restore:
    post:
      summary: Restore (detokenize) identity in a tokenized response
      operationId: restoreIdentity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              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: Successful restore response
          content:
            application/json:
              schema:
                type: object
                properties:
                  final:
                    type: string
                    description: Text with identity re-attached (envelope + inline tokens).
                    example: |
                      （客戶：王小明）
                      針對客戶 王小明 的保守型投資組合，建議…
                  restored:
                    type: integer
                    description: Number of tokens restored for this session.
                    example: 1
        "400":
          description: Missing session_id or text
        "401":
          description: Unauthorized (missing/invalid API key)

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        Shared secret (`tokenize_api_key`). Required for direct backend calls;
        injected by Fusion on the gateway path.