Safe AI Workbench Developer DocsAI-powered workspace with PHI protectionHIPAA-compliant API

AI Chat API

Execute AI tasks with automatic PHI detection, policy enforcement, and conversation continuity

POST /api/ai/chat

Execute an AI task with optional file input, conversation context, and customizable temperature. All requests automatically scan for PHI and enforce configured policies.

Authentication Required

Include your API key or JWT token as a Bearer token in the Authorization header.

Request Body

Parameter	Type	Required	Description
`conversationId`	string	Yes	Use "new" for new conversation or existing conversation ID to continue
`taskId`	string	Yes	ID of the AI task to execute (e.g., "meeting-summarizer", "policy-translator")
`variables`	object	No*	Key-value pairs for task variables (e.g., { content: "...", tone: "professional" }). Required if not using fileHash.
`fileHash`	string	No*	Hash of uploaded file from /api/files/upload. Required for file-based tasks.
`temperature`	number	No	0.0-1.0. Controls randomness. Default varies by task (typically 0.7).

* Either variables or fileHash must be provided.

Example Request

POST /api/ai/chat
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "conversationId": "new",
  "taskId": "meeting-summarizer",
  "variables": {
    "content": "Today's meeting covered Q3 budget planning. Key points: marketing budget increase of 15%, new hire freeze in engineering, sales targets adjusted upward by 20%."
  },
  "temperature": 0.7
}

Response (200 OK)

Field	Type	Description
`completion`	string	AI-generated response text. Null if request was blocked by policy.
`conversationId`	string	ID for this conversation. Use in subsequent requests to continue the conversation.
`phiDetected`	boolean	Whether Protected Health Information was detected in the input.
`phiEntities`	array	List of detected PHI entities with type, text, position, and confidence score.
`policyViolations`	array	Policies that triggered (warn, block, or redact actions).
`metadata`	object	Model info, token usage, processing time, task details.

Example Response

{
  "completion": "Meeting Summary - Q3 Budget Planning\n\nKey Decisions:\n- Marketing budget approved for 15% increase\n- Engineering hiring freeze implemented\n- Sales targets raised by 20%\n\nAction Items:\n1. Finance to finalize marketing allocation by EOW\n2. HR to communicate hiring freeze to department heads\n3. Sales team to review revised quota assignments",
  "conversationId": "conv_abc123def456",
  "phiDetected": false,
  "phiEntities": [],
  "policyViolations": [],
  "metadata": {
    "model": "gpt-4o",
    "temperature": 0.7,
    "tokensUsed": 245,
    "estimatedCost": 0.0049,
    "taskId": "meeting-summarizer",
    "taskName": "Summarize Meeting Notes",
    "processingTime": 1.2,
    "timestamp": "2024-01-15T10:30:45Z"
  }
}

Response with PHI Detection

{
  "completion": "Summary: The document discusses [REDACTED]...",
  "conversationId": "conv_xyz789",
  "phiDetected": true,
  "phiEntities": [
    {
      "type": "PERSON",
      "text": "John Smith",
      "start": 15,
      "end": 25,
      "score": 0.95
    },
    {
      "type": "US_SSN",
      "text": "123-45-6789",
      "start": 50,
      "end": 61,
      "score": 1.0
    }
  ],
  "policyViolations": [
    {
      "policyId": "pol_redact_ssn",
      "policyName": "Redact Social Security Numbers",
      "action": "redact",
      "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b",
      "matches": ["123-45-6789"]
    }
  ],
  "metadata": {
    "model": "gpt-4o",
    "tokensUsed": 312,
    "taskId": "document-summarizer"
  }
}

Response with Policy Block

{
  "completion": null,
  "conversationId": "conv_blocked123",
  "phiDetected": true,
  "phiEntities": [
    {
      "type": "CREDIT_CARD",
      "text": "4532-1234-5678-9010",
      "start": 42,
      "end": 61,
      "score": 1.0
    }
  ],
  "policyViolations": [
    {
      "policyId": "pol_block_cc",
      "policyName": "Block Credit Card Numbers",
      "action": "block",
      "pattern": "\\b(?:\\d{4}[- ]?){3}\\d{4}\\b",
      "matches": ["4532-1234-5678-9010"],
      "message": "Request blocked due to credit card number detection"
    }
  ],
  "error": "Request blocked by policy: Block Credit Card Numbers"
}

⚠️ Important: When a "block" policy triggers, completion is null and the request is not sent to the AI model.

Error Responses

400 Bad Request

Invalid request body or missing required parameters

{ "error": "taskId is required" }

401 Unauthorized

Missing or invalid API key/JWT token

{ "error": "Authentication required" }

403 Forbidden

User lacks permission to access the specified task

{ "error": "Task not available for your group" }

404 Not Found

Task ID does not exist or file hash not found

{ "error": "Task not found: invalid-task-id" }

429 Too Many Requests

Rate limit exceeded (100 requests/minute)

{ "error": "Rate limit exceeded. Retry after 60 seconds" }

500 Internal Server Error

AI model error or server failure

{ "error": "AI service unavailable. Please try again" }

Usage with File Uploads

For tasks that require files (contract-summarizer, resume-parser, etc.), upload the file first, then reference the fileHash:

// Step 1: Upload file
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const uploadRes = await fetch('/api/files/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: formData
});
const { fileHash } = await uploadRes.json();

// Step 2: Process with AI
const chatRes = await fetch('/api/ai/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    conversationId: 'new',
    taskId: 'contract-summarizer',
    fileHash: fileHash  // Use fileHash instead of variables
  })
});