Send Chat Message

​

Authentication & headers

The two authentication methods (bearerAuth and deviceAuth) are mutually exclusive—choose one based on whether the user is registered or a guest. The playground will show the appropriate fields based on your selection.

​

Guest/device auth flow (deviceAuth option)

• x-device-id (required): Unique device identifier
• x-platform (required): One of android, ios, or web
• x-user-id (optional): User ID returned from GET /app/launch
• x-user-email (optional): Email hint for linking
• x-user-phone (optional): Phone hint in E.164 format

1. Launch – call GET /app/launch with x-device-id and x-platform. The response returns a synthetic userId (e.g. U-813e62a0-...) even when no Auth0 account exists.
2. Chat as guest – send POST /api/v1/ai/chat with the device headers plus x-user-id returned from the launch step. Requests work immediately until the free counter reaches the configured FREE_MESSAGE_THRESHOLD (default 100).
3. Hit the limit – on the (threshold + 1) request the API responds with 429 FREE_LIMIT_EXCEEDED and the payload includes error.details.isGuest = true and error.details.requiresSignup = true. Frontends should show the signup modal at this point.
4. Continue after signup – once the user signs up and receives an Auth0 access token, switch to the bearer header. The userId and conversation history stay intact because the backend links the identity via the stored device metadata.

Device headers are treated with the same chat-rate limiting and audit trails as JWTs. Spoofed or missing headers are rejected with 401 UNAUTHORIZED.

​

Request body

​

Masked pre-prompts

​

Guest vs registered usage messaging

{
  "success": false,
  "error": {
    "message": "Please sign up to continue chatting and unlock more features!",
    "code": "FREE_LIMIT_EXCEEDED",
    "details": {
      "currentCount": 100,
      "threshold": 100,
      "remaining": 0,
      "isGuest": true,
      "requiresSignup": true
    }
  },
  "meta": { "...": "..." }
}

​

Responses

​

Buffered JSON

{
  "success": true,
  "data": {
    "conversationId": "665f5e6fcb6e4c73dc6dca01",
    "messageId": "665f5e91cb6e4c73dc6dca05",
    "role": "assistant",
    "content": "Equity funds carry higher volatility...",
    "model": "gpt-4o-mini",
    "tokenCount": 812,
    "toolCalls": [
      {
        "toolName": "portfolio_lookup",
        "args": { "accountId": "abc123" },
        "result": { "holdings": 4 }
      }
    ]
  },
  "meta": {
    "timestamp": "2025-12-01T12:00:00.000Z",
    "requestId": "req_abc"
  }
}

​

Streaming (SSE)

• {"type":"token","content":"..."} – incremental tokens.
• {"type":"toolCall","toolName":"...","args":{...}} – tool invocation start.
• {"type":"toolResult","toolName":"...","result":{...}} – tool output.
• {"type":"done","conversationId":"...","messageId":"...","tokenCount":123,"meta":{"timestamp":"...","streaming":true,"durationMs":1400}}
• {"type":"error","message":"Streaming failed","error":"..."} – terminal failures.

​

Error codes

​

Example calls

​

Authenticated user with streaming (default)

curl -N -X POST https://api.handauncle.com/api/v1/ai/chat \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "message": "Please summarise my portfolio",
        "conversationId": "665f5e6fcb6e4c73dc6dca01"
      }'

Note: No X-Stream-Response header needed—streaming is the default behavior.

​

Guest/device auth with streaming (default)

curl -N -X POST https://api.handauncle.com/api/v1/ai/chat \
  -H 'x-device-id: ios-device-3f92' \
  -H 'x-user-id: U-813e62a0-a3fc-4c7e-bf4e-3f915d9e9f10' \
  -H 'x-platform: ios' \
  -H 'Content-Type: application/json' \
  -d '{ "message": "Hello from a guest!" }'

​

Non-streaming (buffered JSON response)

curl -X POST https://api.handauncle.com/api/v1/ai/chat \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'X-Stream-Response: false' \
  -H 'Content-Type: application/json' \
  -d '{ "message": "What is a mutual fund?" }'