Box Content API: files, folders, sharing and search

Box is the enterprise content client for files, folders and collaboration. After OAuth sign-in the home screen loads the signed-in identity and storage quota from /v1/users/me (login, space_amount, space_used), then pages All Files from /v1/folders/{folderId}/items.

Sharing, search and recents ride the same Bearer token: /v1/shared-links/resolve turns a shared link into the underlying item, /v1/search runs full-text queries, and /v1/recents feeds the Recents tab. Collaborators, comments, events and the hubs GraphQL route sit on the same session.

Box is the official Android client for Box's enterprise content platform: workers open it to browse All Files, preview and download documents, invite collaborators, comment on files, resolve shared links and run full-text search. Behind those screens the app talks to a token-authenticated content API over OAuth2 Bearer tokens — user identity and storage quota, paginated folder listings, file metadata and binary download, chunked upload, collaborations, recents, events, comments, collections, and a GraphQL route used by hubs and AI assist.

Screenshots

API surface

OAuth2 token issue and refresh
POST /v1/oauth/token opendata
Exchanges an authorization code or refresh_token for the Bearer access_token the rest of the app's content API requires, including PKCE code_verifier and sovereign-cloud base_domain flows.
Auth: OAuth2 authorization-code or refresh_token grant with client_id, client_secret and (for PKCE) code_verifier. Returns a Bearer access_token attached to later API calls.
- access_token
- expires_in
- refresh_token
- token_type
- issued_token_type
- restricted_to
- base_domain
Illustrative example reconstructed from the app's interface — not a live capture.
```
POST /v1/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&client_id=ly1nj6n11uina5nfuewjej5etkdkr7bo&client_secret=******&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```
```
{
  "access_token": "c3FIOG9vZE5ob2VlOW1pZg",
  "expires_in": 3600,
  "restricted_to": [],
  "refresh_token": "XAa1eFv3k3qQYk1z3xY2bQ",
  "token_type": "bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the app's sign-in, silent token-refresh and enterprise sign-in flows.
- Token response fields match what the client caches and attaches to later calls.
Current user identity and storage quota
GET /v1/users/me osint
Returns the signed-in user's profile plus storage quota (space_amount / space_used) and max_upload_size that the account screen and upload preflight use.
Auth: Authorization: Bearer <access_token> from POST /v1/oauth/token.
- type
- id
- name
- login
- space_amount
- space_used
- max_upload_size
- avatar_url
- hostname
- enterprise
- created_at
- modified_at
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/users/me HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
{
  "type": "user",
  "id": "17738362",
  "name": "Jane Doe",
  "login": "[email protected]",
  "created_at": "2021-03-04T09:12:36-08:00",
  "modified_at": "2026-09-12T11:04:02-07:00",
  "space_amount": 10737418240,
  "space_used": 2147483648,
  "max_upload_size": 53687091200,
  "avatar_url": "https://cdn.example.com/avatar/large/17738362",
  "hostname": "https://app.example.com/",
  "enterprise": {"type": "enterprise", "id": "421317", "name": "Acme Corp"}
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the account screen's profile and quota panel.
- max_upload_size matches the preflight check run before large uploads.

List folder items

GET /v1/folders/{folderId}/items opendata

Pages the children of a folder (root is folderId=0) — the All Files browse that drives the main screen, including mixed file and folder entries.

Auth: Authorization: Bearer <access_token>.

entries
total_count
limit
offset
order
next_marker
type
id
name
size
etag
item_status
owned_by

Illustrative example reconstructed from the app's interface — not a live capture.

GET /v1/folders/0/items?limit=100&offset=0&fields=id,type,name,size,modified_at,owned_by HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg

{
  "total_count": 2,
  "limit": 100,
  "offset": 0,
  "order": [{"by": "type", "direction": "ASC"}],
  "entries": [
    {
      "type": "folder",
      "id": "192429928",
      "etag": "1",
      "name": "Contracts",
      "size": 0,
      "item_status": "active",
      "owned_by": {"type": "user", "id": "17738362", "name": "Jane Doe"}
    },
    {
      "type": "file",
      "id": "5000948880",
      "name": "Q3-plan.pdf",
      "size": 629644,
      "sha1": "134b65991ed521fcfe4724b7d1761c4c2c16ffd0"
    }
  ],
  "next_marker": null
}

Derived from the app's interface; endpoint details are illustrative, not a live capture.

Reconstructed from the All Files browse and its pull-to-refresh pagination.
Entry shape covers both file and folder children in one list.

File metadata

GET /v1/files/{fileId} opendata

Loads a single file's metadata for the preview, details and share sheets — size, sha1, version_number, comment_count and the nested shared_link object.

Auth: Authorization: Bearer <access_token>.

type
id
name
size
sha1
etag
created_at
modified_at
owned_by
parent
shared_link
version_number
comment_count
extension
has_collaborations
item_status

Illustrative example reconstructed from the app's interface — not a live capture.

GET /v1/files/5000948880?fields=id,name,size,sha1,version_number,comment_count,shared_link,owned_by,parent,permissions HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg

{
  "type": "file",
  "id": "5000948880",
  "etag": "3",
  "sha1": "134b65991ed521fcfe4724b7d1761c4c2c16ffd0",
  "name": "Q3-plan.pdf",
  "size": 629644,
  "created_at": "2026-04-01T10:18:22-07:00",
  "modified_at": "2026-09-08T16:41:09-07:00",
  "content_created_at": "2026-03-30T09:00:00-07:00",
  "content_modified_at": "2026-03-30T09:00:00-07:00",
  "owned_by": {"type": "user", "id": "17738362", "name": "Jane Doe"},
  "parent": {"type": "folder", "id": "192429928", "name": "Contracts"},
  "shared_link": {
    "url": "https://share.example.com/s/rh935iit6ewrmw0unyul",
    "download_url": "https://cdn.example.com/shared/rh935iit6ewrmw0unyul.pdf",
    "access": "open",
    "is_password_enabled": false,
    "download_count": 12,
    "preview_count": 41
  },
  "item_status": "active",
  "version_number": "3",
  "comment_count": 4,
  "extension": "pdf",
  "has_collaborations": true
}

Derived from the app's interface; endpoint details are illustrative, not a live capture.

Reconstructed from the preview, details and share sheets.
The shared_link block mirrors what the share sheet renders.

Download file content
GET /v1/files/{fileId}/content opendata
Streams the file binary used by the in-app previewer and the save-to-device action; version listings can also carry representations and an authenticated download URL.
Auth: Authorization: Bearer <access_token>. The client follows the redirect to a short-lived download URL.
- Location
- authenticated_download_url
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/files/5000948880/content HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
HTTP/1.1 302 Found
Location: https://downloads.example.com/d/1/a1b2c3.../download

(binary body after follow)
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the in-app previewer and the save-to-device action.
Upload file content
POST /v1/files/content opendata
Creates a new file in a parent folder from the camera, share-sheet or Files picker. Large files are split across a chunked upload-session flow instead.
Auth: Authorization: Bearer <access_token>. Multipart attributes JSON plus file body. Large files switch to a chunked upload-session variant on the same upload service.
- entries
- total_count
- type
- id
- name
- size
- sha1
- parent
Illustrative example reconstructed from the app's interface — not a live capture.
```
POST /v1/files/content HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
Content-Type: multipart/form-data; boundary=----ExampleBoundary

