Cognitium Fast API Documentation

Overview

The Cognitium Fast API provides a single POST endpoint for processing chat messages and recording votes. All API requests should be directed to:

https://fastapi.cognitium.co.uk/api

This endpoint accepts JSON requests and returns JSON responses. Depending on the value of the action field in your payload, the API will process either a chat message or a vote.

Authentication & Security

Every request to the API must include these authentication fields:

user_id: A UUID representing your account.
api_key: Your secret API key, which verifies your identity.
session_id: A unique session identifier for tracking requests.

The API verifies that the provided api_key matches the one stored for your user_id. Invalid or mismatched credentials will be rejected.

Important

Always keep your API key secure and never expose it in client-side code. Set appropriate CORS policies for your domain.

API Endpoint Actions

All interactions occur via a single POST endpoint at https://fastapi.cognitium.co.uk/api. The behavior of the API is determined by the value of the action field in your JSON payload.

1. Chat Action

POST application/json

To send a chat message, include "action": "chat" plus the following required fields:

Chat Request JSON

{
  "action": "chat",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "api_key": "your-api-key",
  "session_id": "session123",
  "message": "Hello, how are you?",
  "domain": "https://example.com",
  "client_ip": "123.456.789.0",
  "browser": "Firefox",
  "os": "Windows",
  "language": "en",
  "referrer": "https://referrer.com",
  "browser_info": "Detailed browser info (optional)"
}

Field Descriptions:

message: The text message from the user.
domain: Your website's URL (validated against allowed domains).
client_ip: The user's IP address (must be valid).
browser, os, language, referrer: Additional metadata for logging/analytics.
browser_info: (Optional) More detail about the user’s browser.

Response (Chat):

Chat Response JSON

{
  "message": "Hello! I'm an AI assistant. How can I help you today?",
  "links": [
    {
      "url": "https://example.com/resource",
      "title": "Example Resource",
      "description": "A helpful resource related to your query."
    }
  ],
  "chat_id": 12345,
  "search_results": [
    {
      "title": "Search Result 1",
      "url": "https://example.com/result1",
      "snippet": "Relevant text from search result..."
    }
  ]
}

2. Vote Action

POST application/json

To record a vote for a chat message, send a payload with "action": "vote" and these fields:

Vote Request JSON

{
  "action": "vote",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "api_key": "your-api-key",
  "session_id": "session123",
  "chat_id": 1,
  "vote": 1
}

Field Descriptions:

chat_id: The ID for the chat message being voted on.
vote: 1 for upvote, 0 for downvote.

The API confirms the chat entry exists and belongs to the authenticated user before recording the vote.

Implementation Details

The backend is built with FastAPI and SQLAlchemy. Key points include:

Configuration

Application settings (DB URL, logging, rate limits) are handled via a Pydantic AppConfig. The default public URL is always https://fastapi.cognitium.co.uk/api.

Database Models

Entities like User, Chat, Config, and AllowedDomain are defined with SQLAlchemy, ensuring data consistency and enforcing monthly chat limits.

LLM Providers

Multiple LLM providers (Gemini, OpenAI, Ollama) are supported via a factory pattern. Exactly one is enabled in your config. Each provider updates token usage via TokenManager.

Rate Limits

The API checks your monthly chat usage against UserLimit. If you exceed the limit, it returns a polite prompt to upgrade your plan.

All inputs are validated (UUIDs, IP addresses, etc.). Detailed logs help with troubleshooting.

Example API Integration (Python)

Below is a simple Python example using httpx to send a chat request. Note that the default API URL is used:

Python Integration Example

import httpx
import json

url = "https://fastapi.cognitium.co.uk/api"  # Default Cognitium Fast API URL

payload = {
    "action": "chat",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "api_key": "your-api-key",
    "session_id": "session123",
    "message": "Hello, how are you?",
    "domain": "https://example.com",
    "client_ip": "123.456.789.0",
    "browser": "Firefox",
    "os": "Windows",
    "language": "en",
    "referrer": "https://referrer.com",
    "browser_info": "Detailed browser info"
}

response = httpx.post(url, json=payload)
print(json.dumps(response.json(), indent=2))