API Documentation

Generate an API key to access the Baduno AI system programmatically. Use the endpoints below to integrate AI capabilities into your applications.

Generate API Key

Your API Key

API Key Holders

Name	API Key	Created
Loading...

API Endpoints

POST /chat

Send a message to Baduno AI and receive a response. Supports conversation history through session IDs.

Headers

Header	Value	Required
X-API-Key	Your API key	Required
Content-Type	application/json	Required

Request Body

Parameter	Type	Description	Required
message	string	The message to send to the AI	Required
session_id	string	Session ID for conversation continuity	Optional
temperature	float	Controls randomness (0.0 to 1.0). Default: 0.7	Optional
max_tokens	integer	Maximum tokens to generate. Default: 4096	Optional
top_p	float	Nucleus sampling parameter. Default: 0.9	Optional
websearch	boolean	Enable web search to get current information. Default: false	Optional
companies_search	boolean	Enable company database search for German companies. Default: false	Optional

Request Example

curl -X POST https://www.baduno.ai/chat \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the latest news about AI?",
    "session_id": "user123",
    "temperature": 0.7,
    "max_tokens": 4096,
    "top_p": 0.9,
    "websearch": true,
    "companies_search": false
  }'

Response Example

{
  "response": "I'm doing well, thank you for asking! How can I assist you today?",
  "tokens_generated": 15,
  "generation_time": 0.85,
  "tokens_per_second": 17.65
}

WS /ws

WebSocket endpoint for real-time streaming responses.

Note

WebSocket connections provide real-time streaming of AI responses, allowing you to receive tokens as they are generated.

JavaScript Example

const ws = new WebSocket('wss://www.baduno.ai/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    message: "What's the latest news?",
    session_id: "user123",
    temperature: 0.7,
    max_tokens: 4096,
    top_p: 0.9,
    websearch: true,
    companies_search: false  // Set to true to search company database
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data.response);
};

GET /health

Check if the API is running and healthy.

Request Example

curl https://www.baduno.ai/health

Response Example

{
  "status": "healthy",
  "model_loaded": true,
  "model_name": "GPT-OSS-20B"
}

Web Search Feature

Set websearch: true to enable real-time web search. The AI will search the web for current information and use the results to answer your question. This is useful for:

Getting latest news and current events
Finding up-to-date information about topics
Researching recent developments
Answering questions that require current data

Company Search Feature

Set companies_search: true to enable company database search. The AI will automatically extract company or person names from your message and search the German Handelsregister database. This is useful for:

Finding information about German companies (GmbH, AG, SE, etc.)
Getting company details like register numbers, addresses, and legal forms
Researching managing directors, board members, and partners
Checking company status and business purpose

Example: Send a message like "Suche nach BMW AG" or "Information about SAP SE" and the AI will automatically extract "BMW AG" or "SAP SE" and search the database.

Company Search Example

curl -X POST https://www.baduno.ai/chat \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Suche nach BMW AG",
    "session_id": "user123",
    "temperature": 0.7,
    "companies_search": true
  }'

# The AI will:
# 1. Extract "BMW AG" from your message
# 2. Search the German Handelsregister database
# 3. Return detailed company information including:
#    - Company name and legal form
#    - Register number and court
#    - Business address and status
#    - Managing directors and board members
#    - Share capital and business purpose

Python Example

import requests

API_KEY = "your-api-key-here"
API_URL = "https://www.baduno.ai/chat"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

data = {
    "message": "Explain quantum computing",
    "session_id": "session123",
    "temperature": 0.7,
    "max_tokens": 2048,
    "websearch": False,  # Set to True to enable web search
    "companies_search": False  # Set to True to enable company search
}

response = requests.post(API_URL, headers=headers, json=data)
result = response.json()

print(result["response"])

Node.js Example

const axios = require('axios');

const API_KEY = 'your-api-key-here';
const API_URL = 'https://www.baduno.ai/chat';

