API ও MCP
কী ও টোকেনসহ REST API v2 (YetiShare-সঙ্গত), টুকরো করে আপলোড, প্রতিটি কল, এজেন্ট টোকেনসহ AI সহকারীর জন্য MCP সার্ভার, আর ডকুমেন্টেশন পেজ কোথায়।
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.