Oliver Chat API Documentation | Advisors Asset Management, Inc.

☀️ 🌙

Introduction

Welcome to the Oliver Chat API documentation. This API allows you to interact with the Oliver AI chatbot and its related services provided by Advisors Asset Management, Inc.

Version: 1.0.0

Base URL: https://api.oliverchat.com

Environment:

Authentication

The Oliver Chat API uses OAuth 2.0 for authentication with multiple authentication methods to suit different use cases.

Authentication Methods

Microsoft SSO: Primary authentication method for most users
Username/Password: Alternative authentication method
API Key: For server-to-server communications

POST /api/v1/auth/login

Authenticate a user with username and password.

Request Body

{
  "email": "user@example.com",
  "password": "secure_password"
}

Response

{
  "status": "success",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com",
      "role": "user"
    }
  }
}

GET /api/v1/auth/microsoft

Redirect user to Microsoft authentication.

Query Parameters

Parameter	Type	Required	Description
redirect_uri	string	Yes	URL to redirect to after successful authentication

GET /api/v1/auth/microsoft/callback

Callback endpoint for Microsoft SSO authentication.

Response

Redirects to the specified redirect_uri with authentication token.

POST /api/v1/auth/logout

Logs out the current user by invalidating their token.

Headers

Authorization: Bearer {token}

Response

{
  "status": "success",
  "message": "Successfully logged out"
}

API Keys

API keys can be generated for programmatic access to the Oliver Chat API.

API Key Management

To manage your API keys, use the admin dashboard or the endpoints below.

Test with your API Key

Current API Key: No API key set

POST /api/v1/apikeys

Create a new API key.

Headers

Authorization: Bearer {token}

Request Body

{
  "name": "My Application",
  "expires_at": "2025-12-31T23:59:59Z"  // Optional
}

Response

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "My Application",
    "key": "oc_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2025-03-18T12:00:00Z",
    "expires_at": "2025-12-31T23:59:59Z"
  }
}

GET /api/v1/apikeys

List all API keys for the authenticated user.

Headers

Authorization: Bearer {token}

Response

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "name": "My Application",
      "last_used_at": "2025-03-17T15:30:45Z",
      "created_at": "2025-03-01T12:00:00Z",
      "expires_at": "2025-12-31T23:59:59Z"
    }
  ]
}

DELETE /api/v1/apikeys/{id}

Revoke an API key.

Headers

Authorization: Bearer {token}

Response

{
  "status": "success",
  "message": "API key revoked successfully"
}

Chat Endpoints

The following endpoints are available for chat interactions:

POST /api/v1/chat

Create a new chat.

Headers

Authorization: Bearer {token}

Request Body

{
  "title": "New Chat",  // Optional, will be auto-generated if not provided
  "rag_container_id": 1,  // Optional
  "private": false  // Optional, defaults to false
}

Response

{
  "status": "success",
  "data": {
    "id": 123,
    "title": "New Chat",
    "rag_container_id": 1,
    "private": false,
    "created_at": "2025-03-18T12:34:56Z",
    "updated_at": "2025-03-18T12:34:56Z"
  }
}

GET /api/v1/chat

List all chats for the authenticated user.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)
include_private	boolean	No	Include private chats (default: true)
sort	string	No	Sort order (options: created_at, updated_at; default: updated_at)
direction	string	No	Sort direction (options: asc, desc; default: desc)