async function chat(message) {
  try {
    const response = await axios.post(API_URL, {
      message: message,
      session_id: 'session123',
      temperature: 0.7,
      max_tokens: 2048,
      websearch: false,  // Set to true to enable web search
      companies_search: false  // Set to true to enable company search
    }, {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    });

    console.log(response.data.response);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

chat('Hello, Baduno AI!');

POST /api/pdf/analyze

Upload and analyze PDF documents. Extracts text, tables, and metadata using pdfplumber.

Headers

Header	Value	Required
X-Api-Key	baduno_pdf_2024	Required

Form Data

Parameter	Type	Description	Required
file	file	PDF file to analyze	Required
query	string	Optional question to ask AI about the PDF content. If provided, AI will analyze the PDF and answer your question.	Optional

Request Example (curl) - Basic PDF Analysis

curl -X POST https://www.baduno.ai/api/pdf/analyze \
  -H "X-Api-Key: baduno_pdf_2024" \
  -F "file=@/path/to/document.pdf"

Request Example (curl) - PDF Analysis with AI Query

curl -X POST https://www.baduno.ai/api/pdf/analyze \
  -H "X-Api-Key: baduno_pdf_2024" \
  -F "file=@/path/to/document.pdf" \
  -F "query=What is the main topic of this document?"

Response Example (without query)

{
  "success": true,
  "data": {
    "full_text": "Complete extracted text from the PDF...",
    "tables": [
      {
        "page": 1,
        "table_index": 0,
        "data": [["Header 1", "Header 2"], ["Value 1", "Value 2"]]
      }
    ],
    "metadata": {
      "filename": "document.pdf",
      "total_pages": 5
    },
    "summary": {
      "total_pages": 5,
      "total_words": 1523,
      "total_tables": 2,
      "pages_with_tables": 1,
      "filename": "document.pdf"
    }
  },
  "chat_response": null
}

Response Example (with query)

{
  "success": true,
  "data": null,
  "chat_response": "Based on the PDF content, the main topic of this document is..."
}

Important: Response Behavior

Without query parameter: Returns full PDF data (text, tables, metadata)
With query parameter: Returns ONLY the AI response (no PDF data)

This design allows for flexible usage:

Extract raw data: Don't include query parameter
Get AI analysis: Include query parameter

Python Example - Basic PDF Analysis

import requests

# Basic PDF analysis (extract text only)
pdf_url = "https://www.baduno.ai/api/pdf/analyze"
headers = {"X-Api-Key": "baduno_pdf_2024"}

with open("document.pdf", "rb") as f:
    files = {"file": f}
    response = requests.post(pdf_url, headers=headers, files=files)
    pdf_data = response.json()

if pdf_data["success"]:
    print("Extracted text:", pdf_data["data"]["full_text"])
    print("Summary:", pdf_data["data"]["summary"])

Python Example - PDF Analysis with AI Query

import requests

# PDF analysis with AI query (get immediate answer)
pdf_url = "https://www.baduno.ai/api/pdf/analyze"
headers = {"X-Api-Key": "baduno_pdf_2024"}

with open("document.pdf", "rb") as f:
    files = {"file": f}
    data = {"query": "What is the main topic of this document?"}
    response = requests.post(pdf_url, headers=headers, files=files, data=data)
    result = response.json()

if result["success"]:
    # When query is provided, only chat_response is returned
    print("AI Answer:", result["chat_response"])
    # result["data"] will be None when query is provided

Python Example - Get PDF Content as JSON

import requests

# Ask AI to convert PDF content to JSON format
pdf_url = "https://www.baduno.ai/api/pdf/analyze"
headers = {"X-Api-Key": "baduno_pdf_2024"}

with open("document.pdf", "rb") as f:
    files = {"file": f}
    data = {"query": "Gib mir den kompletten PDF Inhalt als JSON zurück"}
    response = requests.post(pdf_url, headers=headers, files=files, data=data)
    result = response.json()

if result["success"]:
    # AI will format the PDF content as JSON
    print(result["chat_response"])

Python Example - Advanced: Extract then Chat

import requests

# Step 1: Upload and analyze PDF
pdf_url = "https://www.baduno.ai/api/pdf/analyze"
headers = {"X-Api-Key": "baduno_pdf_2024"}

with open("document.pdf", "rb") as f:
    files = {"file": f}
    response = requests.post(pdf_url, headers=headers, files=files)
    pdf_data = response.json()

if pdf_data["success"]:
    # Step 2: Ask questions about the PDF using chat endpoint
    chat_url = "https://www.baduno.ai/chat"
    chat_headers = {
        "X-API-Key": "your-api-key-here",
        "Content-Type": "application/json"
    }

    # Include the extracted text in your message
    message = f"""I have a PDF with the following content:

{pdf_data['data']['full_text'][:5000]}

Please summarize the main points of this document."""

    response = requests.post(chat_url, headers=chat_headers, json={
        "message": message,
        "session_id": "pdf_session_123"
    })

    print(response.json()["response"])

PDF Analysis Feature

The PDF analyzer extracts:

Full Text: Complete text content from all pages
Tables: Structured table data with page numbers
Metadata: File information and page count
Summary: Statistics about pages, words, and tables

Use Cases:

Extract data from invoices, contracts, and reports
Analyze document structure and content
Ask the AI questions about PDF documents
Convert PDFs to structured data

NEW: Direct AI Query Feature

Now you can get instant AI answers when analyzing PDFs!

Add an optional query parameter to your PDF analysis request:

Without query: Get raw PDF data (text, tables, metadata)
With query: Get AI-processed answer ONLY (no raw data)

Benefits:

Single Request: No need for separate API calls
Instant Answers: Get AI analysis immediately
Flexible Output: AI can format response as JSON, XML, CSV, or plain text
Context-Aware: AI analyzes the full document context
Clean Response: Only get what you need - AI answer without raw data clutter

Example Queries:

"What is the main topic of this document?"
"Summarize the key findings"
"Extract all company names mentioned"
"Gib mir den kompletten Inhalt als JSON zurück"
"Convert this document to structured JSON format"
"What are the financial figures in this report?"