Endpoints

Una lista con endpoints públicos para procesar datos

Overview

The BrainBox API exposes 7 public endpoints organized into three groups. All endpoints require Bearer token authentication and return JSON responses with a consistent success field.

Base URL
https://app.brainbox.com.co/api/public/v1

Each endpoint below includes its full path, parameters, request body examples, and response format. Endpoints that consume intelligence units are clearly marked with their cost. Click Try it on any endpoint to open the interactive request builder in the sidebar — it will pre-fill the method, path, and parameters so you can test directly from this page.

Autenticación

BrainBox autentica las solicitudes de la API usando Tokens Bearer. Debes incluir una clave de API en el Authorization encabezado de cada solicitud.

Authorization: Bearer YOUR_API_KEY

Tu Clave de API

Puedes generar y administrar claves de API desde el panel de BrainBox en Cuenta → Claves de API. Las claves siguen el formato: bbfe_[prefix]_[secret_key]

Global routes

General-purpose endpoints for verifying connectivity and authentication status. Use these to confirm your API key is valid before making data requests.

Health Check

GET/api/public/v1/check

Consume 0 unidades de inteligencia.

Verifies API access and authentication. Use this endpoint to confirm your API key is valid and the service is operational. Returns a simple success message if authentication passes. This is the recommended first call when integrating with the BrainBox API.

Response

{
  "success": true,
  "message": "The check access complete"
}

Boxes routes

Endpoints for interacting with Boxes — your document collections. Search documents with AI-powered semantic search, retrieve full document content, manage files and folders (create, move, rename, trash/restore/purge), upload from URL, and ask questions using OpenAI-compatible chat completions.

List Boxes

GET/api/public/v1/boxes

Consume 0 unidades de inteligencia.

Lists the boxes accessible to the API key. Supports pagination, name search, sort order, tag filters, and optional workspace filtering for user-scoped keys.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
page	Path	number	No	Page number. Defaults to 1.
limit	Path	number	No	Items per page. Defaults to 50, max 100.
query	Path	string	No	Case-insensitive box name filter.
sort	Path	string	No	Sort by last interaction: "asc" or "desc".
tags	Path	string	No	Comma-separated tag IDs. Boxes must match all provided tags.
workspaceId	Path	string	No	Optional workspace filter for user-scoped keys. Use "personal" for boxes without a workspace.

Response

