Skip to main content
Conversational AI chat system for investment-related questions. Maintains context across messages within a session and provides personalized responses based on the user’s financial situation.

Chat Sessions

Create Chat Session

POST /api/investment/:accountId/chat/session

Creates a new chat session for investment conversations.

Path Parameters

accountId
string
required
The unique identifier of the account

Response

success
boolean
Indicates if the request was successful
data
object

Example Request

curl -X POST 'https://api.example.com/api/investment/acc_123/chat/session' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

{
  "success": true,
  "data": {
    "sessionId": "sess_abc123xyz",
    "provider": "openai",
    "createdAt": "2026-03-05T10:30:00.000Z"
  }
}

Send Chat Message

POST /api/investment/:accountId/chat/:sessionId/message

Sends a message to the AI and receives a contextual response.
This endpoint uses AI and counts as 1 AI request per message toward your rate limit.

Path Parameters

accountId
string
required
The unique identifier of the account
sessionId
string
required
The chat session identifier

Request Body

message
string
required
The user’s message (minimum 2 characters after trimming, maximum 5,000 characters)

Response

success
boolean
Indicates if the request was successful
data
object

Example Request

curl -X POST 'https://api.example.com/api/investment/acc_123/chat/sess_abc123/message' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Should I invest more in ETFs or individual stocks?"
  }'

Example Response

{
  "success": true,
  "data": {
    "reply": "For most investors, especially those with a balanced profile like yours, ETFs are generally a better choice. They provide instant diversification, lower risk, and typically have lower fees than buying individual stocks. With your monthly investment of €500, ETFs allow you to spread that across hundreds of companies rather than concentrating risk in just a few stocks. Individual stocks require more research, monitoring, and carry higher risk. I'd recommend allocating 80-90% to diversified ETFs and only 10-20% to individual stocks if you want to learn and have specific companies you believe in.",
    "relatedConcepts": [
      "ETF expense ratios",
      "Diversification strategies",
      "Stock picking vs index investing",
      "Risk management"
    ],
    "needsDisclaimer": true
  }
}

Security Features

Messages are processed through security checks:
  • Input sanitization to prevent injection attacks
  • Content filtering for inappropriate requests
  • Output validation to ensure safe responses
If a message fails security checks, the endpoint returns a 400 error with details.

Get Chat History

GET /api/investment/:accountId/chat/:sessionId/history

Retrieves all messages from a chat session.

Path Parameters

accountId
string
required
The unique identifier of the account
sessionId
string
required
The chat session identifier

Response

success
boolean
Indicates if the request was successful
data
object

Example Request

curl -X GET 'https://api.example.com/api/investment/acc_123/chat/sess_abc123/history' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

{
  "success": true,
  "data": {
    "sessionId": "sess_abc123xyz",
    "messages": [
      {
        "role": "user",
        "content": "What is dollar-cost averaging?",
        "createdAt": "2026-03-05T10:35:00.000Z"
      },
      {
        "role": "assistant",
        "content": "Dollar-cost averaging (DCA) is an investment strategy where you invest a fixed amount of money at regular intervals, regardless of market conditions. For example, investing €500 every month into an ETF. This approach reduces the impact of market volatility and removes the need to time the market.",
        "createdAt": "2026-03-05T10:35:02.000Z"
      },
      {
        "role": "user",
        "content": "Should I invest more in ETFs or individual stocks?",
        "createdAt": "2026-03-05T10:40:00.000Z"
      },
      {
        "role": "assistant",
        "content": "For most investors, especially those with a balanced profile like yours, ETFs are generally a better choice...",
        "createdAt": "2026-03-05T10:40:03.000Z"
      }
    ],
    "messageCount": 4,
    "createdAt": "2026-03-05T10:30:00.000Z",
    "lastMessageAt": "2026-03-05T10:40:03.000Z"
  }
}

Get All Chat Sessions

GET /api/investment/:accountId/chat/sessions

Lists all chat sessions for an account.

Path Parameters

accountId
string
required
The unique identifier of the account

Response

success
boolean
Indicates if the request was successful
data
array
Array of chat session summaries

Example Request

curl -X GET 'https://api.example.com/api/investment/acc_123/chat/sessions' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

{
  "success": true,
  "data": [
    {
      "sessionId": "sess_abc123xyz",
      "provider": "openai",
      "messageCount": 8,
      "createdAt": "2026-03-05T10:30:00.000Z",
      "lastMessageAt": "2026-03-05T11:15:00.000Z"
    },
    {
      "sessionId": "sess_def456uvw",
      "provider": "openai",
      "messageCount": 3,
      "createdAt": "2026-03-04T14:20:00.000Z",
      "lastMessageAt": "2026-03-04T14:25:00.000Z"
    }
  ]
}

Delete Chat Session

DELETE /api/investment/:accountId/chat/:sessionId

Deletes a chat session and all its messages.

Path Parameters

accountId
string
required
The unique identifier of the account
sessionId
string
required
The chat session identifier to delete

Response

success
boolean
Indicates if the request was successful
message
string
Confirmation message

Example Request

curl -X DELETE 'https://api.example.com/api/investment/acc_123/chat/sess_abc123' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

{
  "success": true,
  "message": "Sesión eliminada correctamente"
}

AI Context Integration

The chat system provides the AI with rich context including:
  • Financial Summary: Monthly income, savings capacity, savings rate, emergency fund status, and financial trends
  • Investment Profile: User’s risk profile (conservative/balanced/dynamic) if available
  • Market Data: Real-time prices for S&P 500, MSCI World, Nasdaq, Bitcoin, Ethereum, and currency rates
  • Conversation History: Last 20 messages for continuity
This allows the AI to give personalized, contextually-aware responses about:
  • Investment strategies tailored to the user’s situation
  • Risk-appropriate recommendations
  • Market timing considerations
  • Portfolio allocation advice
  • Educational content at the appropriate level

Session Management

Sessions automatically expire after 30 minutes of inactivity. When a user sends a message:
  • If the session is expired, a new session is automatically created
  • If the session is active, the message is added to the existing conversation
  • Session history is maintained in the database

Error Responses

Common Errors

  • 400 - Invalid message (too short, too long, or failed security check)
  • 401 - Unauthorized (missing or invalid token)
  • 403 - Forbidden (no access to this account)
  • 404 - Session not found
  • 503 - AI service unavailable

Build docs developers (and LLMs) love