Response

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "title": "Financial Planning",
      "rag_container_id": 1,
      "private": false,
      "last_message_at": "2025-03-18T12:34:56Z",
      "created_at": "2025-03-18T12:00:00Z",
      "updated_at": "2025-03-18T12:34:56Z"
    },
    {
      "id": 124,
      "title": "Investment Strategy",
      "rag_container_id": null,
      "private": true,
      "last_message_at": "2025-03-17T15:30:22Z",
      "created_at": "2025-03-17T15:00:00Z",
      "updated_at": "2025-03-17T15:30:22Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}

GET /api/v1/chat/{id}

Get a specific chat and its messages.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Chat ID

Query Parameters

Parameter	Type	Required	Description
include_messages	boolean	No	Include chat messages (default: true)
page	integer	No	Page number for messages pagination
per_page	integer	No	Messages per page (default: 50, max: 100)

Response

{
  "status": "success",
  "data": {
    "id": 123,
    "title": "Financial Planning",
    "rag_container_id": 1,
    "private": false,
    "created_at": "2025-03-18T12:00:00Z",
    "updated_at": "2025-03-18T12:34:56Z",
    "messages": [
      {
        "id": 456,
        "role": "user",
        "content": "What are some retirement planning strategies?",
        "created_at": "2025-03-18T12:30:00Z"
      },
      {
        "id": 457,
        "role": "assistant",
        "content": "There are several retirement planning strategies to consider...",
        "citations": [
          {
            "id": 123,
            "source": "Retirement Planning Guide",
            "url": "https://example.com/document/123"
          }
        ],
        "created_at": "2025-03-18T12:30:45Z"
      }
    ]
  },
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 2,
    "total_pages": 1
  }
}

POST /api/v1/chat/{id}/message

Send a message to a chat.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Chat ID

Request Body

{
  "content": "What are some tax-efficient investment strategies?",
  "attachments": [
    {
      "file_id": 789  // Optional, reference to previously uploaded file
    }
  ],
  "stream": true  // Optional, enable streaming response
}

Response (Non-Streaming)

{
  "status": "success",
  "data": {
    "message": {
      "id": 458,
      "role": "user",
      "content": "What are some tax-efficient investment strategies?",
      "attachments": [
        {
          "id": 789,
          "file_name": "portfolio.pdf",
          "file_size": 1204567,
          "mime_type": "application/pdf"
        }
      ],
      "created_at": "2025-03-18T13:15:00Z"
    },
    "response": {
      "id": 459,
      "role": "assistant",
      "content": "Here are several tax-efficient investment strategies...",
      "citations": [
        {
          "id": 124,
          "source": "Tax Strategies Guide",
          "url": "https://example.com/document/124"
        }
      ],
      "created_at": "2025-03-18T13:15:45Z"
    }
  }
}

Response (Streaming)

For streaming responses, the API will return a stream of server-sent events (SSE) with the following format:

event: message
data: {"id": "chunk_1", "content": "Here are ", "done": false}

event: message
data: {"id": "chunk_2", "content": "several tax-efficient ", "done": false}

event: message
data: {"id": "chunk_3", "content": "investment strategies...", "done": false}

event: message
data: {"id": "459", "role": "assistant", "content": "Here are several tax-efficient investment strategies...", "citations": [{"id": 124, "source": "Tax Strategies Guide", "url": "https://example.com/document/124"}], "created_at": "2025-03-18T13:15:45Z", "done": true}

PUT /api/v1/chat/{id}

Update a chat's metadata.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Chat ID

Request Body

{
  "title": "Updated Chat Title",
  "private": true,
  "rag_container_id": 2
}

Response

{
  "status": "success",
  "data": {
    "id": 123,
    "title": "Updated Chat Title",
    "rag_container_id": 2,
    "private": true,
    "created_at": "2025-03-18T12:00:00Z",
    "updated_at": "2025-03-18T14:30:00Z"
  }
}

DELETE /api/v1/chat/{id}

Delete a chat.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Chat ID

Response

{
  "status": "success",
  "message": "Chat deleted successfully"
}

File Management

The following endpoints are available for managing files:

POST /api/v1/files/upload

Upload a file for processing.

Headers

Authorization: Bearer {token}
Content-Type: multipart/form-data

Request Body

Form data with the following fields:

Field	Type	Required	Description
file	file	Yes	The file to upload (max 25MB)
rag_container_id	integer	No	RAG container ID to associate file with
description	string	No	Optional description of the file

Response

{
  "status": "success",
  "data": {
    "id": 789,
    "file_name": "financial_report.pdf",
    "file_size": 1204567,
    "mime_type": "application/pdf",
    "rag_container_id": 1,
    "description": "Q4 Financial Report",
    "created_at": "2025-03-18T15:00:00Z"
  }
}

GET /api/v1/files

List uploaded files.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)
rag_container_id	integer	No	Filter by RAG container ID

Response