{
  "success": true,
  "data": {
    "boxes": [
      {
        "box_id": "box_123",
        "name": "Q4 Research",
        "role": "owner",
        "owner": "owner@example.com",
        "file_count": 8
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "hasMore": false
    }
  }
}

Create Box

POST/api/public/v1/boxes

Consume 0 unidades de inteligencia.

Creates a new box, optionally attaches files, and optionally seeds the ACL with direct members or invitations.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
name	Body	string	Yes	Box name.
fileIds	Body	array	No	Files to attach immediately after creation.
users	Body	array	No	Initial ACL members as `{ email, role }`.
workspaceId	Body	string	No	Workspace for the new box. Ignored when the API key is already workspace-scoped.
notify	Body	number	No	Send invitation emails for pending users.

Request body

{
  "name": "Vendor Review",
  "fileIds": ["file_123"],
  "users": [
    { "email": "editor@example.com", "role": "editor" },
    { "email": "viewer@example.com", "role": "viewer" }
  ],
  "notify": false
}

Response

{
  "success": true,
  "data": {
    "box_id": "box_123",
    "usersNotFound": [],
    "directMembers": ["editor@example.com"],
    "pendingInvitations": ["viewer@example.com"],
    "notificationFailures": []
  }
}

Get Box

GET/api/public/v1/boxes/:box

Consume 0 unidades de inteligencia.

Returns metadata for a single accessible box, including the caller's effective role.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID

Response

{
  "success": true,
  "data": {
    "box": {
      "box_id": "box_123",
      "name": "Vendor Review",
      "status": "active"
    },
    "role": "admin"
  }
}

Get Box ACL

GET/api/public/v1/boxes/:box/acl

Consume 0 unidades de inteligencia.

Returns the current box ACL, including direct members, pending invitations, and the public link when one exists. Requires owner or admin access.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID

Response

{
  "success": true,
  "data": {
    "users": [
      { "user_id": "user_1", "email": "owner@example.com", "role": "owner" },
      { "user_id": "user_2", "email": "editor@example.com", "role": "editor" }
    ],
    "publicUsersCount": 0,
    "pendingInvitations": [
      { "id": "inv_1", "email": "viewer@example.com", "role": "viewer" }
    ],
    "publicLink": null
  }
}

Replace Box ACL

PATCH/api/public/v1/boxes/:box/acl

Consume 0 unidades de inteligencia.

Bulk-replaces all non-owner box members in one request. Owners are preserved automatically.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
users	Body	array	Yes	Final non-owner member list as `{ email, role }`.
notify	Body	number	No	Send notification emails for changed members.

Request body

{
  "users": [
    { "email": "admin@example.com", "role": "admin" },
    { "email": "viewer@example.com", "role": "viewer" }
  ],
  "notify": false
}

Add ACL Member

POST/api/public/v1/boxes/:box/acl/members

Consume 0 unidades de inteligencia.

Adds a single direct member or invitation without requiring the client to submit the full ACL list.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
email	Body	string	Yes	Member email.
role	Body	string	Yes	One of "viewer", "editor", or "admin".

Update ACL Member

PATCH/api/public/v1/boxes/:box/acl/members/:member

Consume 0 unidades de inteligencia.

Changes the role for one existing member or invitation. The `member` path value is the URL-encoded email address.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
member	Path	string	Yes	URL-encoded member email.
role	Body	string	Yes	One of "viewer", "editor", or "admin".

Remove ACL Member

DELETE/api/public/v1/boxes/:box/acl/members/:member

Consume 0 unidades de inteligencia.

Removes a direct member or pending invitation. Owners cannot be removed through this endpoint.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
member	Path	string	Yes	URL-encoded member email.

OpenAI-Compatible Chat Completions (Ask Box)

POST/api/public/v1/boxes/:box/chat/completions

Consume 1-10 (estimated/final) unidades de inteligencia.

OpenAI Chat Completions–compatible endpoint to ask a Box strictly over its documents. Supports streaming, file scoping, and model presets. The response follows the OpenAI Chat Completions format, making it a drop-in replacement for any OpenAI-compatible client library. Intelligence unit consumption varies based on query complexity and the amount of context retrieved.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
model	Body	string	No	One of "auto" \| "default" \| "precise" \| "pro" \| "teacher". Defaults to "auto".
messages	Body	array	Yes	OpenAI-style messages array. At least one user message is required.
stream	Body	number	No	Enable Server-Sent Events streaming (true/false).
temperature	Body	number	No	Sampling temperature (0.0–2.0). Defaults to provider preset if omitted.
source_file_ids	Body	array	No	Array of file IDs to scope retrieval. If omitted, all indexed files in the box are considered.
full_context	Body	number	No	If true and small enough, uses big-context (full sources). Otherwise auto-selects retrieval mode.

Límites Técnicos

Límite	Valor
Request Timeout	800 seconds
Streaming	SSE (text/event-stream)
Usage (stream)	Final stop chunk includes usage with intelligence_units

Request body

{
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": "What are the key takeaways from the Q4 report?"
    }
  ],
  "stream": false,
  "temperature": 0.7,
  "source_file_ids": ["file_123", "file_456"]
}

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Based on the Q4 report, the key takeaways are..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "intelligence_units": 3
  }
}

Retrieve Relevant Document Chunks

POST/api/public/v1/boxes/:box_id/retrieve-documents

Consume 1-5 unidades de inteligencia.

Performs semantic search with AI reranking to find the most relevant text chunks across your indexed documents. Uses vector embeddings and a reranking model to understand query intent and return highly relevant passages. Results include the source file, page number, and a relevance score. Optionally scope the search to specific files using the sources parameter.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box_id	Path	string	Yes	Box ID
query	Body	string	Yes	Natural language search query
sources	Body	array	No	Array of file IDs to search within. If omitted, all indexed files are searched.

Límites Técnicos

Límite	Valor
Request Timeout	500 seconds
Max Vector Results	50 (before rerank)
Min Relevance Score	0.1

Request body

{
  "query": "What is machine learning?",
  "sources": ["file_123", "file_456"]
}

Response

{
  "success": true,
  "data": {
    "documents": [
      {
        "documents": [
          {
            "text": "Machine learning is a subset of artificial intelligence...",
            "page": 3,
            "fileName": "AI_Guide.pdf",
            "fileId": "file_123",
            "source": "Main",
            "link": "https://app.brainbox.com.co/workspace/boxes/BOX_ID/?file=file_123&page=3"
          }
        ]
      }
    ],
    "usage": {
      "intelligence_units_consumed": 1
    }
  }
}

Retrieve Full Documents

POST/api/public/v1/boxes/:box_id/retrieve-full-documents

Consume 0 unidades de inteligencia.

