Box

Access the Box API with managed OAuth authentication. Manage files, folders, collaborations, shared links, and cloud storage.

Reference

Get Current User

GET /box/2.0/users/me

Response:

{
  "type": "user",
  "id": "48806418054",
  "name": "Chris",
  "login": "chris@example.com",
  "created_at": "2026-02-08T13:12:34-08:00",
  "modified_at": "2026-02-08T13:12:35-08:00",
  "language": "en",
  "timezone": "America/Los_Angeles",
  "space_amount": 10737418240,
  "space_used": 0,
  "max_upload_size": 262144000,
  "status": "active",
  "avatar_url": "https://app.box.com/api/avatar/large/48806418054"
}

Get User

GET /box/2.0/users/{user_id}

Get Root Folder

The root folder has ID 0:

GET /box/2.0/folders/0

Get Folder

GET /box/2.0/folders/{folder_id}

Response:

{
  "type": "folder",
  "id": "365037181307",
  "name": "My Folder",
  "description": "Folder description",
  "size": 0,
  "path_collection": {
    "total_count": 1,
    "entries": [
      {"type": "folder", "id": "0", "name": "All Files"}
    ]
  },
  "created_by": {"type": "user", "id": "48806418054", "name": "Chris"},
  "owned_by": {"type": "user", "id": "48806418054", "name": "Chris"},
  "item_status": "active"
}

List Folder Items

GET /box/2.0/folders/{folder_id}/items

Query parameters:

limit - Maximum items to return (default 100, max 1000)
offset - Offset for pagination
fields - Comma-separated list of fields to include

Response:

{
  "total_count": 1,
  "entries": [
    {
      "type": "folder",
      "id": "365036703666",
      "name": "Subfolder"
    }
  ],
  "offset": 0,
  "limit": 100
}

Create Folder

POST /box/2.0/folders
Content-Type: application/json

{
  "name": "New Folder",
  "parent": {"id": "0"}
}

Response:

{
  "type": "folder",
  "id": "365037181307",
  "name": "New Folder",
  "created_at": "2026-02-08T14:56:17-08:00"
}

Update Folder

PUT /box/2.0/folders/{folder_id}
Content-Type: application/json

{
  "name": "Updated Folder Name",
  "description": "Updated description"
}

Copy Folder

POST /box/2.0/folders/{folder_id}/copy
Content-Type: application/json

{
  "name": "Copied Folder",
  "parent": {"id": "0"}
}

Delete Folder

DELETE /box/2.0/folders/{folder_id}

Query parameters:

recursive - Set to true to delete non-empty folders

Returns 204 No Content on success.

Get File Info

GET /box/2.0/files/{file_id}

Download File

GET /box/2.0/files/{file_id}/content

Returns a redirect to the download URL.

Upload File

Upload a new file (up to 50 MB for direct upload):

POST /box/api/2.0/files/content
Content-Type: multipart/form-data

attributes={"name":"file.txt","parent":{"id":"0"}}
file=<binary data>

The attributes field is a JSON string with:

name (required) - Filename to use
parent.id (required) - Folder ID to upload to (use "0" for root)
content_created_at - Optional timestamp
content_modified_at - Optional timestamp

Response:

{
  "total_count": 1,
  "entries": [
    {
      "type": "file",
      "id": "123456789",
      "name": "file.txt",
      "size": 1024,
      "created_at": "2026-04-14T10:00:00-07:00",
      "modified_at": "2026-04-14T10:00:00-07:00",
      "parent": {"type": "folder", "id": "0", "name": "All Files"}
    }
  ]
}

Note: Maton automatically routes upload endpoints to upload.box.com.

Upload New File Version

Upload a new version of an existing file:

POST /box/api/2.0/files/{file_id}/content
Content-Type: multipart/form-data

attributes={"name":"file.txt"}
file=<binary data>

Create Upload Session

POST /box/api/2.0/files/upload_sessions
Content-Type: application/json

{
  "folder_id": "0",
  "file_size": 104857600,
  "file_name": "large_file.zip"
}

Response:

{
  "id": "F971964745A5CD0C001BBE4E58196BFD",
  "type": "upload_session",
  "session_expires_at": "2026-04-15T10:00:00-07:00",
  "part_size": 8388608,
  "total_parts": 13,
  "num_parts_processed": 0,
  "session_endpoints": {
    "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
    "commit": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
    "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "status": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "abort": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD"
  }
}

Create Upload Session for New Version

POST /box/api/2.0/files/{file_id}/upload_sessions
Content-Type: application/json

{
  "file_size": 104857600,
  "file_name": "large_file.zip"
}

Upload Part