{
  "status": "success",
  "data": [
    {
      "id": 789,
      "file_name": "financial_report.pdf",
      "file_size": 1204567,
      "mime_type": "application/pdf",
      "rag_container_id": 1,
      "description": "Q4 Financial Report",
      "created_at": "2025-03-18T15:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

GET /api/v1/files/{id}

Get file details.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	File ID

Response

{
  "status": "success",
  "data": {
    "id": 789,
    "file_name": "financial_report.pdf",
    "file_size": 1204567,
    "mime_type": "application/pdf",
    "rag_container_id": 1,
    "description": "Q4 Financial Report",
    "created_at": "2025-03-18T15:00:00Z",
    "vectorized": true,
    "vectorized_at": "2025-03-18T15:05:32Z"
  }
}

DELETE /api/v1/files/{id}

Delete a file.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	File ID

Response

{
  "status": "success",
  "message": "File deleted successfully"
}

RAG Integration

Retrieval Augmented Generation (RAG) allows the chatbot to use relevant documents from a vector database when generating responses.

POST /api/v1/rag/containers

Create a new RAG container.

Headers

Authorization: Bearer {token}

Request Body

{
  "name": "Financial Documents",
  "description": "Container for financial documents and reports",
  "permissions": {
    "roles": [1, 2],  // Role IDs with access
    "users": [5, 9]   // User IDs with access
  }
}

Response

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Financial Documents",
    "description": "Container for financial documents and reports",
    "created_at": "2025-03-18T16:00:00Z",
    "updated_at": "2025-03-18T16:00:00Z"
  }
}

GET /api/v1/rag/containers

List available RAG containers for the authenticated user.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Financial Documents",
      "description": "Container for financial documents and reports",
      "document_count": 15,
      "created_at": "2025-03-18T16:00:00Z",
      "updated_at": "2025-03-18T16:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

GET /api/v1/rag/containers/{id}

Get details of a specific RAG container.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	RAG container ID

Query Parameters

Parameter	Type	Required	Description
include_documents	boolean	No	Include document list (default: false)
include_permissions	boolean	No	Include permission details (default: false)

Response

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Financial Documents",
    "description": "Container for financial documents and reports",
    "document_count": 15,
    "created_at": "2025-03-18T16:00:00Z",
    "updated_at": "2025-03-18T16:00:00Z",
    "documents": [
      {
        "id": 789,
        "file_name": "financial_report.pdf",
        "file_size": 1204567,
        "mime_type": "application/pdf",
        "description": "Q4 Financial Report",
        "created_at": "2025-03-18T15:00:00Z"
      }
    ],
    "permissions": {
      "roles": [
        {
          "id": 1,
          "name": "Financial Advisor"
        },
        {
          "id": 2,
          "name": "Manager"
        }
      ],
      "users": [
        {
          "id": 5,
          "name": "Jane Smith"
        },
        {
          "id": 9,
          "name": "John Doe"
        }
      ]
    }
  }
}

PUT /api/v1/rag/containers/{id}

Update a RAG container.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	RAG container ID

Request Body

{
  "name": "Updated Financial Documents",
  "description": "Updated container for financial documents and reports",
  "permissions": {
    "roles": [1, 2, 3],
    "users": [5, 9, 12]
  }
}

Response

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Updated Financial Documents",
    "description": "Updated container for financial documents and reports",
    "created_at": "2025-03-18T16:00:00Z",
    "updated_at": "2025-03-18T17:30:00Z"
  }
}

DELETE /api/v1/rag/containers/{id}

Delete a RAG container.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	RAG container ID

Response

{
  "status": "success",
  "message": "RAG container deleted successfully"
}

Search & Browsing

The following endpoints allow the AI to search the internet and browse web pages.

POST /api/v1/search

Perform a Bing search query.

Headers

Authorization: Bearer {token}

Request Body

{
  "query": "latest financial regulations 2025",
  "chat_id": 123,  // Optional, to associate with a chat
  "count": 10,     // Optional, number of results (default: 10, max: 50)
  "offset": 0      // Optional, for pagination
}

Response

