How to Configure API Mode in XFile Ultra
This guide explains the API section in admin settings — in everyday language. You will learn how to turn the member API on or off, what each rate limit means (especially Read and Write), and how bulk delete works.
---
Where to find it
Admin → Settings → Mods → API
The section title is API. Description: public API surface and rate limits.
Members use the API from Manage Account → API, where they create a secret key and call /api/v1 with:
Authorization: Bearer THEIR_API_KEYPublic reference for developers: your site’s /api docs page.
---
API mod (the “API mode” switch)
In the product this is labeled API mod. Think of it as the master on/off for the member API.
| When it is… | What happens |
|---|---|
| On (default) | Members can open Manage Account → API, create a key, and call the member API |
| Off | The API tab disappears from Manage Account, and every member /api/v1 call returns 403 (blocked) |
Turn it off if you do not want any member automation or third-party tools talking to your site.
Turn it on when you want uploaders, scripts, or apps to manage files through the API.
Note: even with API mod on, a user’s plan / Users limits can still block API access for that tier. Site maintenance and normal upload rules still apply.
---
Member API rates (the five hourly limits)
Under Member API rates you set how many requests each member may make per hour, counted per account + IP.
These numbers are speed limits, not permission checkboxes. A higher number means more traffic allowed in that bucket before the API answers “too many requests — try later.”
Typical defaults (your install may show the same):
| Rate label | Default (per hour) | In plain words |
|---|---|---|
| Upload | 30 | Starting or finishing file uploads through the API |
| Remote URL | 20 | “Import this file from a URL” requests |
| Copy from public | 20 | “Copy this public file into my account” requests |
| Read | 300 | Looking things up without changing them |
| Write | 120 | Changing, moving, deleting, or organizing files |
You can raise limits for busy sites or lower them to reduce abuse. Empty or invalid values fall back to the product defaults.
Upload
Counts API uploads — the classic “send a file to my account” flow (including chunked upload start/finish).
If someone uploads many large files by API every hour, this is the dial you turn.
Remote URL
Counts “download this URL and store it as my upload” requests.
This only works when Remote URL upload is also enabled under Mods → Upload sources, and the member’s plan is not blocked from remote URL in Users limits.
Copy from public
Counts “copy an existing public file into my account” requests.
Same idea: needs Copy from public enabled under Mods → Upload sources, and the plan must allow it.
Read — what counts as Read?
Read is for safe, look-up actions. The member is asking “what do I have?” or “give me a download link,” not “change my library.”
Examples of Read:
- List my files
- List trash
- Get details for one file
- Ask for a download link
- Check my storage usage
If a tool only browses the library and fetches links, it mostly burns the Read budget.
Write — what counts as Write?
Write is for actions that change the account’s files or folders.
Examples of Write:
- Delete a file
- Rename or update file details
- Create a folder
- Move files (including bulk move)
- Restore something from trash
- Bulk delete (only if you turn that feature on — see below)
If a tool reorganizes or cleans up a library, it mostly burns the Write budget.
Quick mental model
| Goal | Bucket |
|---|---|
| Send a new file | Upload |
| Pull a file from the internet | Remote URL |
| Duplicate a public file into my account | Copy from public |
| Look up / list / get a link | Read |
| Delete / move / rename / folders / restore | Write |
---
API bulk delete
Two related controls:
| Setting | Meaning |
|---|---|
| API bulk delete | Off by default. When on, keys may call the bulk-delete endpoint to trash many files/folders in one request |
| Bulk delete batch size | How many IDs are allowed in one bulk-delete call (typical default 100, hard max 500) |
Important:
- Bulk delete is optional and powerful — leave it off unless you need scripts to mass-clean libraries
- Turning bulk delete off does not block deleting one file at a time through the API
- Folder IDs in a bulk delete can trash the folder and what is inside it
---
How a member gets started (so you can support them)
1. Confirm API mod is on
2. Member opens Manage Account → API
3. They Generate or Rotate an API key (shown once — they must save it)
4. They call your site with Authorization: Bearer … against /api/v1
5. If something returns 403, check: API mod, plan “API enabled”, Upload sources for remote/copy, and rate limits (429)
Member keys normally include upload + read + write abilities together. Members do not pick scopes in the UI.
---
Suggested setup for most sites
1. Leave API mod on if you want integrations; otherwise turn it off
2. Keep Read fairly high (browsing is chatty)
3. Keep Upload / Remote URL / Copy moderate so one account cannot flood the server
4. Keep Write lower than Read unless automation must reorganize often
5. Leave API bulk delete off until you have a real need, then set a careful batch size
6. Confirm Remote URL upload and Copy from public under Upload sources match what you want the API to allow
---
Common problems
“The member API is disabled”
API mod is off, or the member’s tier blocks API access.
Remote URL / copy always 403
API mod is on, but Upload sources (or Users limits) still blocks remote URL or copy for that plan.
429 Too many requests
They hit one of the five hourly buckets (account + IP). Raise that specific rate, or ask them to slow down.
Bulk delete 403 but single delete works
API bulk delete is off — that is expected.
API tab missing in Manage Account
API mod is off.
---