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 the default URL:

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 validates that the provided api_key matches the one stored for your user_id. Requests with invalid or mismatched credentials will be rejected.

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

To send a chat message, include "action": "chat" along with these required fields:

{
  "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 sent by the user.
domain: Your website's URL. This is verified against your allowed domains.
client_ip: The user's IP address. This must be a valid IP.
browser, os, language, referrer: Additional metadata for logging and analytics.
browser_info: (Optional) Extra information about the user's browser.

Response: On a successful chat action, the API returns a JSON object containing:

message: The AI-generated response.
links: An array of link previews, if applicable.
chat_id: A unique identifier for the chat entry.
search_results: Results generated from the integrated search functionality.

2. Vote Action

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

{
  "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 unique identifier for the chat message you are voting on.
vote: Use 1 for an upvote or 0 for a downvote.

The API ensures that 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: Settings (such as the database URL, logging preferences, and rate limits) are managed using a centralized Pydantic AppConfig. Note that the API always uses the default URL https://fastapi.cognitium.co.uk/api.
Logging: API activity is logged using a custom JSON formatter that records timestamps, log levels, and messages for easy debugging and monitoring.
Database Models: Entities such as User, Chat, Config, and AllowedDomain are defined with SQLAlchemy to ensure data consistency and efficient queries (for example, enforcing monthly chat limits).
LLM Providers: The API supports multiple LLM providers (Google Gemini, OpenAI, and Ollama) via a factory pattern. Exactly one provider must be enabled in your configuration. Each provider sends a POST request to its respective endpoint, processes the response, and updates token usage via a TokenManager.
Rate Limits: Before processing a chat request, the API checks your monthly chat usage against the limit defined in the UserLimit table. If you exceed your limit, a polite message is returned prompting you to upgrade your plan.
Error Handling: Detailed HTTP status codes and error messages are provided for scenarios such as invalid JSON, missing fields, authentication failures, unauthorized domain access, and rate limit breaches.

All input fields are validated (e.g. ensuring user_id is a valid UUID and client_ip is a valid IP address). Detailed logs are maintained for troubleshooting.

Example API Integration (Python)

The following Python example uses the httpx library to send a chat request. Note that the default API URL is used:

import httpx
import json

url = "https://fastapi.cognitium.co.uk/api"  # This is the default 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))

To record a vote, modify the payload to include "action": "vote" along with the chat_id and vote fields.

Error Handling & Troubleshooting

The API returns clear HTTP status codes and error messages. Common issues include:

Invalid JSON or malformed requests.
Missing required fields (e.g. message or domain).
Invalid user_id format or authentication errors (incorrect API key).
Unauthorized domain access when the provided domain is not allowed.
Exceeding your monthly chat limit.

Example error response:

{
  "error": "Invalid API key."
}

Please ensure that your client application checks the HTTP status code and handles errors gracefully.

Conclusion

This documentation covers all aspects of the Cognitium Fast API, including how to send chat messages, record votes, and handle errors and rate limits. Remember, all API requests should be directed to https://fastapi.cognitium.co.uk/api – this is the default endpoint. By following these guidelines and examples, you can seamlessly integrate our API into your application.