---
title: "AI Chat"
method: POST
path: "/api/ai/chat"
tags: ["AI Chat"]
---

# AI Chat

`POST /api/ai/chat`

Send a prompt to an LLM with automatic PII encoding/decoding. The prompt is encoded before reaching the LLM, and the LLM's response is decoded back to original values.

The full pipeline is:
1. Your prompt is scanned for PII
2. PII is replaced with Privacy Twins
3. The encoded prompt is sent to the LLM
4. The LLM response (containing Privacy Twins) is decoded
5. You receive both the raw LLM response and the decoded version

**SDK Usage:**
```typescript
const result = await client.chatWithAI({
  prompt: 'Analyze credit history for John Doe at john@company.com',
  model: 'gemini-2.0-flash-exp',
  provider: 'vertex'
});
```

## Request body

- AIChatRequest
  - `prompt` string, required — User prompt (will be automatically encoded to remove PII before reaching the LLM)
  - `conversationHistory` ConversationMessage[] — Previous messages for multi-turn conversation context
    - `role` 'user' | 'assistant'
    - `content` string
    - `encoded` boolean — Whether this message content contains Privacy Twins (encoded) rather than original PII
  - `sessionId` string — Session tracking ID for multi-turn conversations
  - `sessionContinuationIds` string[] — Continuation IDs from prior conversation turns (enables cross-turn decoding)
  - `model` string — LLM model name
  - `provider` 'vertex' | 'aws' | 'mock' — LLM provider
  - `temperature` number, double — Generation temperature (higher = more creative)
  - `maxTokens` integer — Maximum tokens in the LLM response

## Response `200`

AI chat response with decoded PII

- AIChatResponse
  - `success` boolean
  - `originalPrompt` string — The original user prompt (with real PII)
  - `encodedPrompt` string — The prompt sent to the LLM (PII replaced with Privacy Twins)
  - `llmResponse` string — Raw LLM response (contains Privacy Twins)
  - `decodedResponse` string — Final response with Privacy Twins decoded back to original values
  - `continuationId` string
  - `encoding` object
    - `transformations` Transformation[]
      - `originalHash` string — Cryptographic hash of the original value
      - `twinHash` string — Cryptographic hash of the twin value
      - `entityType` 'PERSON' | 'EMAIL_ADDRESS' | 'PHONE_NUMBER' | 'US_SSN' | 'DATE_TIME' | 'LOCATION' | 'CREDIT_CARD' | 'IP_ADDRESS' | 'IBAN_CODE' | 'US_PASSPORT' | 'US_DRIVER_LICENSE' | 'NRP' | 'MEDICAL_LICENSE' | 'URL' — Type of PII entity detected
      - `catalogItemId` string — Internal catalog item identifier
      - `position` object
        - `start` integer — Start character index in the original text
        - `end` integer — End character index in the original text
      - `score` number, double — Detection confidence score (0.0–1.0)
      - `original` string — Original PII value (available for local decoding)
      - `twin` string — Synthetic Privacy Twin value
      - `components` TransformationComponent[] — Sub-part breakdowns (e.g., first name, last name)
        - `original` string — Original sub-part value
        - `twin` string — Twin sub-part value
        - `type` 'FIRST_NAME' | 'LAST_NAME' | 'CITY' | 'STATE' | 'DATE_FULL_FORMAT' | 'MONTH_NAME' | 'DAY' | 'YEAR' — Component type
    - `statistics` EncodingStatistics
      - `originalLength` integer — Character count of original input
      - `encodedLength` integer — Character count of encoded output
      - `piiEntitiesDetected` integer — Number of PII entities found
      - `transformationsApplied` integer — Number of transformations applied
      - `processingTimeMs` number — Server-side processing time in milliseconds
  - `llm` object
    - `model` string
    - `provider` string
    - `finishReason` string
    - `metadata` object
      - `promptTokens` integer
      - `completionTokens` integer
      - `totalTokens` integer
  - `decoding` object
    - `twinsDecoded` integer
    - `transformations` DecodedTransformation[]
      - `twin` string — The Privacy Twin value
      - `original` string — The original PII value
      - `entityType` string — Type of PII entity
      - `decrypted` boolean — Whether decryption was successful
      - `catalogItemId` string
  - `processingTimeMs` number

## Other responses

- `401` — Authentication failed or token expired
- `403` — Trial expired or subscription required

## Changes

- **2026-08-20** `0e1db3b6bc7c` — 3 breaking, 17 info
  - added the new required request property `prompt`
  - the request's body type/format changed from ``/`` to `object`/``
  - the response's body type/format changed from ``/`` to `object`/`` for status `200`
  - added the new optional request property `conversationHistory`
  - …16 more
- **2026-03-07** `f19009a654f5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/privacypal/apis/privacypal-api/changes/api/ai/chat/post.md)

---

[API](https://skmtc.dev/privacypal/apis/privacypal-api.md) · [All operations](https://skmtc.dev/privacypal/apis/privacypal-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/privacypal/privacypal-api/revisions/0e1db3b6bc7c/schema)