{
  "status": "success",
  "data": {
    "query": "latest financial regulations 2025",
    "results": [
      {
        "id": "search_result_1",
        "title": "New Financial Regulations for 2025",
        "url": "https://example.com/financial-regulations-2025",
        "description": "Overview of the latest financial regulations taking effect in 2025...",
        "published_date": "2025-01-15T00:00:00Z"
      },
      {
        "id": "search_result_2",
        "title": "SEC Announces New Rules for 2025",
        "url": "https://example.com/sec-rules-2025",
        "description": "The Securities and Exchange Commission has announced new rules...",
        "published_date": "2025-02-10T00:00:00Z"
      }
    ],
    "total_results": 156,
    "search_id": "abc123def456"
  }
}

POST /api/v1/browse

Browse and extract content from a web page.

Headers

Authorization: Bearer {token}

Request Body

{
  "url": "https://example.com/financial-regulations-2025",
  "chat_id": 123,  // Optional, to associate with a chat
  "search_id": "abc123def456"  // Optional, to associate with a search query
}

Response

{
  "status": "success",
  "data": {
    "url": "https://example.com/financial-regulations-2025",
    "title": "New Financial Regulations for 2025",
    "content": "In 2025, several new financial regulations will take effect...",
    "metadata": {
      "author": "Jane Smith",
      "published_date": "2025-01-15T00:00:00Z",
      "source": "Example Financial News"
    },
    "browse_id": "browse_xyz789"
  }
}

GET /api/v1/search/history

Get search and browsing history.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
chat_id	integer	No	Filter by chat ID
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)

Response

{
  "status": "success",
  "data": {
    "searches": [
      {
        "id": "abc123def456",
        "query": "latest financial regulations 2025",
        "chat_id": 123,
        "result_count": 156,
        "created_at": "2025-03-18T18:30:00Z"
      }
    ],
    "browses": [
      {
        "id": "browse_xyz789",
        "url": "https://example.com/financial-regulations-2025",
        "title": "New Financial Regulations for 2025",
        "search_id": "abc123def456",
        "chat_id": 123,
        "created_at": "2025-03-18T18:32:00Z"
      }
    ]
  },
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}

Compliance

The following endpoints are available for compliance management:

POST /api/v1/compliance/check

Check content for compliance violations.

Headers

Authorization: Bearer {token}

Request Body

{
  "content": "This is some content to check for compliance issues.",
  "categories": [1, 2, 3],  // Optional, specific compliance categories to check
  "chat_id": 123            // Optional, to associate with a chat
}

Response

{
  "status": "success",
  "data": {
    "compliant": true,
    "violations": []
  }
}

Example response with violations:

{
  "status": "success",
  "data": {
    "compliant": false,
    "violations": [
      {
        "category_id": 2,
        "category_name": "Investment Advice",
        "rule": "Investment advice must include disclaimers",
        "excerpt": "You should invest in these stocks",
        "severity": "medium"
      }
    ]
  }
}

GET /api/v1/compliance/categories

Get available compliance categories.

Headers

Authorization: Bearer {token}

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "General Conduct",
      "description": "Rules related to general business conduct and ethics"
    },
    {
      "id": 2,
      "name": "Investment Advice",
      "description": "Rules for providing investment advice"
    },
    {
      "id": 3,
      "name": "Client Data Privacy",
      "description": "Rules for handling client personal information"
    }
  ]
}

GET /api/v1/compliance/flags

Get flagged compliance violations.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
resolved	boolean	No	Filter by resolution status
category_id	integer	No	Filter by compliance category
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)

Response