Retrieves the complete, ordered text content for specified documents (max 10 per request). Returns every page of each document with its full text, preserving page order. This endpoint is free — it does not consume intelligence units. Useful for extracting full content for downstream processing, RAG pipelines, or document export.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box_id	Path	string	Yes	Box ID
sources	Body	array	Yes	Array of file IDs to retrieve (max 10)

Límites Técnicos

Límite	Valor
Max Documents per Request	10 files

Request body

{
  "sources": ["file_123", "file_456"]
}

Response

{
  "success": true,
  "data": {
    "documents": [
      {
        "fileId": "file_123",
        "fileName": "Report_2024.pdf",
        "mediaType": "pdf",
        "pages": [
          {
            "pageNumber": 1,
            "text": "Executive Summary...",
            "link": "https://app.brainbox.com.co/workspace/boxes/BOX_ID/?file=file_123&page=1"
          }
        ]
      }
    ],
    "usage": {
      "documents_retrieved": 2,
      "total_pages": 15
    }
  }
}

Upload & Index File

POST/api/public/v1/boxes/:box/upload

Consume Variable unidades de inteligencia.

Uploads a file into a box and runs the full indexing pipeline (parse, chunk, embed, vectorize). Two modes (non-breaking): (1) JSON with `url` — BrainBox downloads from an HTTPS URL (up to 2 GB); (2) multipart/form-data with a `file` field — direct binary upload, max 4 MB. For larger files use the URL mode. Optionally place the file inside a folder with `folderId`. Supports PDF, Office documents, images, CSV, text files, and audio/video. Intelligence unit cost varies by file type and size. Requires owner or admin role on the box.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
url	Body	string	No	JSON mode: HTTPS URL of the file to download and index. Required when not sending multipart `file`.
file	Body	string	No	Multipart mode: binary file field. Max 4 MB. Required when not sending JSON `url`.
fileName	Body	string	No	Custom file name. If omitted, derived from the URL or uploaded file name.
folderId	Body	string	No	Optional target folder inside the box. Omit to place the file at the box root.

Límites Técnicos

Límite	Valor
Max File Size (URL mode)	2 GB
Max File Size (direct multipart)	4 MB
Request Timeout	800 seconds
Connection Timeout	30 seconds (URL fetch)
URL Scheme	HTTPS only (URL mode)

Request body

// JSON + URL mode
{
  "url": "https://example.com/reports/annual-report-2024.pdf",
  "fileName": "Annual Report 2024.pdf",
  "folderId": "folder_123"
}

// Direct multipart mode (files <= 4 MB)
// Content-Type: multipart/form-data
// fields: file (binary), fileName? (string), folderId? (string)

Response

{
  "success": true,
  "data": {
    "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Annual_Report_2024.pdf",
    "media_type": "acrobat",
    "storage_size": 2458000,
    "box_id": "your-box-id",
    "parent_id": "folder_123",
    "source": "direct"
  }
}

List Box Files

GET/api/public/v1/boxes/:box/files

Consume 0 unidades de inteligencia.

Returns all indexed files in the box with metadata including file name, media type, parent folder, page count, character count, storage size, tags, and creation date. Use `folderId` to list only files inside a folder (`root` for the box root). Requires owner or admin role on the box. This endpoint is free and does not consume intelligence units.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
folderId	Path	string	No	Filter by parent folder id. Use "root" to list only files at the box root.

Response

{
  "success": true,
  "data": {
    "files": [
      {
        "fileId": "file_123",
        "name": "document.pdf",
        "mediaType": "pdf",
        "parentId": "folder_123",
        "pages": 10,
        "charCount": 12345,
        "storageSize": 123456,
        "tags": [],
        "createdAt": "2023-01-01T00:00:00.000Z"
      }
    ],
    "usage": { "files": 1 }
  }
}

Move or Rename File

PATCH/api/public/v1/boxes/:box/files/:file

Consume 0 unidades de inteligencia.

Renames a file and/or moves it to another folder inside the box. Send `name`, `parentId`, or both. Use `parentId: null` to move the file back to the box root. Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
file	Path	string	Yes	File ID
name	Body	string	No	New file name
parentId	Body	string	No	Target folder ID, or null for the box root

Request body

{
  "name": "renamed.pdf",
  "parentId": "folder_123"
}

Response

{
  "success": true,
  "data": {
    "fileId": "file_123",
    "name": "renamed.pdf",
    "parentId": "folder_123"
  }
}

Move File to Trash

DELETE/api/public/v1/boxes/:box/files/:file

Consume 0 unidades de inteligencia.

Soft-deletes a file by moving it to the box trash. Storage, vectors and database rows are kept so restore is instant. Permanent deletion only happens via the trash purge endpoint. Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
file	Path	string	Yes	File ID

Response

