API and MCP
The REST API v2 (YetiShare-compatible) with keys and tokens, chunked uploads, every call, the MCP server for AI assistants with agent tokens, and where the docs page is.
BoxPuff has two doors for programs. The REST API v2 at /api/v2/... follows the YetiShare API, so apps and scripts written for a YetiShare site work with a change of address. The MCP server at /mcp lets a member connect an AI assistant (Claude, ChatGPT and others that speak the Model Context Protocol) to their own files with a personal token. Both honour the member's package.
Where the documentation is
Every call is written down once, in includes/api-docs.php, and three pages read it: the public /api page (linked in the footer when Show front-end API documentation is on), Admin → Infrastructure → API Documentation, and the API Testing Tool next to it, which fills a form for any call and shows the raw answer. The member's keys are under Settings → API Access; the admin's switches under Site Settings → API and MCP.
Opening the API folder itself - https://your-site/api/ - now shows the documentation page, as /api does. A web server serves an existing folder before any rewrite rule, which used to leave that address blank; the shipped .htaccess has the rule RewriteRule ^api/?$ index.php [L,QSA] for it, and the folder's own index.php hands over to the site's front controller when it is opened straight (so it also works on a server that ignores .htaccess). A person whose browser sends Accept: text/html to the API's base address (/api/v2/) is sent to the same page; a program gets the short JSON BoxPuff API v2. See the documentation. with the docs address.
/api/?section=mcp - the address behind the How it works link beside Connected agents in the member's settings - opens the documentation page too; the MCP section is further down it, and /api#mcp jumps straight there. A browser sent to the API's base address with ?section=mcp (/api/v2/?section=mcp) is redirected to /api#mcp.
If you updated an older site by hand, make sure the new .htaccess came with the files.
Authentication
Site Settings → API → Authentication method chooses between API Keys (default) and Account access details.
POST /api/v2/authorize
key1=<API key 1>&key2=<API key 2> (or username & password)
The answer carries access_token (64 characters, lives an hour and is refreshed by every call) and account_id; every other call sends both, as form fields, in a JSON body, or the token as Authorization: Bearer .... /disable_access_token ends it. Access level limits the API to chosen packages, and the package field API Access can switch it off for a type; Rate limit per minute (120 per account, twice that per address; 30 for /authorize) answers 429 when exceeded. Always call over HTTPS.
Answers look like {"_status":"success","_datetime":"...","data":{...}} or {"_status":"error","_datetime":"...","response":"why"} with codes 400, 401, 403, 404, 405, 429 and 500.
The calls
| Section | Calls |
|---|---|
| Authentication | /authorize, /disable_access_token |
| User Accounts | /account/info, /account/package, /account/register and /account/forgot_password (only with Enable API registration), /account/purge_trash; admin only: /account/create, /account/edit, /account/delete |
| Files | /file/upload, /file/download (a link good for six hours, not bound to an address, so apps download from anywhere), /file/url_upload_add, /file/url_upload_status, /file/info, /file/edit, /file/delete (to the trash), /file/move, /file/copy, /file/bulk_trash, /file/bulk_restore, /file/bulk_delete, /file/bulk_move |
| Folders | /folder/create, /folder/listing (folder, trash, recent, all, shared or search; sorting and type filters; paging), /folder/info, /folder/edit, /folder/delete, /folder/move |
| Sharing | /share/create_public_url, /share/public_url_listing, /share/delete, /share/internal_listing, /share/create_internal, /share/send_email |
| Packages | /package/listing (admin) |
| Teams | /api/app/teams/list, /api/app/teams/switch, /api/app/teams/create, /api/app/teams/members; listing calls take an optional team_id |
Chunked uploads. /file/upload takes one file as multipart/form-data. For a big file send it in pieces: each request carries a Content-Range: bytes start-end/total header and the same c_tracker value; the last piece stores the file and the answer has upload_complete: true and a data[] row with the YetiShare field names (url, short_url, file_id, delete_hash, url_html, url_bbcode and so on). Every upload goes through the same package rules as the browser (Uploads).
Plugins add calls through the bp_api_calls hook; the Voucher Reseller plugin has its own JSON endpoint, and the Browser Extension signs in through /authorize.
The MCP server
Site Settings → MCP → Enable MCP server (on by default) opens /mcp, a JSON-RPC 2.0 endpoint speaking the Model Context Protocol: initialize, ping, tools/list, tools/call, resources/list, batches. The member makes a token under Settings → Connected agents: a label, a lifetime in days (the default is MCP token expiry (days), 30; 0 = never), then Create. The token (bpa_...) is shown once, together with a ready-made configuration:
{
"mcpServers": {
"boxpuff": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer bpa_..." } }
}
}
Paste it into the assistant's MCP settings and it can work with the files. Revoke ends a token at once; the cron purges expired ones.
The tools: account_info, list_files, search_files (by name, keyword, type or extension), get_file, upload_file (a small file as base64, at most MCP inline upload max (MB)), download_link (good for six hours), create_folder, rename, move, trash (and restore), share_link (with password and expiry), list_shares, revoke_share. Each is limited to the token's own account and its package; MCP rate limit per minute throttles. Plugins add tools through bp_mcp_tools and bp_mcp_call.
Members' keys
Settings → API Access shows API key 1 and API key 2 (60 characters each) with Regenerate - anything using the old keys stops at once. The admin does not see members' keys; a member who lost theirs regenerates.
Tips
- Give the API only to packages that need it: untick API Access on the trial package.
- A download manager or desktop sync tool for members is one
/authorizeand one/folder/listingaway; the WebDAV plugin is the no-code alternative. - Keep Enable API registration off unless an app of yours registers accounts; it opens a registration path without the captcha.
- The Testing Tool uses your own admin keys; try
/account/infofirst to see the shape of an answer.