PUT /box/api/2.0/files/upload_sessions/{session_id}
Content-Type: application/octet-stream
Content-Range: bytes 0-8388607/104857600
Digest: sha=<base64-encoded SHA-1 of part>

<part data>

Response:

{
  "part": {
    "part_id": "6F2D3A7B8C4E5F6A",
    "offset": 0,
    "size": 8388608,
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  }
}

List Uploaded Parts

GET /box/api/2.0/files/upload_sessions/{session_id}/parts

Commit Upload Session

After all parts are uploaded:

POST /box/api/2.0/files/upload_sessions/{session_id}/commit
Content-Type: application/json
Digest: sha=<base64-encoded SHA-1 of entire file>

{
  "parts": [
    {"part_id": "6F2D3A7B8C4E5F6A", "offset": 0, "size": 8388608},
    {"part_id": "7G3E4B8D9F5A6C7B", "offset": 8388608, "size": 8388608}
  ]
}

Response: Returns the created file object.

Abort Upload Session

DELETE /box/api/2.0/files/upload_sessions/{session_id}

Returns 204 No Content on success

Update File Info

PUT /box/2.0/files/{file_id}
Content-Type: application/json

{
  "name": "renamed-file.txt",
  "description": "File description"
}

Copy File

POST /box/2.0/files/{file_id}/copy
Content-Type: application/json

{
  "name": "copied-file.txt",
  "parent": {"id": "0"}
}

Delete File

DELETE /box/2.0/files/{file_id}

Returns 204 No Content on success.

Get File Versions

GET /box/2.0/files/{file_id}/versions

Shared Links

Create a shared link by updating a file or folder:

PUT /box/2.0/folders/{folder_id}
Content-Type: application/json

{
  "shared_link": {
    "access": "open"
  }
}

Access levels:

open - Anyone with the link
company - Only users in the enterprise
collaborators - Only collaborators

Response includes:

{
  "shared_link": {
    "url": "https://app.box.com/s/sisarrztrenabyygfwqggbwommf8uucv",
    "access": "open",
    "effective_access": "open",
    "is_password_enabled": false,
    "permissions": {
      "can_preview": true,
      "can_download": true,
      "can_edit": false
    }
  }
}

List Folder Collaborations

GET /box/2.0/folders/{folder_id}/collaborations

Create Collaboration

POST /box/2.0/collaborations
Content-Type: application/json

{
  "item": {"type": "folder", "id": "365037181307"},
  "accessible_by": {"type": "user", "login": "user@example.com"},
  "role": "editor"
}

Roles: editor, viewer, previewer, uploader, previewer_uploader, viewer_uploader, co-owner

Update Collaboration

PUT /box/2.0/collaborations/{collaboration_id}
Content-Type: application/json

{
  "role": "viewer"
}

Delete Collaboration

DELETE /box/2.0/collaborations/{collaboration_id}

Search

GET /box/2.0/search?query=document

Query parameters:

query - Search query (required)
type - Filter by type: file, folder, web_link
file_extensions - Comma-separated extensions
ancestor_folder_ids - Limit to specific folders
limit - Max results (default 30)
offset - Pagination offset

Response:

{
  "total_count": 5,
  "entries": [...],
  "limit": 30,
  "offset": 0,
  "type": "search_results_items"
}

Events

GET /box/2.0/events

Query parameters:

stream_type - all, changes, sync, admin_logs
stream_position - Position to start from
limit - Max events to return

Response:

{
  "chunk_size": 4,
  "next_stream_position": "30401068076164269",
  "entries": [...]
}

List Trashed Items

GET /box/2.0/folders/trash/items

Get Trashed Item

GET /box/2.0/files/{file_id}/trash
GET /box/2.0/folders/{folder_id}/trash

Restore Trashed Item

POST /box/2.0/files/{file_id}
POST /box/2.0/folders/{folder_id}

Permanently Delete

DELETE /box/2.0/files/{file_id}/trash
DELETE /box/2.0/folders/{folder_id}/trash

List Collections

GET /box/2.0/collections

Response:

{
  "total_count": 1,
  "entries": [
    {
      "type": "collection",
      "name": "Favorites",
      "collection_type": "favorites",
      "id": "35223030868"
    }
  ]
}

Get Collection Items

GET /box/2.0/collections/{collection_id}/items

Recent Items

GET /box/2.0/recent_items

List Webhooks

GET /box/2.0/webhooks

Create Webhook

POST /box/2.0/webhooks
Content-Type: application/json

{
  "target": {"id": "365037181307", "type": "folder"},
  "address": "https://example.com/webhook",
  "triggers": ["FILE.UPLOADED", "FILE.DOWNLOADED"]
}

Note: Webhook creation may require enterprise permissions.

Delete Webhook

DELETE /box/2.0/webhooks/{webhook_id}

On this page