API Reference

IntelligenceBox exposes an OpenAI-compatible REST API on your local network. Connect using your Box’s IP address or hostname.

Base URL

Find your Box’s address in the IntelligenceBox app under Settings → Device Info.

http://<your-box-ip>:3001

Example: http://192.168.1.100:3001 or http://intelligencebox.local:3001

Authentication

All requests require an API key. Create one in the app: Settings → API Keys → Create New Key.

x-api-key: YOUR_API_KEY

Or use Bearer token format (for OpenAI SDK compatibility):

Authorization: Bearer YOUR_API_KEY

Chat Completions

OpenAI-compatible chat API. Works with any OpenAI SDK.

Endpoint: POST /v1/chat/completions

Request

curl -X POST "http://<your-box-ip>:3001/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-cinziapro",
    "messages": [
      {"role": "user", "content": "Summarize my uploaded contracts"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

Parameters

Parameter	Type	Description
`model`	string	Model name (use `gpt-oss-cinziapro`)
`messages`	array	Array of message objects with `role` and `content`
`temperature`	number	0-2, controls randomness (default: 0.7)
`stream`	boolean	Enable SSE streaming (default: false)
`max_tokens`	number	Maximum tokens in response

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699000000,
  "model": "gpt-oss-cinziapro",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Based on your contracts..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 150,
    "total_tokens": 200
  }
}

File Upload

Upload documents for RAG (Retrieval-Augmented Generation). Files are indexed and become searchable.

Endpoint: POST /api/upload

Request

curl -X POST "http://<your-box-ip>:3001/api/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "collection=my-project"

Parameters

Parameter	Type	Description
`file`	file	Document to upload (PDF, DOCX, TXT, images)
`collection`	string	Collection name for organizing documents

Supported Formats

PDF (with OCR for scanned documents)
Microsoft Word (.docx, .doc)
Plain text (.txt, .md)
Images (.jpg, .png) - text is extracted
Excel (.xlsx)

Vector Search

Search through indexed documents semantically.

Endpoint: POST /api/vectors/search

Request

curl -X POST "http://<your-box-ip>:3001/api/vectors/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "termination clauses",
    "collection": "my-project",
    "topK": 5
  }'

Parameters

Parameter	Type	Description
`query`	string	Search query in natural language
`collection`	string	Filter by collection name
`topK`	number	Number of results (default: 5)

Response

{
  "results": [
    {
      "id": "chunk_123",
      "score": 0.89,
      "content": "The agreement may be terminated...",
      "metadata": {
        "filename": "contract.pdf",
        "page": 12
      }
    }
  ]
}

SDK Examples

Node.js

import OpenAI from "openai";
 
const client = new OpenAI({
  baseURL: "http://192.168.1.100:3001/v1",
  apiKey: "YOUR_API_KEY",
});
 
const response = await client.chat.completions.create({
  model: "gpt-oss-cinziapro",
  messages: [{ role: "user", content: "Hello!" }],
});
 
console.log(response.choices[0].message.content);

Python

from openai import OpenAI
 
client = OpenAI(
    base_url="http://192.168.1.100:3001/v1",
    api_key="YOUR_API_KEY",
)
 
response = client.chat.completions.create(
    model="gpt-oss-cinziapro",
    messages=[{"role": "user", "content": "Hello!"}],
)
 
print(response.choices[0].message.content)

cURL with Streaming

curl -X POST "http://<your-box-ip>:3001/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-oss-cinziapro", "messages": [{"role": "user", "content": "Hello"}], "stream": true}'

Models

List available models on your Box.

Endpoint: GET /v1/models

curl "http://<your-box-ip>:3001/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Health Check

Check if your Box is running.

Endpoint: GET /health

curl "http://<your-box-ip>:3001/health"

Error Codes

Code	Description
400	Invalid request body or parameters
401	Missing or invalid API key
404	Endpoint or resource not found
500	Server error

Error response format:

{
  "error": {
    "message": "Invalid API key",
    "type": "auth_error",
    "code": "unauthorized"
  }
}

🎬 Video Guide Building MCP Servers