API Documentation — CaveauAI by Blue Note Logic

Authentication

All API requests require an X-API-Key header. Keys are unique to your account and scoped to your corpus.

Prefixed for Identification

All keys start with bnl_ so you can easily identify them in your code and config files.

Hashed on Our Servers

Keys are hashed (SHA-256) at rest. We never store them in plaintext. If you lose your key, generate a new one.

Generate & Revoke from Dashboard

Manage your keys from the platform dashboard. Revoke compromised keys instantly.

                        Request Header
                    
                        X-API-Key: bnl_sk_abc123def456...

Rate Limits by Plan

Trial No API access

Starter 500 requests/month

Professional 2,000 requests/month

Enterprise Custom

Endpoints

Base URL: https://ai.bluenotelogic.com

POST /api/v2/chat.php AI Chat

Ask a question and get an AI-powered answer from your document corpus. The response includes the generated answer, source citations, model information, and performance metrics.

Request Body (JSON)

message

string required

The question to ask your AI assistant.

use_corpus

boolean default: true

Whether to search your document corpus for context. Set to false for general AI chat.

model

string optional

Specific model to use for generation. Defaults to the best available model.

Response (JSON)

answer

string

The AI-generated answer grounded in your documents.

model

string

The model used for generation (e.g. "qwen2.5:72b").

sources

array

Source documents referenced in the answer, with title and relevance score.

response_time_ms

integer

Total processing time in milliseconds.

tokens_used

integer

Number of tokens consumed by the request.

                    Example Request & Response
                    curl
                

                    # Request
curl -X POST https://ai.bluenotelogic.com/api/v2/chat.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bnl_sk_abc123def456" \
  -d '{
    "message": "What is our return policy?",
    "use_corpus": true
  }'

# Response
{
  "answer": "According to your Terms of Service (Section 7.1), customers may request a full refund within 14 days of purchase, provided the product has not been downloaded or activated. Refund requests should be submitted through the customer portal.",
  "model": "qwen2.5:72b",
  "sources": [
    {
      "title": "terms-of-service-v3.2.pdf",
      "score": 0.94,
      "excerpt": "Section 7.1 — Refund Policy: Customers are entitled to..."
    }
  ],
  "response_time_ms": 2340,
  "tokens_used": 847
}
                

$ch = curl_init('https://ai.bluenotelogic.com/api/v2/chat.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: bnl_your_api_key',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'message' => 'What is our return policy?',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response['answer'];

import requests

response = requests.post(
    'https://ai.bluenotelogic.com/api/v2/chat.php',
    headers={'X-API-Key': 'bnl_your_api_key'},
    json={'message': 'What is our return policy?'}
)
data = response.json()
print(data['answer'])

const response = await fetch('https://ai.bluenotelogic.com/api/v2/chat.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'bnl_your_api_key',
    },
    body: JSON.stringify({ message: 'What is our return policy?' }),
});
const data = await response.json();
console.log(data.answer);

POST /api/v2/search.php Semantic Search

Search your document corpus for relevant chunks using semantic vector search. Returns ranked results with relevance scores, document titles, and text excerpts. Useful for building custom search interfaces or pre-filtering before chat.

Request Body (JSON)

query

string required

The search query in natural language.

top_k

integer default: 5, range: 1-20

Number of results to return.

Response (JSON)

results

array

Matching document chunks, each with title, score, excerpt, and document_id.

query_time_ms

integer

Vector search time in milliseconds.

                    Example Request & Response
                    curl
                

                    # Request
curl -X POST https://ai.bluenotelogic.com/api/v2/search.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bnl_sk_abc123def456" \
  -d '{
    "query": "employee onboarding process",
    "top_k": 3
  }'

# Response
{
  "results": [
    {
      "title": "hr-onboarding-guide.pdf",
      "score": 0.92,
      "excerpt": "New employees must complete the following steps within their first week: security badge activation, IT setup request, and mandatory compliance training...",
      "document_id": 142
    },
    {
      "title": "employee-handbook-2025.pdf",
      "score": 0.87,
      "excerpt": "The onboarding period spans 90 days. During this time, the new hire will be assigned a mentor from their department...",
      "document_id": 98
    },
    {
      "title": "it-setup-checklist.docx",
      "score": 0.81,
      "excerpt": "IT provisioning for new employees includes: email account, VPN access, development environment setup, and Slack workspace invitation...",
      "document_id": 205
    }
  ],
  "query_time_ms": 45
}
                

POST /api/v2/documents.php Document Management

Upload, list, and delete documents in your corpus programmatically. Use this endpoint to integrate document management into your own workflows and automation pipelines.

LIST List Documents

Returns all documents in your corpus with metadata including title, upload date, chunk count, and status.

{"action": "list"}

UPLOAD Upload Document

Upload a new document to your corpus. Uses multipart/form-data. Supported formats: PDF, DOCX, TXT, HTML.

multipart/form-data

DELETE Remove Document

Remove a document and all its chunks from your corpus. This action is irreversible.

{"action": "delete", "document_id": 142}

                            LIST
                            List all documents
                        
curl

                        curl -X POST https://ai.bluenotelogic.com/api/v2/documents.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bnl_sk_abc123def456" \
  -d '{"action": "list"}'

# Response
{
  "documents": [
    {
      "id": 142,
      "title": "hr-onboarding-guide.pdf",
      "chunks": 24,
      "uploaded_at": "2026-03-01T10:30:00Z",
      "status": "ready"
    },
    {
      "id": 98,
      "title": "employee-handbook-2025.pdf",
      "chunks": 87,
      "uploaded_at": "2026-02-15T14:22:00Z",
      "status": "ready"
    }
  ],
  "total": 2
}
                    

                            UPLOAD
                            Upload a document
                        
curl

                        curl -X POST https://ai.bluenotelogic.com/api/v2/documents.php \
  -H "X-API-Key: bnl_sk_abc123def456" \
  -F "action=upload" \
  -F "file=@/path/to/document.pdf"

# Response
{
  "success": true,
  "document_id": 210,
  "title": "document.pdf",
  "chunks": 15,
  "message": "Document uploaded and processed successfully."
}
                    

Ready to integrate CorpusAI?

Get your API key and start building. Three lines of code to AI-powered answers from your own documents.

Get API Key View Pricing

REST API

Get started in 3 steps

Sign Up

Set Your Header

Send JSON, Get Answers

Authentication

Rate Limits by Plan

Endpoints

Request Body (JSON)

Response (JSON)

Request Body (JSON)

Response (JSON)

Error Handling

HTTP Status Codes

Rate Limits & Usage

Response Headers

What Counts as a Request

Ready to integrate CorpusAI?