{
	"info": {
		"_postman_id": "ib-box-server-api",
		"name": "IntelligenceBox Box Server API",
		"description": "# IntelligenceBox Box Server API\n\nComplete API collection for IntelligenceBox Box Server - your private AI assistant platform.\n\n## Quick Start\n\n1. **Get your API key** from IntelligenceBox app → Settings → API Keys\n2. **Set environment variables:**\n   - `box_server_url`: Your box server address (e.g., `{{box_server_url}}`)\n   - `api_key`: Your API key\n3. **Test connection** with Health Check endpoint\n4. **Get IDs** using List Vectors and List Assistants\n5. **Start chatting!**\n\n## Authentication\n\nAll protected endpoints require authentication via API Key:\n\n```\nx-api-key: YOUR_API_KEY\n```\n\nor\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n## Response Format\n\n### Chat Endpoint Response (SSE Stream)\n\nThe chat endpoint returns a **Server-Sent Events (SSE)** stream. Each event contains a JSON object with different types:\n\n```\ndata: {\"type\":\"text-delta\",\"textDelta\":\"Hello\"}\ndata: {\"type\":\"text-delta\",\"textDelta\":\" there\"}\ndata: {\"type\":\"text-delta\",\"textDelta\":\"!\"}\ndata: {\"type\":\"finish\",\"finishReason\":\"stop\"}\n```\n\n### Parsing SSE in JavaScript\n\n```javascript\nconst response = await fetch('{{box_server_url}}/api/ai/chat', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'x-api-key': 'YOUR_API_KEY'\n  },\n  body: JSON.stringify({\n    id: 'chat-123',\n    messages: [{ role: 'user', content: 'Hello' }],\n    boxAddress: '{{box_server_url}}'\n  })\n});\n\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\nlet fullText = '';\n\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n  \n  const chunk = decoder.decode(value);\n  const lines = chunk.split('\\n');\n  \n  for (const line of lines) {\n    if (line.startsWith('data: ')) {\n      const data = JSON.parse(line.slice(6));\n      if (data.type === 'text-delta') {\n        fullText += data.textDelta;\n        console.log(data.textDelta); // Real-time output\n      }\n    }\n  }\n}\n\nconsole.log('Full response:', fullText);\n```\n\n### Parsing SSE in Python\n\n```python\nimport requests\nimport json\n\nresponse = requests.post(\n    '{{box_server_url}}/api/ai/chat',\n    headers={\n        'Content-Type': 'application/json',\n        'x-api-key': 'YOUR_API_KEY'\n    },\n    json={\n        'id': 'chat-123',\n        'messages': [{'role': 'user', 'content': 'Hello'}],\n        'boxAddress': '{{box_server_url}}'\n    },\n    stream=True\n)\n\nfull_text = ''\nfor line in response.iter_lines():\n    if line:\n        line = line.decode('utf-8')\n        if line.startswith('data: '):\n            try:\n                data = json.loads(line[6:])\n                if data.get('type') == 'text-delta':\n                    full_text += data.get('textDelta', '')\n                    print(data.get('textDelta', ''), end='', flush=True)\n            except json.JSONDecodeError:\n                pass\n\nprint('\\nFull response:', full_text)\n```\n\n### Parsing SSE in cURL\n\n```bash\ncurl -N -X POST {{box_server_url}}/api/ai/chat \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -d '{\"id\":\"chat-123\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"boxAddress\":\"{{box_server_url}}\"}'\n```\n\n## Event Types\n\n| Type | Description |\n|------|-------------|\n| `text-delta` | Partial text chunk from AI response |\n| `tool-call` | AI is calling a tool (web search, etc.) |\n| `tool-result` | Result from tool execution |\n| `finish` | Stream completed |\n| `error` | Error occurred |\n\n## Error Handling\n\n| Status | Description |\n|--------|-------------|\n| 200 | Success (streaming response) |\n| 401 | Unauthorized - Invalid or missing API key |\n| 404 | Not found - Invalid endpoint or resource |\n| 429 | Rate limited - Too many requests |\n| 500 | Server error |\n\n## Support\n\nFor issues or questions, visit: https://github.com/anthropics/claude-code/issues",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"variable": [
		{
			"key": "box_server_url",
			"value": "https://your-box.intelligencebox.it",
			"type": "string",
			"description": "Your IntelligenceBox server URL (found in Settings → Device Info)"
		},
		{
			"key": "api_key",
			"value": "YOUR_API_KEY_HERE",
			"type": "string",
			"description": "Your API key from IntelligenceBox app settings"
		}
	],
	"item": [
		{
			"name": "1. Setup & Health",
			"item": [
				{
					"name": "Health Check",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									"pm.test('Server is healthy', function () {",
									"    pm.response.to.have.status(200);",
									"});",
									"",
									"pm.test('Response has status field', function () {",
									"    const json = pm.response.json();",
									"    pm.expect(json).to.have.property('status');",
									"});"
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "{{box_server_url}}/health",
							"host": ["{{box_server_url}}"],
							"path": ["health"]
						},
						"description": "Check if the box server is running and healthy.\n\n**No authentication required.**\n\n### Response\n```json\n{\n  \"status\": \"ok\",\n  \"version\": \"1.0.0\",\n  \"uptime\": 12345\n}\n```"
					},
					"response": []
				},
				{
					"name": "Server Info",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									"pm.test('Server responds', function () {",
									"    pm.response.to.have.status(200);",
									"});"
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"method": "GET",
						"header": [],
						"url": {
							"raw": "{{box_server_url}}/",
							"host": ["{{box_server_url}}"],
							"path": [""]
						},
						"description": "Get server version and build information.\n\n**No authentication required.**\n\n### Response\n```json\n{\n  \"name\": \"IntelligenceBox Server\",\n  \"version\": \"1.0.0\",\n  \"build\": \"2024-01-15\"\n}\n```"
					},
					"response": []
				}
			],
			"description": "Basic setup and health check endpoints to verify your connection."
		},
		{
			"name": "2. Get Resources",
			"item": [
				{
					"name": "List All Vectors (Folders)",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									"pm.test('Status is 200', function () {",
									"    pm.response.to.have.status(200);",
									"});",
									"",
									"pm.test('Response has vectors array', function () {",
									"    const json = pm.response.json();",
									"    pm.expect(json).to.have.property('vectors');",
									"    pm.expect(json.vectors).to.be.an('array');",
									"});",
									"",
									"// Save first vector ID for later use",
									"const json = pm.response.json();",
									"if (json.vectors && json.vectors.length > 0) {",
									"    pm.collectionVariables.set('vector_id', json.vectors[0].id);",
									"    console.log('Saved vector_id:', json.vectors[0].id);",
									"}"
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							}
						],
						"url": {
							"raw": "{{box_server_url}}/api/public/vectors",
							"host": ["{{box_server_url}}"],
							"path": ["api", "public", "vectors"]
						},
						"description": "Get all vectors (folders/collections) available to the authenticated user.\n\n**Vectors** are document collections that enable RAG (Retrieval Augmented Generation). When you chat with a vector, the AI searches your documents for relevant context.\n\n### Response\n```json\n{\n  \"vectors\": [\n    {\n      \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"name\": \"Company Documents\",\n      \"description\": \"Internal company policies and procedures\",\n      \"folder\": \"/path/to/folder\",\n      \"iconName\": \"Folder\",\n      \"accentColor\": \"#E0F2FE\",\n      \"createdAt\": \"2024-01-15T10:30:00Z\"\n    }\n  ]\n}\n```\n\n### Usage\nUse the `id` field as the `vector` parameter in chat requests to enable RAG for that folder."
					},
					"response": []
				},
				{
					"name": "List All Assistants",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									"pm.test('Status is 200', function () {",
									"    pm.response.to.have.status(200);",
									"});",
									"",
									"pm.test('Response has assistants array', function () {",
									"    const json = pm.response.json();",
									"    pm.expect(json).to.have.property('assistants');",
									"    pm.expect(json.assistants).to.be.an('array');",
									"});",
									"",
									"// Save first assistant ID for later use",
									"const json = pm.response.json();",
									"if (json.assistants && json.assistants.length > 0) {",
									"    pm.collectionVariables.set('assistant_id', json.assistants[0].id);",
									"    console.log('Saved assistant_id:', json.assistants[0].id);",
									"}"
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							}
						],
						"url": {
							"raw": "{{box_server_url}}/api/public/assistants",
							"host": ["{{box_server_url}}"],
							"path": ["api", "public", "assistants"]
						},
						"description": "Get all assistants available to the authenticated user.\n\n**Assistants** are customized AI personas with specific instructions, tools, and attached document folders.\n\n### Response\n```json\n{\n  \"assistants\": [\n    {\n      \"id\": \"550e8400-e29b-41d4-a716-446655440001\",\n      \"name\": \"Research Assistant\",\n      \"handle\": \"research\",\n      \"description\": \"Helps with research tasks\",\n      \"instructions\": \"You are a helpful research...\",\n      \"icon\": \"Search\",\n      \"color\": \"#3B82F6\",\n      \"vectorIds\": [\"vector-id-1\", \"vector-id-2\"],\n      \"vectors\": [\n        { \"id\": \"vector-id-1\", \"name\": \"Research Papers\" },\n        { \"id\": \"vector-id-2\", \"name\": \"Notes\" }\n      ],\n      \"createdAt\": \"2024-01-15T10:30:00Z\"\n    }\n  ]\n}\n```\n\n### Usage\nUse the `id` field as the `assistantId` parameter in chat requests.\n\n**Note:** Assistants may have vectors (folders) pre-configured. The `vectorIds` array shows which folders are attached."
					},
					"response": []
				},
				{
					"name": "Get Vector by ID",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									"pm.test('Status is 200 or 404', function () {",
									"    pm.expect(pm.response.code).to.be.oneOf([200, 404]);",
									"});"
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							}
						],
						"url": {
							"raw": "{{box_server_url}}/api/public/vectors/:vectorId",
							"host": ["{{box_server_url}}"],
							"path": ["api", "public", "vectors", ":vectorId"],
							"variable": [
								{
									"key": "vectorId",
									"value": "{{vector_id}}",
									"description": "Vector UUID (run 'List All Vectors' first to auto-populate)"
								}
							]
						},
						"description": "Get detailed information about a specific vector (folder).\n\n### Response\n```json\n{\n  \"vector\": {\n    \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"name\": \"Company Documents\",\n    \"description\": \"Internal company policies\",\n    \"folder\": \"/path/to/folder\",\n    \"topK\": 5,\n    \"filter\": 0,\n    \"strategy\": \"CHUNK\"\n  }\n}\n```"
					},
					"response": []
				},
				{
					"name": "Get Assistant by ID",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									"pm.test('Status is 200 or 404', function () {",
									"    pm.expect(pm.response.code).to.be.oneOf([200, 404]);",
									"});"
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							}
						],
						"url": {
							"raw": "{{box_server_url}}/api/public/assistants/:assistantId",
							"host": ["{{box_server_url}}"],
							"path": ["api", "public", "assistants", ":assistantId"],
							"variable": [
								{
									"key": "assistantId",
									"value": "{{assistant_id}}",
									"description": "Assistant UUID (run 'List All Assistants' first to auto-populate)"
								}
							]
						},
						"description": "Get detailed information about a specific assistant including full instructions and attached vectors.\n\n### Response\n```json\n{\n  \"assistant\": {\n    \"id\": \"550e8400-e29b-41d4-a716-446655440001\",\n    \"name\": \"Research Assistant\",\n    \"handle\": \"research\",\n    \"description\": \"Helps with research tasks\",\n    \"instructions\": \"You are a helpful research assistant...\",\n    \"builtInTools\": {\n      \"webSearch\": true,\n      \"calculate\": true\n    },\n    \"vectorIds\": [\"vector-id-1\"],\n    \"vectors\": [\n      {\n        \"id\": \"vector-id-1\",\n        \"name\": \"Research Papers\",\n        \"description\": \"Academic papers collection\"\n      }\n    ]\n  }\n}\n```"
					},
					"response": []
				}
			],
			"description": "Endpoints to list and retrieve vectors (folders) and assistants.\n\n**Tip:** Run these first to get the IDs you need for chat requests."
		},
		{
			"name": "3. Chat",
			"item": [
				{
					"name": "Basic Chat",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							},
							{
								"key": "Content-Type",
								"value": "application/json",
								"type": "text"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"id\": \"chat-{{$randomUUID}}\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hello! What can you help me with?\"\n    }\n  ],\n  \"boxAddress\": \"{{box_server_url}}\"\n}"
						},
						"url": {
							"raw": "{{box_server_url}}/api/ai/chat",
							"host": ["{{box_server_url}}"],
							"path": ["api", "ai", "chat"]
						},
						"description": "Basic chat request without any assistant or folders.\n\n### Request Body\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | string | Yes | Unique chat ID. Use same ID to continue conversation |\n| `messages` | array | Yes | Array of message objects |\n| `boxAddress` | string | Yes | Your box server URL |\n\n### Message Object\n| Field | Type | Description |\n|-------|------|-------------|\n| `role` | string | `user`, `assistant`, or `system` |\n| `content` | string | The message text |\n\n### Response\nServer-Sent Events (SSE) stream. See collection description for parsing examples.\n\n### Example Events\n```\ndata: {\"type\":\"text-delta\",\"textDelta\":\"Hello\"}\ndata: {\"type\":\"text-delta\",\"textDelta\":\"! I can help you with...\"}\ndata: {\"type\":\"finish\",\"finishReason\":\"stop\"}\n```"
					},
					"response": []
				},
				{
					"name": "Chat with Assistant",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							},
							{
								"key": "Content-Type",
								"value": "application/json",
								"type": "text"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"id\": \"chat-{{$randomUUID}}\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Hello! What can you help me with?\"\n    }\n  ],\n  \"boxAddress\": \"{{box_server_url}}\",\n  \"assistantId\": \"{{assistant_id}}\"\n}"
						},
						"url": {
							"raw": "{{box_server_url}}/api/ai/chat",
							"host": ["{{box_server_url}}"],
							"path": ["api", "ai", "chat"]
						},
						"description": "Chat with a specific assistant. The assistant's instructions, tools, and configured folders will be used.\n\n### Additional Parameters\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `assistantId` | string | Yes | Assistant UUID from 'List All Assistants' |\n\n### How it works\n1. The assistant's custom instructions are applied\n2. Any folders attached to the assistant enable RAG automatically\n3. Built-in tools configured for the assistant are available\n\n**Tip:** Run 'List All Assistants' first to auto-populate the `assistant_id` variable."
					},
					"response": []
				},
				{
					"name": "Chat with Folder (RAG)",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							},
							{
								"key": "Content-Type",
								"value": "application/json",
								"type": "text"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"id\": \"chat-{{$randomUUID}}\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What information do you have in my documents?\"\n    }\n  ],\n  \"boxAddress\": \"{{box_server_url}}\",\n  \"vector\": [\"{{vector_id}}\"]\n}"
						},
						"url": {
							"raw": "{{box_server_url}}/api/ai/chat",
							"host": ["{{box_server_url}}"],
							"path": ["api", "ai", "chat"]
						},
						"description": "Chat with RAG (Retrieval Augmented Generation) using a specific folder.\n\n### Additional Parameters\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `vector` | array | Yes | Array of vector (folder) UUIDs |\n\n### How RAG works\n1. Your question is used to search the folder's indexed documents\n2. Relevant document chunks are retrieved\n3. The AI uses these chunks as context to answer your question\n4. Sources are cited in the response\n\n### Multiple Folders\nYou can search multiple folders at once:\n```json\n\"vector\": [\"folder-id-1\", \"folder-id-2\", \"folder-id-3\"]\n```\n\n**Tip:** Run 'List All Vectors' first to auto-populate the `vector_id` variable."
					},
					"response": []
				},
				{
					"name": "Chat with Assistant + Folder",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							},
							{
								"key": "Content-Type",
								"value": "application/json",
								"type": "text"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"id\": \"chat-{{$randomUUID}}\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Analyze my documents and give me a summary\"\n    }\n  ],\n  \"boxAddress\": \"{{box_server_url}}\",\n  \"assistantId\": \"{{assistant_id}}\",\n  \"vector\": [\"{{vector_id}}\"]\n}"
						},
						"url": {
							"raw": "{{box_server_url}}/api/ai/chat",
							"host": ["{{box_server_url}}"],
							"path": ["api", "ai", "chat"]
						},
						"description": "Combine an assistant with additional folders.\n\n### How it works\n- Assistant's custom instructions are applied\n- Assistant's pre-configured folders are searched\n- Additional folders specified in `vector` are ALSO searched\n- All tools from the assistant are available\n\nThis is the most powerful option - you get:\n- Custom AI behavior from the assistant\n- RAG from both assistant's folders AND your specified folders"
					},
					"response": []
				},
				{
					"name": "Continue Conversation",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							},
							{
								"key": "Content-Type",
								"value": "application/json",
								"type": "text"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"id\": \"my-conversation-123\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What is the capital of France?\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"The capital of France is Paris.\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"What is its population?\"\n    }\n  ],\n  \"boxAddress\": \"{{box_server_url}}\"\n}"
						},
						"url": {
							"raw": "{{box_server_url}}/api/ai/chat",
							"host": ["{{box_server_url}}"],
							"path": ["api", "ai", "chat"]
						},
						"description": "Continue an existing conversation with full context.\n\n### Important Rules\n1. **Same ID**: Use the SAME `id` as the original conversation\n2. **Full History**: Include ALL previous messages in order\n3. **Append New**: Add your new message at the end\n\n### Message History Format\n```json\n{\n  \"messages\": [\n    { \"role\": \"user\", \"content\": \"First question\" },\n    { \"role\": \"assistant\", \"content\": \"First answer\" },\n    { \"role\": \"user\", \"content\": \"Follow-up question\" },\n    { \"role\": \"assistant\", \"content\": \"Follow-up answer\" },\n    { \"role\": \"user\", \"content\": \"Your new question here\" }\n  ]\n}\n```\n\n### Why include full history?\nThe AI uses the conversation history to understand context. Without it, follow-up questions like \"What about its population?\" won't make sense."
					},
					"response": []
				},
				{
					"name": "Get Stream Status",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							}
						],
						"url": {
							"raw": "{{box_server_url}}/api/ai/chat/:chatId/stream-status",
							"host": ["{{box_server_url}}"],
							"path": ["api", "ai", "chat", ":chatId", "stream-status"],
							"variable": [
								{
									"key": "chatId",
									"value": "your-chat-id",
									"description": "The chat ID you used in the chat request"
								}
							]
						},
						"description": "Check the status of an active chat stream.\n\n### Response\n```json\n{\n  \"status\": \"active\",\n  \"isActive\": true,\n  \"startTime\": \"2024-01-15T10:30:00Z\",\n  \"lastActivity\": \"2024-01-15T10:30:05Z\",\n  \"messageCount\": 42,\n  \"accumulatedText\": \"Hello! I can help you with...\"\n}\n```\n\n### Status Values\n| Status | Description |\n|--------|-------------|\n| `active` | Stream is currently generating |\n| `completed` | Stream finished successfully |\n| `aborted` | Stream was stopped by user |\n| `error` | An error occurred |\n| `not_found` | No stream found for this chat ID |"
					},
					"response": []
				},
				{
					"name": "Stop Stream",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "x-api-key",
								"value": "{{api_key}}",
								"type": "text"
							}
						],
						"url": {
							"raw": "{{box_server_url}}/api/ai/chat/:chatId/stop",
							"host": ["{{box_server_url}}"],
							"path": ["api", "ai", "chat", ":chatId", "stop"],
							"variable": [
								{
									"key": "chatId",
									"value": "your-chat-id",
									"description": "The chat ID you want to stop"
								}
							]
						},
						"description": "Stop/abort an active chat stream.\n\nUseful when:\n- The response is too long\n- You want to cancel a request\n- The AI is going off-topic\n\n### Response\n```json\n{\n  \"success\": true,\n  \"message\": \"Stream stopped successfully\"\n}\n```"
					},
					"response": []
				}
			],
			"description": "Chat endpoints for interacting with AI assistants and RAG-enabled folders.\n\n**Response Format:** All chat endpoints return Server-Sent Events (SSE) streams. See the collection description for parsing examples in JavaScript, Python, and cURL."
		}
	]
}