Chat API

The Chat API allows you to interact with Oliver, our AI assistant optimized for financial services. You can send messages, manage chat history, and utilize specialized knowledge through RAG containers.

Pro Tip: For a more responsive experience, use the Streaming API to get real-time message updates.

Chat Object

The Chat object represents a conversation between a user and Oliver.

Attribute	Type	Description
id	string	Unique identifier for the chat
name	string	Name of the chat (auto-generated or user-defined)
user_id	string	ID of the user who owns the chat
is_private	boolean	Whether the chat is marked as private
rag_containers	array	Array of RAG container IDs associated with this chat
last_message_at	timestamp	Timestamp of the last message in the chat
created_at	timestamp	When the chat was created
updated_at	timestamp	When the chat was last updated

Message Object

The Message object represents an individual message within a chat.

Attribute	Type	Description
id	string	Unique identifier for the message
chat_id	string	ID of the chat this message belongs to
role	string	Either "user" or "assistant"
content	string	The message content
attachments	array	Array of attached files (optional)
citations	array	Array of citation objects (only for assistant messages)
created_at	timestamp	When the message was created

Create a Chat

Create a new chat session.

Endpoint

POST https://api.oliverchat.com/v1/chats

Request Body

{
  "name": "Financial Planning Discussion",  // Optional, auto-generated if not provided
  "rag_containers": ["container_id_1", "container_id_2"],  // Optional
  "is_private": false  // Optional, defaults to false
}

Example Response

{
  "success": true,
  "data": {
    "id": "chat_123456789",
    "name": "Financial Planning Discussion",
    "user_id": "user_987654321",
    "is_private": false,
    "rag_containers": ["container_id_1", "container_id_2"],
    "last_message_at": null,
    "created_at": "2025-03-11T10:00:00Z",
    "updated_at": "2025-03-11T10:00:00Z"
  },
  "message": "Chat created successfully"
}

Send a Message

Send a message to Oliver within a chat session.

Endpoint

POST https://api.oliverchat.com/v1/chats/{chat_id}/messages

Request Body

{
  "content": "What investment strategies would you recommend for a moderate risk tolerance?",
  "attachments": []  // Optional, for file uploads
}

Example Response

{
  "success": true,
  "data": {
    "id": "msg_123456789",
    "chat_id": "chat_123456789",
    "role": "assistant",
    "content": "For a moderate risk tolerance, I would recommend a balanced portfolio approach. This typically includes a mix of stocks, bonds, and possibly alternative investments...",
    "citations": [
      {
        "source": "Investment Strategies for Moderate Risk Profiles",
        "url": "https://ragcontainer.oliverchat.com/docs/inv-strategies.pdf",
        "type": "rag_document"
      }
    ],
    "created_at": "2025-03-11T10:05:00Z"
  },
  "message": "Message sent successfully"
}

Get Chat History

Retrieve the message history for a specific chat.

Endpoint

GET https://api.oliverchat.com/v1/chats/{chat_id}/messages

Query Parameters

limit: Maximum number of messages to return (default: 50, max: 100)
before: Return messages before this message ID (for pagination)
after: Return messages after this message ID (for pagination)

Example Response

