Chat API – /api/v1/chat

Use this endpoint to send user messages to the PetaAI Chatbot engine.

URL

POST https://api.petameta.com/api/v1/chat

Headers

Content-Type: application/json
X-API-Key: YOUR_BACKEND_API_KEY

Request Body

{
  "user_id": "test_user_001",
  "session_id": "sess_test_001",
  "message": "Hi, I need help",
  "metadata": {
    "channel": "web_widget",
    "source": "cashbridge.com.au"
  }
}

Response (Success)

{
  "success": true,
  "message": "No worries — once an application is submitted, it can’t be changed directly...",
  "request_id": "req_1763595158_9631c3cc",
  "user_id": "test_user_001",
  "timestamp": "2025-11-19T23:32:38.702736",
  "intent": "human_handover_candidate",
  "confidence": 0.82,
  "requires_handover": true,
  "handover_priority": "medium",
  "handover_reason": "Ambiguous loan calculation discrepancy",
  "entities": {
    "amount_requested": "1600",
    "amount_detected": "1200"
  },
  "suggested_actions": [
    "Connect to human agent",
    "Provide application number"
  ],
  "processing_time": 0.0134
}

Response (Error)

{
  "success": false,
  "error": "Invalid API Key",
  "code": "AUTH_INVALID_KEY",
  "request_id": "req_1763595158",
  "timestamp": "2025-11-19T23:32:38.702736"
}

Status Codes

Status	Meaning
200	Successful request
400	Bad request / Missing fields
401	Invalid or missing API key
429	Rate limit exceeded
500	Internal server error

Rate Limiting

• 60 requests per minute per API key
• Exceeding limit returns:
  429 Too Many Requests

Features Returned

intent

Classification result of the message:

• greeting
• loan_calculation
• payment_issue
• human_handover_candidate
• unknown

requires_handover

When true, your system should route the user to a human agent.

suggested_actions

Quick actions for UI buttons (e.g., "Check Eligibility", "Show Plans", "Connect to Support").