Skip to main content
The Box Hub items API allows you to:
At this stage, the API supports managing files, folders, and web links only. Elements such as callouts, dividers, paragraphs, or sections must be added in the Box Hubs web interface. Content added through the API is placed in the first content block.
Box Hubs endpoints require the box-version: 2025.0 header. If you omit this header, the API returns a 400 error with the message Missing required box-version header. Supported API versions: [2025.0]. For more information, see Box API versioning strategy.
The returns HTTP 207 (Multi-Status). The response body includes the status of each operation (add or remove). Follow the API reference for full response and error handling.

​
List hub items

To retrieve all items in a Box Hub, call the endpoint with the hub ID. 
curl -i -X GET "https://api.box.com/2.0/hub_items?hub_id=HUB_ID" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0"
Replace HUB_ID with your hub ID. You can use optional query parameters marker and limit for pagination. The response includes an entries array of hub items (each with id, type, name).

​
Add or remove hub items

To add or remove items in a hub, call the endpoint with the hub ID and a list of operations. Each operation has an action (add or remove) and an item reference (type and id).

​
Add a file to a hub

curl -i -X POST "https://api.box.com/2.0/hubs/HUB_ID/manage_items" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0" \
     -H "Content-Type: application/json" \
     -d '{
       "operations": [
         {
           "action": "add",
           "item": {
             "type": "file",
             "id": "FILE_ID"
           }
         }
       ]
     }'

​
Add a folder to a hub

curl -i -X POST "https://api.box.com/2.0/hubs/HUB_ID/manage_items" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0" \
     -H "Content-Type: application/json" \
     -d '{
       "operations": [
         {
           "action": "add",
           "item": {
             "type": "folder",
             "id": "FOLDER_ID"
           }
         }
       ]
     }'

​
Remove an item from a hub

curl -i -X POST "https://api.box.com/2.0/hubs/HUB_ID/manage_items" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0" \
     -H "Content-Type: application/json" \
     -d '{
       "operations": [
         {
           "action": "remove",
           "item": {
             "type": "file",
             "id": "FILE_ID"
           }
         }
       ]
     }'
Replace HUB_ID, FILE_ID, and FOLDER_ID with actual IDs. For web links, use "type": "web_link" and the web link ID. You can combine multiple add and remove operations in a single request.

​
Use cases

  • Automate hub creation: Use the or metadata queries to find content matching criteria, then add the filtered results to a hub with the manage hub items endpoint.
  • Event-driven updates: Use to react to events (for example, a new file in a folder) and add that content to a hub automatically.