{
  "success": true,
  "data": {
    "fileId": "file_123",
    "trashed": true
  }
}

List Trash

GET/api/public/v1/boxes/:box/files/trash

Consume 0 unidades de inteligencia.

Lists every file and folder currently in the box trash. Trashed items keep their content and can be restored. Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "fileId": "file_123",
        "name": "document.pdf",
        "type": "file",
        "parentId": null,
        "updatedAt": "2026-08-01T00:00:00.000Z",
        "userId": "user_123"
      }
    ],
    "usage": { "items": 1 }
  }
}

Restore from Trash

POST/api/public/v1/boxes/:box/files/trash

Consume 0 unidades de inteligencia.

Restores selected items from the box trash back to their original location. Works for both files and folders (folders restore their whole subtree). Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
fileIds	Body	array	Yes	IDs of the trashed items to restore

Request body

{
  "fileIds": ["file_123", "folder_456"]
}

Response

{
  "success": true,
  "data": {
    "restored": ["file_123", "folder_456"]
  },
  "errors": []
}

Purge Trash

DELETE/api/public/v1/boxes/:box/files/trash

Consume 0 unidades de inteligencia.

Permanently deletes selected trashed items, or the whole trash when `empty: true` is sent. Purged items cannot be recovered. Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
fileIds	Body	array	No	IDs of trashed items to purge
empty	Body	string	No	Set to true to empty the whole trash. Provide either fileIds or empty.

Request body

{
  "empty": true
}

Response

{
  "success": true,
  "data": {
    "purgedCount": 5
  }
}

List Folders

GET/api/public/v1/boxes/:box/folders

Consume 0 unidades de inteligencia.

Returns every folder inside a box as a flat list (excluding trashed and private items). Each folder includes its `parentId` so clients can rebuild the tree. Filter with `parentId` (`root` for top-level folders). Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
parentId	Path	string	No	Filter by parent folder id. Use "root" to list only top-level folders.

Response

{
  "success": true,
  "data": {
    "folders": [
      {
        "folderId": "folder_123",
        "name": "Contracts",
        "parentId": null,
        "createdAt": "2026-08-01T00:00:00.000Z"
      }
    ],
    "usage": { "folders": 1 }
  }
}

Create Folder

POST/api/public/v1/boxes/:box/folders

Consume 0 unidades de inteligencia.

Creates a folder inside a box, optionally nested under another folder via `parentId`. Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
name	Body	string	Yes	Folder name
parentId	Body	string	No	Parent folder id. Omit or send null for the box root.

Request body

{
  "name": "Contracts",
  "parentId": null
}

Response

{
  "success": true,
  "data": {
    "folderId": "folder_123",
    "name": "Contracts",
    "parentId": null
  }
}

Move or Rename Folder

PATCH/api/public/v1/boxes/:box/folders/:folder

Consume 0 unidades de inteligencia.

Renames a folder and/or moves it under another folder. Send `name`, `parentId`, or both. Use `parentId: null` for the box root. Moving a folder into itself or one of its subfolders is rejected. Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
folder	Path	string	Yes	Folder ID
name	Body	string	No	New folder name
parentId	Body	string	No	Target parent folder id, or null for the box root

Request body

{
  "name": "2026 Contracts",
  "parentId": "folder_parent"
}

Response

{
  "success": true,
  "data": {
    "folderId": "folder_123",
    "name": "2026 Contracts",
    "parentId": "folder_parent"
  }
}

Move Folder to Trash

DELETE/api/public/v1/boxes/:box/folders/:folder

Consume 0 unidades de inteligencia.

Soft-deletes a folder and everything inside it (subfolders and files) by moving the whole subtree to the box trash. Restore later from the trash; permanent deletion only happens via trash purge. Deleting a folder that contains items created by other members requires the admin role. Requires owner or admin role on the box. This endpoint is free.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
box	Path	string	Yes	Box ID
folder	Path	string	Yes	Folder ID

Response

{
  "success": true,
  "data": {
    "folderId": "folder_123",
    "trashedCount": 4
  }
}

Files

Endpoints for working with individual files. Currently supports generating temporary signed URLs for direct file downloads.

Get File Signed URL

GET/api/public/v1/files/:id/signed-url

Consume 0 unidades de inteligencia.

Generates a temporary signed URL for downloading a file directly. The URL is valid for 10 minutes (600 seconds) and provides direct access to the file's storage location. Use this when you need to download the original file rather than its extracted text content.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
id	Path	string	Yes	File ID

Response

{
  "success": true,
  "data": {
    "name": "document.pdf",
    "mediaType": "pdf",
    "signedUrl": "https://storage.googleapis.com/...",
    "expiresIn": 600
  }
}