------ExampleBoundary
Content-Disposition: form-data; name="attributes"

{"name":"site-photo.jpg","parent":{"id":"192429928"}}
------ExampleBoundary
Content-Disposition: form-data; name="file"; filename="site-photo.jpg"
Content-Type: image/jpeg

<binary>
------ExampleBoundary--
```
```
{
  "total_count": 1,
  "entries": [
    {
      "type": "file",
      "id": "5000949001",
      "name": "site-photo.jpg",
      "size": 248113,
      "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
      "parent": {"type": "folder", "id": "192429928"}
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the camera, share-sheet and Files-picker upload flows.
- The multipart shape pairs an attributes JSON part with the file body.
Full-text search
GET /v1/search opendata
Runs the in-app search across names, file contents, descriptions, comments and tags, optionally including recent shared links.
Auth: Authorization: Bearer <access_token>.
- query
- content_types
- ancestor_folder_ids
- file_extensions
- created_at_range
- updated_at_range
- include_recent_shared_links
- entries
- total_count
- limit
- offset
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/search?query=contract&limit=25&offset=0&content_types=name,file_content,description&include_recent_shared_links=true HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
{
  "total_count": 1,
  "limit": 25,
  "offset": 0,
  "entries": [
    {
      "type": "file",
      "id": "5000948880",
      "name": "Q3-plan.pdf",
      "description": "Quarterly plan",
      "size": 629644,
      "owned_by": {"type": "user", "id": "17738362", "name": "Jane Doe"}
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the in-app search bar and its scope and date filters.
Resolve shared link
GET /v1/shared-links/resolve opendata
Resolves a shared-link URL (and optional password) into the underlying file or folder so the open-link flow can preview or download it.
Auth: Authorization: Bearer <access_token> plus a shared-link header carrying the link URL and optional password. Anonymous client_credentials tokens can be minted first for public links.
- type
- id
- name
- size
- shared_link
- url
- download_url
- effective_access
- effective_permission
- is_password_enabled
- unshared_at
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/shared-links/resolve HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
X-Shared-Link: https://share.example.com/s/rh935iit6ewrmw0unyul
```
```
{
  "type": "file",
  "id": "5000948880",
  "name": "Q3-plan.pdf",
  "size": 629644,
  "shared_link": {
    "url": "https://share.example.com/s/rh935iit6ewrmw0unyul",
    "download_url": "https://cdn.example.com/shared/rh935iit6ewrmw0unyul.pdf",
    "effective_access": "open",
    "effective_permission": "can_download",
    "is_password_enabled": false,
    "unshared_at": null
  }
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the open-shared-link flow, including password-protected links.
Folder collaborations
GET /v1/folders/{folderId}/collaborators opendata
Lists who can access a folder (a file variant exists as well) — the collaborators screen. New invites are created with item, accessible_by and role.
Auth: Authorization: Bearer <access_token>. New invites POST to /v1/collaborators.
- type
- id
- status
- role
- accessible_by
- invite_email
- item
- created_at
- modified_at
- expires_at
- acknowledged_at
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/folders/192429928/collaborators HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
{
  "total_count": 2,
  "entries": [
    {
      "type": "collaboration",
      "id": "791293",
      "created_at": "2025-11-02T14:21:09-08:00",
      "modified_at": "2025-11-02T14:21:09-08:00",
      "expires_at": null,
      "status": "accepted",
      "role": "editor",
      "accessible_by": {"type": "user", "id": "482921", "login": "[email protected]", "name": "Alex Partner"},
      "invite_email": null,
      "item": {"type": "folder", "id": "192429928", "name": "Contracts"}
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the collaborators screen and the invite sheet.
Recent items
GET /v1/recents opendata
Feeds the Recents tab with the files and folders the user most recently previewed, downloaded or opened via a shared link.
Auth: Authorization: Bearer <access_token>.
- type
- interacted_at
- interaction_type
- interaction_shared_link
- item
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/recents?limit=50 HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
{
  "entries": [
    {
      "type": "recent_item",
      "interacted_at": "2026-09-27T18:04:11-07:00",
      "interaction_type": "item_preview",
      "interaction_shared_link": null,
      "item": {
        "type": "file",
        "id": "5000948880",
        "name": "Q3-plan.pdf",
        "size": 629644
      }
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the Recents tab and its per-item interaction labels.

User events stream

GET /v1/events opendata

Polls (and long-polls) the user's event stream so the client can refresh listings after upload, preview and collaboration activity from other sessions.

Auth: Authorization: Bearer <access_token>.

chunk_size
next_stream_position
entries
event_id
event_type
created_at
recorded_at
session_id
created_by
source

Illustrative example reconstructed from the app's interface — not a live capture.

GET /v1/events?stream_type=all&stream_position=now HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg

{
  "chunk_size": 1,
  "next_stream_position": "1152922976252290886",
  "entries": [
    {
      "type": "event",
      "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
      "created_at": "2026-09-27T18:04:11-07:00",
      "recorded_at": "2026-09-27T18:04:12-07:00",
      "event_type": "ITEM_PREVIEW",
      "session_id": "70090280850c4564be4a4a4a4a4a4a4a",
      "created_by": {"type": "user", "id": "17738362", "name": "Jane Doe", "login": "[email protected]"},
      "source": {"type": "file", "id": "5000948880", "name": "Q3-plan.pdf"}
    }
  ]
}

Derived from the app's interface; endpoint details are illustrative, not a live capture.

Reconstructed from the listing auto-refresh that follows activity in other sessions.

File comments

GET /v1/files/{fileId}/comments opendata

Loads the comment thread on a file, including threaded replies. New comments are posted with the file as their item.

Auth: Authorization: Bearer <access_token>. New comments POST to /v1/comments.

type
id
is_reply_comment
message
tagged_message
created_by
created_at
modified_at
item

Illustrative example reconstructed from the app's interface — not a live capture.

GET /v1/files/5000948880/comments HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg

{
  "total_count": 1,
  "entries": [
    {
      "type": "comment",
      "id": "191969",
      "is_reply_comment": false,
      "message": "Please confirm the Q3 numbers.",
      "tagged_message": "Please confirm the Q3 numbers.",
      "created_by": {"type": "user", "id": "482921", "name": "Alex Partner", "login": "[email protected]"},
      "created_at": "2026-09-20T09:11:43-07:00",
      "modified_at": "2026-09-20T09:11:43-07:00",
      "item": {"type": "file", "id": "5000948880"}
    }
  ]
}

Derived from the app's interface; endpoint details are illustrative, not a live capture.

Reconstructed from the file comment thread and reply composer.

Collections (Favorites)
GET /v1/collections opendata
Lists the user's collections (typically Favorites). Items inside a collection are read from /v1/collections/{collectionId}/items.
Auth: Authorization: Bearer <access_token>.
- type
- id
- name
- collection_type
- entries
- total_count
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/collections HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
{
  "total_count": 1,
  "entries": [
    {
      "type": "collection",
      "id": "926489",
      "name": "Favorites",
      "collection_type": "favorites"
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the Favorites screen and its item list.
App GraphQL (Hubs and search)
POST /v1/hubs/graphql opendata
Serves hubs, hub items and the in-app full-search GraphQL operations that the REST surface does not cover.
Auth: Authorization: Bearer <access_token>. A single GraphQL endpoint fronts several named operations.
- data
- hubs
- edges
- node
- id
- title
Illustrative example reconstructed from the app's interface — not a live capture.
```
POST /v1/hubs/graphql HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
Content-Type: application/json

{"operationName":"GetHubs","variables":{"first":20},"query":"query GetHubs($first:Int){ hubs(first:$first){ edges { node { id title } } } }"}
```
```
{
  "data": {
    "hubs": {
      "edges": [
        {"node": {"id": "hub_01HZX4K2", "title": "Legal playbooks"}}
      ]
    }
  }
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the hubs browse and AI-assist screens.
- Several named operations share one GraphQL route.
Signed-in user feature flags
GET /v1/users/me/features opendata
Returns the signed-in user's enabled feature flags (user_feature_list) that gate share-link passwords, AI assist and hubs in the client.
Auth: Authorization: Bearer <access_token>.
- user_feature_list
- password_protected_shared_links
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/users/me/features HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
{
  "user_feature_list": [
    "password_protected_shared_links",
    "box_ai",
    "hubs"
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the client-side feature gating applied after sign-in.
Trashed folder items
GET /v1/trash/items opendata
Pages the Trash screen: files and folders the user deleted. A single trashed item is readable on a per-item trash variant of the file and folder routes.
Auth: Authorization: Bearer <access_token>.
- entries
- total_count
- limit
- offset
- type
- id
- name
- item_status
- trashed_at
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/trash/items?limit=100&offset=0 HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
{
  "total_count": 1,
  "limit": 100,
  "offset": 0,
  "entries": [
    {
      "type": "file",
      "id": "5000948880",
      "name": "Q3-plan.pdf",
      "item_status": "trashed",
      "trashed_at": "2026-09-20T09:11:43-07:00"
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the Trash screen and its restore actions.
File metadata instances
GET /v1/files/{fileId}/metadata opendata
Lists metadata template instances attached to a file (enterprise classification, custom fields). A single template is read or written on a scoped variant of the same route.
Auth: Authorization: Bearer <access_token>.
- entries
- $type
- $parent
- $template
- $scope
- $version
Illustrative example reconstructed from the app's interface — not a live capture.
```
GET /v1/files/5000948880/metadata HTTP/1.1
Authorization: Bearer c3FIOG9vZE5ob2VlOW1pZg
```
```
{
  "entries": [
    {
      "$type": "contractTemplate-3d5d72bb",
      "$parent": "file_5000948880",
      "$template": "contractTemplate",
      "$scope": "enterprise_421317",
      "$version": 1,
      "contractType": "MSA",
      "renewalDate": "2027-04-01T00:00:00.000Z"
    }
  ]
}
```
Derived from the app's interface; endpoint details are illustrative, not a live capture.
- Reconstructed from the file details metadata panel.

Where teams use this data

Enterprise file-inventory sync
A records system signs in as the worker, reads space_used / space_amount from GET /v1/users/me, then walks GET /v1/folders/{folderId}/items to snapshot id, name, size, sha1 and owned_by for every file under All Files.
Shared-link intake
A ticketing bot takes a shared-link URL, calls GET /v1/shared-links/resolve with the link carried in a header, and stores the resolved file id, effective_access and download_url without asking the sender to re-upload.
Collaboration audit
Security ops pages GET /v1/folders/{folderId}/collaborators for sensitive folders and diffs accessible_by.login, role and status against an allow-list, then watches GET /v1/events for collaborator-added activity.
Recent-work dashboard
A desktop companion mirrors the Recents tab via GET /v1/recents (interacted_at, interaction_type, item) and overlays full-text hits from GET /v1/search so a worker can jump back into the last previewed contract.

Frequently asked questions

What does the Box Android app load after sign-in?

GET /v1/users/me returns the signed-in identity (id, name, login) plus storage quota (space_amount, space_used, max_upload_size). The All Files screen then pages GET /v1/folders/{folderId}/items, with folderId=0 for the root.

How does Box sharing work on this API?

A shared-link URL is resolved by GET /v1/shared-links/resolve using a shared-link header (and optional password). Collaborators on a folder come from GET /v1/folders/{folderId}/collaborators with role, status and accessible_by; new invites POST to /v1/collaborators.

Can I search and list recents?

Yes. GET /v1/search takes query plus content_types, ancestor_folder_ids and include_recent_shared_links. GET /v1/recents returns interacted_at, interaction_type and the nested item the Recents tab shows.

How is the app authenticated?

OAuth2. POST /v1/oauth/token exchanges an authorization code or refresh_token (with PKCE code_verifier) for access_token, expires_in and refresh_token. Every later content API call sends Authorization: Bearer <access_token>.

More Business apps

Topics

box api
box content api
box files
box folders
box collaborations
box shared links
box search
box events
space_used
oauth2 token

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

Box Content API: files, folders, sharing and search

Screenshots

API surface

OAuth2 token issue and refresh

Current user identity and storage quota

List folder items

File metadata

Download file content

Upload file content

Full-text search

Resolve shared link

Folder collaborations

Recent items

User events stream

File comments

Collections (Favorites)

App GraphQL (Hubs and search)

Signed-in user feature flags

Trashed folder items

File metadata instances

Data categories

Where teams use this data

Enterprise file-inventory sync

Shared-link intake

Collaboration audit

Recent-work dashboard

Frequently asked questions

More Business apps

ADP Mobile Solutions

Google Ads

Meta Ads Manager

Meta Business Suite

Topics

Need this app's data API integrated?