{
  "status": "success",
  "data": [
    {
      "id": 45,
      "chat_log_id": 457,
      "category_id": 2,
      "category_name": "Investment Advice",
      "reason": "Missing investment disclaimer",
      "content_excerpt": "You should invest in these stocks",
      "resolved": false,
      "created_at": "2025-03-18T19:15:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

PUT /api/v1/compliance/flags/{id}

Update a compliance flag.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Compliance flag ID

Request Body

{
  "resolved": true,
  "resolution_notes": "Added appropriate disclaimers in response"
}

Response

{
  "status": "success",
  "data": {
    "id": 45,
    "chat_log_id": 457,
    "category_id": 2,
    "category_name": "Investment Advice",
    "reason": "Missing investment disclaimer",
    "content_excerpt": "You should invest in these stocks",
    "resolved": true,
    "resolution_notes": "Added appropriate disclaimers in response",
    "resolved_by": "John Doe",
    "resolved_at": "2025-03-18T20:00:00Z",
    "created_at": "2025-03-18T19:15:00Z"
  }
}

Financial Compliance

The following endpoints are specific to financial regulations and compliance:

POST /api/v1/financial-compliance/check

Check content for financial compliance violations.

Headers

Authorization: Bearer {token}

Request Body

{
  "content": "This is financial advice content to check for compliance.",
  "regulatory_bodies": ["SEC", "FINRA"],  // Optional, specific regulatory bodies to check
  "chat_id": 123                          // Optional, to associate with a chat
}

Response

{
  "status": "success",
  "data": {
    "compliant": false,
    "violations": [
      {
        "category_id": 5,
        "category_name": "SEC Advertising Rules",
        "rule": "SEC Rule 206(4)-1",
        "excerpt": "guaranteed returns on investment",
        "severity": "high",
        "recommendation": "Remove or modify language about guaranteed returns"
      }
    ]
  }
}

GET /api/v1/financial-compliance/categories

Get financial compliance categories.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
regulatory_body	string	No	Filter by regulatory body (SEC, FINRA, etc.)

Response

{
  "status": "success",
  "data": [
    {
      "id": 5,
      "name": "SEC Advertising Rules",
      "regulatory_body": "SEC",
      "description": "Rules related to advertising and promotion of investments",
      "rules": [
        {
          "id": 101,
          "name": "SEC Rule 206(4)-1",
          "description": "Anti-fraud provisions for investment advisor advertisements"
        }
      ]
    },
    {
      "id": 6,
      "name": "FINRA Communications with the Public",
      "regulatory_body": "FINRA",
      "description": "Rules governing member communications with the public",
      "rules": [
        {
          "id": 201,
          "name": "FINRA Rule 2210",
          "description": "Communications with the public"
        }
      ]
    }
  ]
}

GET /api/v1/financial-compliance/documents

Get financial compliance documents.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
document_type	string	No	Filter by document type
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "document_type": "Policy",
      "title": "Investment Advice Policy",
      "description": "Company policy for providing investment advice",
      "retention_period": 2555,
      "compliance_category_id": 5,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Admin Endpoints

The following endpoints are available for administrative functions:

GET /api/v1/admin/system-status

Get system status information.

Headers

Authorization: Bearer {token}

Response

{
  "status": "success",
  "data": {
    "api_health": {
      "status": "operational",
      "response_time": 45
    },
    "ai_providers": [
      {
        "name": "OpenAI",
        "status": "operational",
        "response_time": 856
      },
      {
        "name": "Anthropic",
        "status": "operational",
        "response_time": 743
      }
    ],
    "rag_status": {
      "status": "operational",
      "response_time": 125
    },
    "database_status": {
      "status": "operational",
      "connections": 15,
      "max_connections": 100
    },
    "system_load": {
      "cpu": 23.5,
      "memory": 42.8,
      "disk": 38.2
    }
  }
}

GET /api/v1/admin/chat-logs

Get chat logs for administrative review.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
user_id	integer	No	Filter by user ID
start_date	string	No	Filter by start date (ISO 8601 format)
end_date	string	No	Filter by end date (ISO 8601 format)
flagged	boolean	No	Filter by flagged status
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)

Response

{
  "status": "success",
  "data": [
    {
      "id": 457,
      "user_id": 5,
      "user_name": "Jane Smith",
      "chat_id": 123,
      "chat_title": "Financial Planning",
      "message": "What are some retirement planning strategies?",
      "response": "There are several retirement planning strategies to consider...",
      "flagged": false,
      "created_at": "2025-03-18T12:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

GET /api/v1/admin/system-config

Get system configuration settings.

Headers

Authorization: Bearer {token}

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "key_name": "openai_api_endpoint",
      "key_value": "https://api.openai.com/v1",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "key_name": "anthropic_api_endpoint",
      "key_value": "https://api.anthropic.com/v1",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}

PUT /api/v1/admin/system-config/{id}

Update a system configuration setting.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	System config ID

Request Body

{
  "key_value": "https://api.openai.com/v2"
}

Response

{
  "status": "success",
  "data": {
    "id": 1,
    "key_name": "openai_api_endpoint",
    "key_value": "https://api.openai.com/v2",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-03-18T21:00:00Z"
  }
}

User Management

The following endpoints are available for user management:

GET /api/v1/users

List users (admin access required).

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
role	string	No	Filter by role
search	string	No	Search by name or email
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)

Response

{
  "status": "success",
  "data": [
    {
      "id": 5,
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "role": "user",
      "supervisor_id": 9,
      "created_at": "2025-01-15T00:00:00Z",
      "updated_at": "2025-01-15T00:00:00Z"
    },
    {
      "id": 9,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "role": "supervisor",
      "supervisor_id": null,
      "created_at": "2025-01-10T00:00:00Z",
      "updated_at": "2025-01-10T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}

POST /api/v1/users

Create a new user (admin access required).

Headers

Authorization: Bearer {token}

Request Body

{
  "name": "New User",
  "email": "new.user@example.com",
  "password": "secure_password",
  "role": "user",
  "supervisor_id": 9,
  "permissions": ["create_chat", "access_rag_container_1"]
}

Response

{
  "status": "success",
  "data": {
    "id": 10,
    "name": "New User",
    "email": "new.user@example.com",
    "role": "user",
    "supervisor_id": 9,
    "created_at": "2025-03-18T22:00:00Z",
    "updated_at": "2025-03-18T22:00:00Z"
  }
}

GET /api/v1/users/{id}

Get a specific user (admin access required).

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	User ID

Response

{
  "status": "success",
  "data": {
    "id": 5,
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "role": "user",
    "supervisor_id": 9,
    "supervisor": {
      "id": 9,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "permissions": [
      "create_chat",
      "access_rag_container_1"
    ],
    "created_at": "2025-01-15T00:00:00Z",
    "updated_at": "2025-01-15T00:00:00Z"
  }
}

PUT /api/v1/users/{id}

Update a user (admin access required).

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	User ID

Request Body

{
  "name": "Jane Smith Updated",
  "email": "jane.updated@example.com",
  "role": "user",
  "supervisor_id": 9,
  "permissions": ["create_chat", "access_rag_container_1", "access_rag_container_2"]
}

Response

{
  "status": "success",
  "data": {
    "id": 5,
    "name": "Jane Smith Updated",
    "email": "jane.updated@example.com",
    "role": "user",
    "supervisor_id": 9,
    "created_at": "2025-01-15T00:00:00Z",
    "updated_at": "2025-03-18T22:30:00Z"
  }
}

DELETE /api/v1/users/{id}

Delete a user (admin access required).

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	User ID

Response

{
  "status": "success",
  "message": "User deleted successfully"
}

GET /api/v1/profile

Get the authenticated user's profile.

Headers

Authorization: Bearer {token}

Response

{
  "status": "success",
  "data": {
    "id": 5,
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "role": "user",
    "preferences": {
      "theme": "dark",
      "sidebar_collapsed": false
    },
    "permissions": [
      "create_chat",
      "access_rag_container_1"
    ],
    "created_at": "2025-01-15T00:00:00Z",
    "updated_at": "2025-01-15T00:00:00Z"
  }
}

PUT /api/v1/profile

Update the authenticated user's profile.

Headers

Authorization: Bearer {token}

Request Body

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "password": "new_secure_password",  // Optional
  "preferences": {
    "theme": "light",
    "sidebar_collapsed": true
  }
}

Response

{
  "status": "success",
  "data": {
    "id": 5,
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "preferences": {
      "theme": "light",
      "sidebar_collapsed": true
    },
    "created_at": "2025-01-15T00:00:00Z",
    "updated_at": "2025-03-18T23:00:00Z"
  }
}

Generated Images

The following endpoints are available for managing AI-generated images:

POST /api/v1/images/generate

Generate an image using AI.

Headers

Authorization: Bearer {token}

Request Body

{
  "prompt": "A chart showing investment portfolio diversification",
  "size": "1024x1024",  // Optional, sizes: 256x256, 512x512, 1024x1024
  "chat_id": 123        // Optional, to associate with a chat
}

Response

{
  "status": "success",
  "data": {
    "id": 42,
    "url": "https://api.oliverchat.com/images/generated/abc123.png",
    "prompt": "A chart showing investment portfolio diversification",
    "size": "1024x1024",
    "created_at": "2025-03-18T23:15:00Z"
  }
}

GET /api/v1/images

List generated images.

Headers

Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
chat_id	integer	No	Filter by chat ID
page	integer	No	Page number for pagination
per_page	integer	No	Results per page (default: 20, max: 100)

Response

{
  "status": "success",
  "data": [
    {
      "id": 42,
      "url": "https://api.oliverchat.com/images/generated/abc123.png",
      "prompt": "A chart showing investment portfolio diversification",
      "size": "1024x1024",
      "chat_id": 123,
      "created_at": "2025-03-18T23:15:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

DELETE /api/v1/images/{id}

Delete a generated image.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Image ID

Response

{
  "status": "success",
  "message": "Image deleted successfully"
}

Streaming

Streaming endpoints allow real-time updates as the AI processes responses.

Chat Streaming

For chat streaming, use the regular chat message endpoint with stream: true in the request body.

Server-Sent Events Format

Streaming responses use server-sent events (SSE) with the following format:

event: message
data: {"id": "chunk_1", "content": "Here are ", "done": false}

event: message
data: {"id": "chunk_2", "content": "several tax-efficient ", "done": false}

event: message
data: {"id": "chunk_3", "content": "investment strategies...", "done": false}

event: message
data: {"id": "final_message_id", "content": "Here are several tax-efficient investment strategies...", "done": true}

Client Implementation Example

const eventSource = new EventSource('/api/v1/chat/123/message/stream?token=your_token');

eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  
  if (data.done) {
    eventSource.close();
    // Handle complete message
  } else {
    // Handle chunk
    // Append data.content to the UI
  }
});

eventSource.addEventListener('error', (event) => {
  eventSource.close();
  // Handle error
});

Citations

Citations are references to sources used by the AI when generating responses.

GET /api/v1/citations/{id}

Get details about a specific citation.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Citation ID

Response

{
  "status": "success",
  "data": {
    "id": 123,
    "source": "Retirement Planning Guide",
    "title": "Comprehensive Retirement Planning",
    "url": "https://example.com/document/123",
    "excerpt": "Retirement planning strategies should include consideration of tax implications...",
    "document_id": 789,  // If from a RAG document
    "search_id": null,    // If from a search result
    "browse_id": null,    // If from a browsed web page
    "created_at": "2025-03-18T12:30:45Z"
  }
}

GET /api/v1/chat/{id}/citations

Get all citations used in a chat.

Headers

Authorization: Bearer {token}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Chat ID

Response

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "message_id": 457,
      "source": "Retirement Planning Guide",
      "url": "https://example.com/document/123",
      "created_at": "2025-03-18T12:30:45Z"
    },
    {
      "id": 124,
      "message_id": 459,
      "source": "Tax Strategies Guide",
      "url": "https://example.com/document/124",
      "created_at": "2025-03-18T13:15:45Z"
    }
  ]
}

Error Codes

The API uses standardized error codes to indicate issues:

Error Code	HTTP Status	Description
auth_failed	401	Authentication failure (invalid credentials)
validation_error	422	Validation failed for request parameters
not_found	404	Requested resource not found
permission_denied	403	User lacks permission for the requested action
rate_limit_exceeded	429	Too many requests (rate limit exceeded)
server_error	500	Internal server error

Error Response Format

{
  "status": "error",
  "code": "validation_error",
  "message": "The request parameters failed validation.",
  "details": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

Rate Limiting

To ensure system stability and fair usage, the API implements rate limiting:

Default Rate Limits

Endpoint Category	Rate Limit	Window
Authentication	10 requests	1 minute
Chat Messages	60 requests	1 minute
Image Generation	10 requests	1 minute
Search & Browsing	20 requests	1 minute
Financial Data	100 requests	1 minute
Other Endpoints	120 requests	1 minute

Rate Limit Headers

Rate limit information is included in the response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1716148800

Rate Limit Exceeded Response

{
  "status": "error",
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "details": {
    "retry_after": 25
  }
}