{ "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" }, { "key": "vector_id", "value": "", "type": "string" }, { "key": "assistant_id", "value": "", "type": "string" }, { "key": "notification_id", "value": "", "type": "string" }, { "key": "chat_id", "value": "", "type": "string" }, { "key": "embed_client_secret", "value": "", "type": "string" }, { "key": "embed_ticket", "value": "", "type": "string" } ], "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." }, { "name": "4. Files", "item": [ { "name": "List Files in Folder", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status is 200', function () {", " pm.response.to.have.status(200);", "});", "", "// Save first file ID for later requests", "const json = pm.response.json();", "if (json.files && json.files.length > 0) {", " pm.collectionVariables.set('file_id', json.files[0].id);", " console.log('Saved file_id:', json.files[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/:vectorId/files?limit=100&offset=0", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", ":vectorId", "files" ], "query": [ { "key": "limit", "value": "100" }, { "key": "offset", "value": "0" }, { "key": "status", "value": "completed", "disabled": true }, { "key": "search", "value": "report", "disabled": true } ], "variable": [ { "key": "vectorId", "value": "{{vector_id}}", "description": "Folder UUID (run 'List All Vectors' first to auto-populate)" } ] }, "description": "List the files in a folder and their ingestion status.\n\n### Query Parameters\n| Param | Type | Description |\n|-------|------|-------------|\n| `limit` | integer | Page size, default 100, max 500 |\n| `offset` | integer | Items to skip, default 0 |\n| `status` | string | Filter by ingestion status |\n| `search` | string | Case-insensitive filename search |\n\n### Response\n```json\n{\n \"collection\": \"vector-id\",\n \"total\": 12,\n \"limit\": 100,\n \"offset\": 0,\n \"files\": [\n {\n \"id\": \"file-uuid\",\n \"name\": \"report.pdf\",\n \"folder\": \"reports/2026\",\n \"relativePath\": \"vector-id/reports/2026/report.pdf\",\n \"size\": 248173,\n \"status\": \"completed\",\n \"phase\": \"done\",\n \"progress\": 100,\n \"error\": null,\n \"createdAt\": \"2026-01-15T10:30:00Z\",\n \"updatedAt\": \"2026-01-15T10:35:00Z\"\n }\n ]\n}\n```" }, "response": [] }, { "name": "Upload File", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [] }, { "key": "client_id", "value": "report-2026-q4", "type": "text", "disabled": true } ] }, "url": { "raw": "{{box_server_url}}/api/public/vectors/:vectorId/files", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", ":vectorId", "files" ], "variable": [ { "key": "vectorId", "value": "{{vector_id}}", "description": "Folder UUID to upload into" } ] }, "description": "Upload a document into a folder. The file is saved and queued for RAG ingestion.\n\n**Request:** `multipart/form-data` with the file in a field named `file` (the field `files` is also accepted). Send one file per request.\n\n### Form Fields\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `file` | file | Yes | The document to upload |\n| `relativePath` | text | No | Sub-folder path, e.g. `reports/2026/q4.pdf` |\n| `client_id` | text | No | Your own identifier, echoed back |\n\n### Response (202 Accepted)\n```json\n{\n \"status\": \"ok\",\n \"message\": \"File queued for ingestion pipeline\",\n \"collection\": \"vector-id\",\n \"files\": [\n {\n \"filename\": \"report.pdf\",\n \"originalFilename\": \"report.pdf\",\n \"client_id\": \"report-2026-q4\",\n \"size\": 248173,\n \"mimetype\": \"application/pdf\",\n \"relativePath\": \"vector-id/report.pdf\"\n }\n ],\n \"task_ids\": [\"task-uuid\"]\n}\n```\n\n**Note:** 202 means the file is queued, not yet indexed. Poll 'List Files in Folder' until `status` is `completed`. Max 5 GB per file. Unsupported types return 422.\n\n**Tip:** In the Body tab, select the `file` field and choose a local file. Run 'List All Vectors' first to auto-populate `vector_id`." }, "response": [] }, { "name": "Upload File to Sub-folder", "request": { "method": "POST", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [] }, { "key": "relativePath", "value": "reports/2026/q4.pdf", "type": "text" } ] }, "url": { "raw": "{{box_server_url}}/api/public/vectors/:vectorId/files", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", ":vectorId", "files" ], "variable": [ { "key": "vectorId", "value": "{{vector_id}}", "description": "Folder UUID to upload into" } ] }, "description": "Upload a file into a nested sub-folder using `relativePath`. The last path segment is the filename; missing folders are created automatically." }, "response": [] }, { "name": "Get File Metadata", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/vectors/:vectorId/files/:fileId", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", ":vectorId", "files", ":fileId" ], "variable": [ { "key": "vectorId", "value": "{{vector_id}}" }, { "key": "fileId", "value": "{{file_id}}", "description": "File UUID (run 'List Files in Folder' first to auto-populate)" } ] }, "description": "Get a single file's metadata. Returns `{ \"file\": { ... } }` with the same fields as a list entry." }, "response": [] }, { "name": "Download File", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/vectors/:vectorId/files/:fileId/content", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", ":vectorId", "files", ":fileId", "content" ], "variable": [ { "key": "vectorId", "value": "{{vector_id}}" }, { "key": "fileId", "value": "{{file_id}}" } ] }, "description": "Download the raw bytes of a file. Use 'Send and Download' in Postman to save it to disk. Cloud-backed files cannot be downloaded and return 415." }, "response": [] }, { "name": "Replace File", "request": { "method": "PUT", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [] } ] }, "url": { "raw": "{{box_server_url}}/api/public/vectors/:vectorId/files/:fileId", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", ":vectorId", "files", ":fileId" ], "variable": [ { "key": "vectorId", "value": "{{vector_id}}" }, { "key": "fileId", "value": "{{file_id}}" } ] }, "description": "Replace a file's contents in place. The old file (and its index data) is removed and the new file is re-ingested into the same sub-folder. Returns 202 Accepted, like an upload." }, "response": [] }, { "name": "Delete File", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/vectors/:vectorId/files/:fileId", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", ":vectorId", "files", ":fileId" ], "variable": [ { "key": "vectorId", "value": "{{vector_id}}" }, { "key": "fileId", "value": "{{file_id}}" } ] }, "description": "Delete a file from a folder (removes its chunks, metadata, and index data).\n\n### Response\n```json\n{\n \"status\": \"ok\",\n \"deleted\": true,\n \"file_id\": \"file-uuid\",\n \"errors\": []\n}\n```" }, "response": [] } ], "description": "Upload and manage the documents inside a folder (vector collection): list, upload, download, replace, and delete files.\n\nUploaded files are queued for RAG ingestion (202 Accepted) and become searchable in chat once indexed." }, { "name": "5. Notifications", "description": "Push notifications into the IntelligenceBox desktop app. Each notification is persisted before it is delivered, so one sent while the app was closed is replayed in the notification bell on the next launch.", "item": [ { "name": "Send Notification", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status is 201 or 202', function () {", " pm.expect(pm.response.code).to.be.oneOf([201, 202]);", "});", "", "const json = pm.response.json();", "if (json.notification && json.notification.id) {", " pm.collectionVariables.set('notification_id', json.notification.id);", " console.log('Saved notification_id:', json.notification.id);", "}" ], "type": "text/javascript" } } ], "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 \"title\": \"Deploy finished\",\n \"description\": \"api-gateway v2.4.1 is live in production.\",\n \"type\": \"success\",\n \"category\": \"backgroundTasks\",\n \"icon\": \"Rocket\",\n \"name\": \"CI pipeline\",\n \"deepLink\": \"/inter/chat/deploy-log-2f8a\"\n}" }, "url": { "raw": "{{box_server_url}}/api/public/notifications", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "notifications" ] }, "description": "Send a notification. `title` is required; everything else is optional.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `title` | string | Headline (required) |\n| `description` | string | Body text |\n| `type` | string | `info` \\| `success` \\| `error` |\n| `category` | string | Groups it and picks the glyph |\n| `deepLink` | string | In-app route opened on click, must start with `/` |\n| `icon` | string | Lucide icon name, e.g. `Rocket` |\n| `name` | string | Who it is from |\n| `read` | boolean | Create it already read |\n| `dedupeKey` | string | Collapse repeats into one row |\n| `silent` | boolean | Persist only, no popup or toast |" } }, { "name": "Send Notification (rich sender)", "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 \"title\": \"Marco Rossi mentioned you\",\n \"description\": \"can you review the Q3 numbers?\",\n \"category\": \"messaging\",\n \"deepLink\": \"/messaggi\",\n \"sender\": {\n \"kind\": \"user\",\n \"name\": \"Marco Rossi\",\n \"imageUrl\": \"https://example.com/avatars/marco.jpg\"\n }\n}" }, "url": { "raw": "{{box_server_url}}/api/public/notifications", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "notifications" ] }, "description": "Full control over the leading visual. `kind` picks the rendering: `system` shows a glyph, `user`/`assistant` show an avatar, `email` shows initials." } }, { "name": "List Notifications", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });", "pm.test('Has notifications array', function () {", " pm.expect(pm.response.json()).to.have.property('notifications');", "});" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/notifications?limit=20", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "notifications" ], "query": [ { "key": "limit", "value": "20" } ] }, "description": "Notifications for the API key owner, newest first. Query: `limit`, `offset`, `unreadOnly`, `category`." } }, { "name": "Unread Count", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/notifications/unread-count", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "notifications", "unread-count" ] }, "description": "Just the unread number, for a badge elsewhere." } }, { "name": "Get Notification", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/notifications/{{notification_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "notifications", "{{notification_id}}" ] }, "description": "One stored notification, including its metadata." } }, { "name": "Mark as Read", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"read\": true\n}" }, "url": { "raw": "{{box_server_url}}/api/public/notifications/{{notification_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "notifications", "{{notification_id}}" ] }, "description": "Mark read (also marks seen) or send `false` to return it to unread." } }, { "name": "Mark All Read", "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": "{}" }, "url": { "raw": "{{box_server_url}}/api/public/notifications/read-all", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "notifications", "read-all" ] }, "description": "Marks every unread notification read. Returns `{ updated: n }`." } }, { "name": "Delete Notification", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/notifications/{{notification_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "notifications", "{{notification_id}}" ] }, "description": "Removes it from the feed permanently." } } ] }, { "name": "6. Folders", "description": "Create and manage knowledge folders, and search inside them.", "item": [ { "name": "Create Folder", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });", "const json = pm.response.json();", "if (json.vector && json.vector.id) {", " pm.collectionVariables.set('vector_id', json.vector.id);", " console.log('Saved vector_id:', json.vector.id);", "}" ], "type": "text/javascript" } } ], "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 \"name\": \"Support tickets\",\n \"description\": \"Exported tickets, refreshed nightly\",\n \"strategy\": \"CHUNK\",\n \"topK\": 8,\n \"iconName\": \"LifeBuoy\",\n \"accentColor\": \"#E0F2FE\"\n}" }, "url": { "raw": "{{box_server_url}}/api/public/vectors", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors" ] }, "description": "Creates a folder and provisions its vector collection.\n\n`strategy` is fixed at creation: `CHUNK` (passages, the default), `DOCUMENT` (whole files), `TABULAR` (spreadsheets into SQL)." } }, { "name": "Update Folder", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"topK\": 12,\n \"filter\": 0.35\n}" }, "url": { "raw": "{{box_server_url}}/api/public/vectors/{{vector_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", "{{vector_id}}" ] }, "description": "Updates metadata and retrieval settings. Ingestion settings only affect documents uploaded after the change. `strategy` cannot be changed." } }, { "name": "Search in Folder", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });", "pm.test('Has results array', function () {", " pm.expect(pm.response.json()).to.have.property('results');", "});" ], "type": "text/javascript" } } ], "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 \"query\": \"What is the notice period for termination?\",\n \"limit\": 5\n}" }, "url": { "raw": "{{box_server_url}}/api/public/vectors/{{vector_id}}/search", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", "{{vector_id}}", "search" ] }, "description": "Semantic search with no LLM involved. Returns the matching passages with their source document and page." } }, { "name": "Delete Folder", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/vectors/{{vector_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "vectors", "{{vector_id}}" ] }, "description": "Irreversible: removes the folder, its documents, its vectors and its knowledge graph." } } ] }, { "name": "7. Assistants", "description": "Create and manage assistants: prompt, folders, tools.", "item": [ { "name": "Create Assistant", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });", "const json = pm.response.json();", "if (json.assistant && json.assistant.id) {", " pm.collectionVariables.set('assistant_id', json.assistant.id);", " console.log('Saved assistant_id:', json.assistant.id);", "}" ], "type": "text/javascript" } } ], "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 \"name\": \"Contract analyst\",\n \"description\": \"Answers questions about signed agreements\",\n \"instructions\": \"You are a contract analyst. Answer only from the documents provided, always cite the clause number, and say plainly when something is not covered.\",\n \"visibility\": \"PRIVATE\",\n \"icon\": \"Scale\",\n \"vectorIds\": [\n \"{{vector_id}}\"\n ],\n \"builtInTools\": {\n \"calculate\": true,\n \"webSearch\": false\n }\n}" }, "url": { "raw": "{{box_server_url}}/api/public/assistants", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "assistants" ] }, "description": "Creates an assistant owned by the API key's user. It appears in the desktop app immediately and can be used in chat requests." } }, { "name": "Update Assistant", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"instructions\": \"You are a contract analyst. Cite clause numbers. Flag anything unusual.\"\n}" }, "url": { "raw": "{{box_server_url}}/api/public/assistants/{{assistant_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "assistants", "{{assistant_id}}" ] }, "description": "Owner only. `vectorIds`, `builtInTools` and `suggestions` replace the previous value wholesale rather than merging." } }, { "name": "Delete Assistant", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/assistants/{{assistant_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "assistants", "{{assistant_id}}" ] }, "description": "Owner only. Conversations that used the assistant are kept." } } ] }, { "name": "8. Conversations", "description": "Read back and manage stored conversations.", "item": [ { "name": "List Conversations", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/chats?origin=API&limit=20", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "chats" ], "query": [ { "key": "origin", "value": "API" }, { "key": "limit", "value": "20" } ] }, "description": "Conversations for the key owner. `origin=API` returns only the ones created through this API." } }, { "name": "Get Conversation", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/chats/{{chat_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "chats", "{{chat_id}}" ] }, "description": "The conversation with its full transcript." } }, { "name": "Rename Conversation", "request": { "method": "PATCH", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Acme MSA \\u2014 notice period\"\n}" }, "url": { "raw": "{{box_server_url}}/api/public/chats/{{chat_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "chats", "{{chat_id}}" ] }, "description": "Renames the thread." } }, { "name": "Delete Conversation", "request": { "method": "DELETE", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/chats/{{chat_id}}", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "chats", "{{chat_id}}" ] }, "description": "Removes the conversation and every message in it." } } ] }, { "name": "9. Discovery", "description": "Ask the box who you are and what it can do.", "item": [ { "name": "Who Am I", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/me", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "me" ] }, "description": "Identity behind the API key, the workspace it resolved to, and a few counts. The cheapest meaningful health check." } }, { "name": "List Models", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/models", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "models" ] }, "description": "Local model plus every cloud model the box knows. Check `hasCredential` — a model without one cannot actually be used." } }, { "name": "List Tools", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/tools", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "tools" ] }, "description": "Built-in tool catalog. These keys go in `builtInTools` when creating an assistant." } }, { "name": "Capabilities", "request": { "method": "GET", "header": [ { "key": "x-api-key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{box_server_url}}/api/public/capabilities", "host": [ "{{box_server_url}}" ], "path": [ "api", "public", "capabilities" ] }, "description": "Machine-readable map of every public endpoint on this box." } } ] }, { "name": "10. External Apps", "description": "Ticket exchange for an installed external app (EMBED). The box opens the app in an iframe with ?ticket=; the app redeems it server-side and gets the launching user's identity plus an API key that acts as them.\n\nSet embed_client_secret and embed_ticket before running. This call does NOT use x-api-key — the client secret is the credential.", "item": [ { "name": "Exchange Launch Ticket", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status is 200', function () {", " pm.response.to.have.status(200);", "});", "", "const json = pm.response.json();", "if (json.apiKey && json.apiKey.key) {", " // The key is persistent: store it and reuse it for every", " // later call as this user.", " pm.collectionVariables.set('api_key', json.apiKey.key);", " console.log('Saved api_key for', json.user && json.user.email);", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{embed_api_key_from_launch}}", "type": "text", "description": "The apiKey field from the launch POST. There is no per-installation client secret." }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"ticket\": \"{{embed_ticket}}\"\n}" }, "url": { "raw": "{{auth_server_url}}/api/integrations/embed/exchange", "host": [ "{{auth_server_url}}" ], "path": [ "api", "integrations", "embed", "exchange" ] }, "description": "Redeem the single-use launch ticket for the identity of whoever opened the app. The launch POSTs ticket + apiKey + apiBaseUrl to your SSO path; the bearer here is that same apiKey." } } ] } ] }