{
  "success": true,
  "data": [
    {
      "id": "msg_123456780",
      "chat_id": "chat_123456789",
      "role": "user",
      "content": "What investment strategies would you recommend for a moderate risk tolerance?",
      "attachments": [],
      "created_at": "2025-03-11T10:04:00Z"
    },
    {
      "id": "msg_123456789",
      "chat_id": "chat_123456789",
      "role": "assistant",
      "content": "For a moderate risk tolerance, I would recommend a balanced portfolio approach...",
      "citations": [
        {
          "source": "Investment Strategies for Moderate Risk Profiles",
          "url": "https://ragcontainer.oliverchat.com/docs/inv-strategies.pdf",
          "type": "rag_document"
        }
      ],
      "created_at": "2025-03-11T10:05:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "per_page": 50,
    "has_more": false
  },
  "message": "Messages retrieved successfully"
}

List Chats

Get a list of all chats for the authenticated user.

Endpoint

GET https://api.oliverchat.com/v1/chats

Query Parameters

limit: Maximum number of chats to return (default: 20, max: 50)
offset: Offset for pagination (default: 0)
include_private: Include private chats (default: true)
sort: Sort by field (default: "last_message_at", options: "created_at", "updated_at", "name")
order: Sort order (default: "desc", options: "asc")

Example Response

{
  "success": true,
  "data": [
    {
      "id": "chat_123456789",
      "name": "Financial Planning Discussion",
      "user_id": "user_987654321",
      "is_private": false,
      "rag_containers": ["container_id_1", "container_id_2"],
      "last_message_at": "2025-03-11T10:05:00Z",
      "created_at": "2025-03-11T10:00:00Z",
      "updated_at": "2025-03-11T10:05:00Z"
    },
    {
      "id": "chat_123456790",
      "name": "Retirement Options",
      "user_id": "user_987654321",
      "is_private": true,
      "rag_containers": [],
      "last_message_at": "2025-03-10T15:30:00Z",
      "created_at": "2025-03-10T15:00:00Z",
      "updated_at": "2025-03-10T15:30:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "per_page": 20,
    "page": 1,
    "total_pages": 1
  },
  "message": "Chats retrieved successfully"
}

Update Chat

Update chat details such as name or privacy setting.

Endpoint

PATCH https://api.oliverchat.com/v1/chats/{chat_id}

Request Body

{
  "name": "Updated Chat Name",  // Optional
  "is_private": true,  // Optional
  "rag_containers": ["container_id_1"]  // Optional
}

Example Response

{
  "success": true,
  "data": {
    "id": "chat_123456789",
    "name": "Updated Chat Name",
    "user_id": "user_987654321",
    "is_private": true,
    "rag_containers": ["container_id_1"],
    "last_message_at": "2025-03-11T10:05:00Z",
    "created_at": "2025-03-11T10:00:00Z",
    "updated_at": "2025-03-11T11:00:00Z"
  },
  "message": "Chat updated successfully"
}

Delete Chat

Delete a chat and all its messages.

Endpoint

DELETE https://api.oliverchat.com/v1/chats/{chat_id}

Example Response

{
  "success": true,
  "data": null,
  "message": "Chat deleted successfully"
}

Upload Files

Upload files to be attached to a message or processed by Oliver.

Endpoint

POST https://api.oliverchat.com/v1/chats/{chat_id}/files

Request

This endpoint accepts multipart/form-data with the following fields:

files[]: File data (can include multiple files)
purpose: Purpose of the upload (options: "attachment", "analysis", both separated by comma)

Example Response

{
  "success": true,
  "data": {
    "file_ids": ["file_123456789", "file_123456790"],
    "files": [
      {
        "id": "file_123456789",
        "filename": "financial_report.pdf",
        "mime_type": "application/pdf",
        "size": 1052672,
        "purpose": ["attachment", "analysis"]
      },
      {
        "id": "file_123456790",
        "filename": "portfolio.xlsx",
        "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "size": 524288,
        "purpose": ["attachment", "analysis"]
      }
    ]
  },
  "message": "Files uploaded successfully"
}

Send Message with File References

Send a message that references previously uploaded files.

Endpoint

POST https://api.oliverchat.com/v1/chats/{chat_id}/messages

Request Body

{
  "content": "Can you analyze these financial reports and tell me the key insights?",
  "attachments": ["file_123456789", "file_123456790"]
}

Example Response

{
  "success": true,
  "data": {
    "id": "msg_123456790",
    "chat_id": "chat_123456789",
    "role": "assistant",
    "content": "Based on the financial reports you've provided, here are the key insights:\n\n1. Your portfolio has shown a 12% annual growth rate...",
    "citations": [],
    "created_at": "2025-03-11T11:30:00Z"
  },
  "message": "Message sent successfully"
}

Error Responses

Not Found

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Chat not found",
    "details": null
  }
}

Permission Denied

{
  "success": false,
  "error": {
    "code": "permission_denied",
    "message": "You do not have permission to access this chat",
    "details": null
  }
}

Validation Error

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The provided data is invalid",
    "details": {
      "content": ["The content field is required."]
    }
  }
}

Next: Streaming API Back to Authentication

Chat API

Chat Object

Message Object

Create a Chat

Endpoint

Request Body

Example Response

Send a Message

Endpoint

Request Body

Example Response

Get Chat History

Endpoint

Query Parameters

Example Response

List Chats

Endpoint

Query Parameters

Example Response

Update Chat

Endpoint

Request Body

Example Response

Delete Chat

Endpoint

Example Response

Upload Files

Endpoint

Request

Example Response

Send Message with File References

Endpoint

Request Body

Example Response

Error Responses

Not Found

Permission Denied

Validation Error

Test the Chat API