Chat API

Integrate AI-powered chat capabilities into your applications using our Chat API endpoints.

Authentication

All API requests require authentication using your API key. You can find your API key in your account settings .

Chat API

POST https://filebrain.pro/api/chat/v1/

Request Parameters

Parameter Type Required Description
project_id string Yes Your project identifier
api_key string Yes Your secret API key
query string Yes The user's question or message
session_id string No Unique identifier for maintaining conversation context
prompt string No Custom prompt to override the default project prompt
tags array No List of tags for filtering knowledge base content
human_assist boolean No Flag to request human assistance
context_info boolean No Include context information in response
url_format string No Format of the response ('html' or 'plain'). Default is 'html'

Request Example

{
  "project_id": "c929732212329c3da8368e868bcd3393",
  "api_key": "4a6b796c6931eecbb1ec8cdd85ac15c4ba64408e",
  "query": "Hello, FileBrain!",
  "session_id": "optional_unique_user_token",
  "prompt": "optional_custom_prompt",
  "tags": ["optional", "tags", "list"],
  "human_assist": false,
  "context_info": false,
  "url_format": "html"
}

Response Format

{
  "status": "success",
  "message": {
    "question": "user_question",
    "answer": "response_to_the_question",
    "source": ["Optional_array_of_sources"]
  },
  "execution_time": 0.5,
  "call_cost": 1,
  "total_tokens": 150,
  "is_intention": false,
  "context_info": {
    "chunks": [
      {
        "id": 1,
        "source": "document.txt",
        "content": "relevant text from knowledge base",
        "score": 0.9600
      }
    ],
    "memory_context": [
      {
        "id": 1,
        "user": "hi",
        "chatbot": "hi there, how may I help you today?"
      }
    ]
  }
}

Response Parameters

Parameter Type Description
status string Response status (success or error)
message object Contains the question, answer, and optional sources
execution_time number Time taken to process the request in seconds
call_cost number The cost associated with this API call
total_tokens number Total tokens used in the request and response
is_intention boolean Indicates if a custom intention was triggered (true) or if this is a normal response (false)
context_info object Optional knowledge base context and conversation history (only included when context_info parameter is set to true)

Error Response Format

{
  "status": "error",
  "message": "error_message"
}

Common error messages include:

  • "Authentication failed"
  • "Project ID is not valid"
  • "API usage limit reached"
  • "Invalid JSON"

Human Assist Response

{
  "status": "success",
  "message": {
    "question": "user_question",
    "answer": "Human assistance requested",
    "source": []
  },
  "execution_time": 1,
  "call_cost": 0,
  "total_tokens": 1,
  "is_intention": true
}

Custom Intention Response

When a custom intention is triggered, the response will include is_intention: true and the answer will contain the configured intention response:

{
  "status": "success",
  "message": {
    "question": "user_question",
    "answer": "Custom intention response text",
    "source": []
  },
  "execution_time": 1,
  "call_cost": 0,
  "total_tokens": 1,
  "is_intention": true
}

Code Examples

import requests

API_URL = "https://filebrain.pro/api/chat/v1/"
headers = {"Content-Type": "application/json"}

payload = {
    "project_id": "YOUR-PROJECT-ID",
    "api_key": "YOUR-API-KEY",
    "query": "Hello, FileBrain!",
    "session_id": "unique_session_id",
    # "prompt": "optional_custom_prompt",
    # "tags": ["tag1", "tag2"],
    # "human_assist": False,
    # "context_info": False,
    # "url_format": "html"
}

response = requests.post(API_URL, json=payload, headers=headers)

if response.status_code == 200:
    data = response.json()
    if data.get("status") == "success":
        answer = data["message"]["answer"]
        is_intention = data.get("is_intention", False)
        print(f"Answer: {answer}")
        
        # Check if this is a custom intention response
        if is_intention:
            print("This is a custom intention response")
            
        # Get chunks if context_info was requested
        chunks = data.get("context_info", {}).get("chunks", [])
        print(f"Relevant chunks: {len(chunks)}")
    else:
        print("Error:", data.get("message", "Unknown error"))
else:
    print("Failed to reach the server.")
const API_URL = 'https://filebrain.pro/api/chat/v1/';

const payload = {
    project_id: 'YOUR-PROJECT-ID',
    api_key: 'YOUR-API-KEY',
    query: 'Hello, FileBrain!',
    session_id: 'unique_session_id',
    // prompt: 'optional_custom_prompt',
    // tags: ['tag1', 'tag2'],
    // human_assist: false,
    // context_info: false,
    // url_format: 'html'
};

async function chatWithFileBrain() {
    try {
        const response = await fetch(API_URL, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify(payload)
        });

        const data = await response.json();
        
        if (data.status === 'success') {
            console.log('Answer:', data.message.answer);
            
            // Check if this is a custom intention response
            if (data.is_intention) {
                console.log('Custom intention detected!');
            }
            
            // Access context information if requested
            if (data.context_info) {
                console.log('Context chunks:', data.context_info.chunks.length);
            }
        } else {
            console.error('Error:', data.message);
        }
    } catch (error) {
        console.error('Failed to reach the server:', error);
    }
}
curl -X POST https://filebrain.pro/api/chat/v1/ \
    -H "Content-Type: application/json" \
    -d '{
        "project_id": "YOUR-PROJECT-ID",
        "api_key": "YOUR-API-KEY",
        "query": "Hello, FileBrain!",
        "session_id": "unique_session_id",
        # "prompt": "optional_custom_prompt",
        # "tags": ["tag1", "tag2"],
        # "human_assist": false,
        # "context_info": false,
        # "url_format": "html"
    }'