The open creative studio on ComfyUI: images, video, 3D and audio on open weights, on your own GPU or the cloud. Camera motions, effects, apps, Cinema, Layers, Image to 3D and an AI agent.
Manage your Fuobe from your own tools
An install can be managed from your own tools with an admin API token: a script, a dashboard or a small admin app of your own can list accounts, switch them off, read and delete their runs, take results down, read reports and run the workers, without signing in as the owner.
An admin token:
- works only on
/api/admin/*. Anywhere else (pages, Settings, sign-in, the studio's API,/api/mcp) it gets403 "An admin token only works on the admin API."; - does only what you ticked when you made it (its scopes);
- is never the owner: it can't sign in, change settings or keys, or make or revoke tokens;
- stands on its own: a session cookie sent with it is ignored;
- is stored only as its SHA-256. You see the token once, when you make it.
Every change made through the admin API is written to the admin log, and so is every file a token opens and its reads of people's data. The log never holds a token, a password, a prompt or an IP address.
Make a token
- Open Settings → Security in the owner's signed-in browser.
- Under Admin tokens, press New admin token.
- Name it, tick what it may do (Read only and Full admin tick sets for you), pick an expiry and press Create admin token.
- Copy the token (
fuobe_adm_…, 53 characters). It isn't shown again.
The list shows each token's first characters, its scopes, when it was made and last used, and when it expires. Revoke stops it at once. Sign everyone out with Also revoke every API token revokes admin tokens too. An install keeps at most 20 live admin tokens.
Keep the token out of URLs, logs and shared files. Send it only in the Authorization header, and only over HTTPS.
Scopes
| Scope | Lets the token |
|---|---|
accounts:read |
GET /api/admin/accounts (JSON or CSV), GET /api/admin/accounts/{id} |
accounts:write |
PATCH /api/admin/accounts/{id} with { "disabled": true | false } or { "signOut": true } (its paired ComfyUIs stop too) |
accounts:delete |
DELETE /api/admin/accounts/{id}: its runs, files and record go. It can't be undone |
runs:read |
GET /api/admin/generations: runs, each one's facts only (when, which model and app, how it ended, how many results). Accounts' and guests' runs by default; the owner's own with whose=ours or whose=everyone. With outputs:view, GET /api/admin/generations/{id} too |
runs:write |
POST /api/admin/generations/{id}/rerun: a new run in an account, made from its run that failed or was cancelled |
runs:delete |
DELETE /api/admin/generations/{id}: a run still going is canceled first |
outputs:view |
GET /api/admin/files/{path}: a stored file, an account's or the owner's own, held ones too. Each view is logged. With runs:read, the runs' prompts, inputs and results too, and one run in full |
outputs:hide |
POST /api/admin/outputs/hide |
outputs:moderate |
POST /api/admin/outputs/hide, /unhide and /remove |
reports:read |
GET /api/admin/reports (reporters' emails only with accounts:read) |
workers:read |
GET /api/admin/workers, GET /api/admin/workers/jobs, GET /api/admin/workers/events |
workers:write |
PATCH /api/admin/workers/{id}: pause, resume, drain, hours, lanes, pick order, revoke; and POST /api/admin/workers/{id}/update |
workers:update |
POST /api/admin/workers/{id}/update only: ask a worker to update its program now |
workers:tokens |
POST /api/admin/workers, and PATCH /api/admin/workers/{id} with rotate: both answer with a worker token. A worker receives accounts' queued jobs with their input files and sends back the results, so give this scope only to a tool you'd trust with those |
queue:read |
GET /api/admin/queue, GET /api/admin/queue/settings, GET /api/admin/queue/overrides |
queue:write |
PATCH /api/admin/queue/settings: the run ceiling, the owner's wait limit, fair share, the pick allowance and the paused budget (pausedBudgetS: how long a run that has started may spend back in line) |
queue:control |
POST /api/admin/queue/mode, POST /api/admin/queue/overrides, DELETE /api/admin/queue/overrides/{id}, POST /api/admin/queue/cancel: who the GPUs serve first, runs and people sent first or held, and cancelling a run (gpu-workers.md) |
site:read |
GET /api/admin/site/uploads, GET /api/admin/site/runs |
site:write |
PATCH /api/admin/site/uploads: the upload switches; PATCH /api/admin/site/runs: what people read when a run fails |
audit:read |
GET /api/admin/audit |
The read-only preset in Settings ticks runs:read, reports:read, workers:read, queue:read and audit:read:
no emails, no prompts and no results. With runs:read, an account's email in a run needs accounts:read. Without it a
run's account is { id, emailHidden: true }; email: null always means the account was deleted.
Any valid admin token may call GET /api/admin/tokens/self, which says the token's name and scopes, so a tool can
offer only what it may do. /api/admin/tokens itself (make, list, revoke) is the owner's signed-in browser's only.
Examples
export FUOBE=https://fuobe.example.com
export TOKEN=fuobe_adm_... # from Settings → Security → Admin tokens
# Which token is this, and what may it do?
curl -s "$FUOBE/api/admin/tokens/self" -H "Authorization: Bearer $TOKEN"
# Accounts, with their runs and space; one by email; every email containing "studio"
curl -s "$FUOBE/api/admin/accounts" -H "Authorization: Bearer $TOKEN"
curl -s "$FUOBE/api/admin/[email protected]" -H "Authorization: Bearer $TOKEN"
curl -s "$FUOBE/api/admin/accounts?q=studio" -H "Authorization: Bearer $TOKEN"
# Switch an account off, sign it out everywhere, delete it
curl -s -X PATCH "$FUOBE/api/admin/accounts/ACCOUNT_ID" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"disabled": true}'
curl -s -X PATCH "$FUOBE/api/admin/accounts/ACCOUNT_ID" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"signOut": true}'
curl -s -X DELETE "$FUOBE/api/admin/accounts/ACCOUNT_ID" -H "Authorization: Bearer $TOKEN"
# Accounts' failed video runs, 50 a page; then the next page
curl -s "$FUOBE/api/admin/generations?status=failed&kind=video&limit=50" -H "Authorization: Bearer $TOKEN"
curl -s "$FUOBE/api/admin/generations?status=failed&kind=video&limit=50&before=NEXT" -H "Authorization: Bearer $TOKEN"
# Open a result's file (an output's url is /api/files/<path>: ask /api/admin/files/<path>)
curl -s -o result.png "$FUOBE/api/admin/files/PATH" -H "Authorization: Bearer $TOKEN"
# Hide a run's results
curl -s -X POST "$FUOBE/api/admin/outputs/hide" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"generationIds": ["RUN_ID"]}'
# The admin log, newest first
curl -s "$FUOBE/api/admin/audit?limit=50" -H "Authorization: Bearer $TOKEN"
Calls
Times are epoch milliseconds and sizes are bytes. Every answer is Cache-Control: no-store.
| Call | Request | Answer |
|---|---|---|
GET /api/admin/accounts |
q (the email contains it, up to 100 characters), email (exactly that address), format=csv |
{ total, items, totals, signInNotices }; with q or email, also matched. total and totals always cover every account. signInNotices lists each auth.json that was found in the data folder after the sign-in data moved into the database. Each one was set aside without being read (Sign-in data). An entry gives { file, foundAt, reason, counts }. reason is stray, unreadable, link (a symbolic link, never followed) or import-failed. counts is { accounts, tokens, accountsNotInDatabase }, or null when the file isn't sign-in data or is a link. An entry stays in the list until you delete its file. CSV: a text/csv download |
GET /api/admin/accounts/{id} |
one account with its numbers; 404 No such account |
|
PATCH /api/admin/accounts/{id} |
exactly one of { disabled: boolean }, { signOut: true }, { password: string } or { email: string } |
the account (no numbers). password: a new password of at least 8 characters (400 otherwise), hashed as at sign-up. email: a new sign-in email, lower-cased as at sign-up (400 for one that isn't an email address, 409 when another account uses it). Either one ends every sign-in of the account, so it logs in again; its paired ComfyUIs stay paired. The log row names the account only, never the password or the email |
DELETE /api/admin/accounts/{id} |
204 | |
GET /api/admin/generations |
account (one account), else whose (people: accounts' and guests' runs, the default; ours: the owner's own; everyone); source (the owner's runs only: hands-on, or batch for any automated run: batch, drill, example, test, api); where (pool: this install's GPUs, the owner's runs on its ComfyUI too; provider: a cloud provider; own: an account's own GPU); status (finished or done, failed, canceled, waiting, started, and running for waiting and started); kind (image, video, audio, model3d, text); model (letters of the model id); from and to (yyyy-mm-dd in UTC, both days included); q (words of the prompt, or a run id); ids (a comma list of up to 100 run ids: those runs, whoever's they are); before (the last page's next); limit (1 to 100, default 30) |
{ items, next }; next is null on the last page. Each run has whose: account, guest or owner. Each output has a state: shown, held (hidden, or waiting for its check) or removed (its file is gone). A failed run on this install's GPUs (and the owner's own failed run) also has detail: the technical reason, which the account never sees. account is { id, email } (email null: a deleted account), { id, emailHidden: true } without accounts:read, or null for the owner's own run, which has source too (hands-on from the site; batch, drill, example, test as its script said; api for a run sent with an API token that said none) and sourceName when its script gave one. A run that is one step of a longer run (its steps wait for one another) has step: { n, of } |
GET /api/admin/generations/{id} |
needs runs:read and outputs:view |
One run in full, an account's, a guest's or the owner's own: { run, stored, fix, trouble, where, model, preset, studio, prompt, negativePrompt, asked, settings, inputs, batch, near, chain, sent, timing, jobs, workerLog, money, madeBy, surface, providerId, progress, checks }. stored.detail is the technical reason for the owner; comfyReason, when there is one, is ComfyUI's own reason in one short line (a node that isn't installed, a model file not in its list, an error in a node), and each of jobs has it as comfyWhy. A job on one of this site's workers may have nodes: its slowest nodes, slowest first, each { node, type, ms, beforeStepsMs, steps } (beforeStepsMs and steps for a node with steps; gpu-workers.md). inputs lists each input file by slot, with its state (kept with its url, removed, example, inline, link). chain is { before, after }: the steps it waits for and the steps that wait for it. rerunOf and rerunAs (also on each run of the list): the run it is a re-run of, and the run it was re-run as. Keys, tokens and GPU addresses are never part of it. 404 for an unknown run |
DELETE /api/admin/generations/{id} |
204; 404 for an unknown run or the owner's own | |
POST /api/admin/generations/{id}/rerun |
{ reason? }: a sentence for the admin log (up to 300 characters) |
201 { run, account, ids, held? }: a new run in the same account with the same request (feature, model, words, settings and files), sent through the account's own Run: the same checks, limits and services, queued and priced the same way, on the place the run went before when it can go there. The account sees it as any run of its own. held: why it waits to enter the line. 404 for an unknown run, the owner's own or a deleted account; 409 for a run that didn't fail and wasn't cancelled, one in the Trash, a step of a longer run, an account switched off, a run re-run already (with rerunAs), or input files that are gone (code: "input-gone"); any other refusal (a limit, a service) is the Run's own answer, with its status and code |
POST /api/admin/outputs/hide |
{ assetIds?, generationIds? } (up to 500 each) |
{ hidden } |
POST /api/admin/outputs/unhide |
the same | { shown } |
POST /api/admin/outputs/remove |
the same, and evidence?: true to keep the files in a locked folder |
{ removed } |
GET /api/admin/files/{path} |
Range works |
the file, an account's or the owner's own (held ones too); 404 for unknown paths |
GET /api/admin/reports |
limit (1 to 500, default 100) |
{ items }, newest first |
GET /api/admin/queue |
{ held, lanes, running, holding, queued, next, nextTotal, text, controls, now }. queued is in the order the workers serve it, each with rank (null while no worker takes it), why, code (class, next, boost, held, pinned, paused), override and person (a key, never an account id). A holding row for a worker that holds back the line (task null) names the job it would take first (generationId, model, op, principal). A run of the owner's that the owner made by hand (no source) has handsOn: true in queued, running and holding: it waits with people's runs, and its why says "Your run". controls: { pools, workers, overrides, ended, modes } (a run override has generationId, the run pressed, and generations, every step of that Run it covers) (gpu-workers.md) |
|
POST /api/admin/queue/mode |
{ pool?, worker?, mode, forMin? }: mode is people-first, people-only, ours-first, balanced, or null (back to normal); forMin is 1 to 10080, or null (until switched back) |
{ mode, before }; 400 for a value out of bounds, 404 for no such worker |
GET /api/admin/queue/overrides |
{ live, ended } (the last 20 that ended) |
|
POST /api/admin/queue/overrides |
`{ kind: "run", generationId, action: "next" | "hold", worker?, forMin? }or{ kind: "person", person |
DELETE /api/admin/queue/overrides/{id} |
{ override } (ended now); 404 when it isn't in effect |
|
POST /api/admin/queue/cancel |
{ generationId } |
{ generationId, status }: the run ends as the person's own Cancel ends it; 404 for no such run, 409 for one that ended |
GET /api/admin/queue/settings |
{ settings: { runCeilingS: { default, lanes }, ownerWaitLimitS, fairShare, pickAllowanceMs, firstPickGraceMs, pausedBudgetS } } (gpu-workers.md) |
|
PATCH /api/admin/queue/settings |
any of runCeilingS: { default, lanes? } (seconds, 60 to 86400; a given runCeilingS replaces the default and every lane's value), ownerWaitLimitS (seconds, 60 to 604800, or null for no limit), fairShare (boolean), pickAllowanceMs (0 to 3600000), firstPickGraceMs (0 to 600000; gpu-workers.md), pausedBudgetS (seconds, 0 to 604800) |
{ settings }; 400 with the reason for a value out of bounds, an unknown setting or an unknown lane |
GET /api/admin/site/uploads |
{ switches: { soundConvert, soundTrim, videoTrim, photoConvert, photoCrop } }: what a browser may do to a file that doesn't fit a tool before it is uploaded (convert a sound to MP3, offer a part of a sound or clip, convert or shrink a photo, offer a crop). All true by default. Every visitor reads the same values at GET /api/site/uploads |
|
PATCH /api/admin/site/uploads |
any of the five, each true or false |
{ switches }; 400 with the reason for an unknown switch or a value that isn't a boolean. A switch that is off leaves that kind of file as it is: the tool says why it can't take it, and the server's checks apply. Browsers pick it up when they next load a page |
GET /api/admin/site/runs |
{ failureDetail }: what a person reads when a run of theirs on this install's GPUs fails. full: the plain sentence and, under it, the cleaned technical reason (ComfyUI's own: no folders, addresses, keys or prompt text); friendly: the plain sentence only. Settings → Failed runs is the same choice. A new install starts with full; an install that had runs or settings before this choice existed keeps friendly |
|
PATCH /api/admin/site/runs |
{ "failureDetail": "full" | "friendly" } |
{ failureDetail }; 400 for any other body. Runs read it the next time they are shown. A person only ever sees the details of their own runs |
GET /api/admin/workers |
{ workers, lanes }. Each worker adds ramGuard (its RAM guard switch, false by default, gpu-workers.md), pickOrder, noStream (the workflows it takes only with every weight on its card, newest first: [{ workflowId, at }], gpu-workers.md), asked: { at, words } or null, jobs (each job it holds: { taskId, generationId, slot, lane, laneLabel, stage, state, claimedAt, startedAt, progress, progressAt, movedAt, gpuBusy, stallMs, doing, typicalMs, etaS, owners, feature?, modelName?, op?, kind? }: doing is what its ComfyUI runs now ({ node, nodeClass, nodeTitle, value?, max?, pass? }, or null), for the owner only; movedAt is when the worker last saw the job move, on the site clock, or null from an older worker; gpuBusy is its GPU use from 0 to 100, or null; past stallMs without a move the worker gives the job back; etaS is more than 0 or null, never 0 for a running job) and lastEvent: { at, kind, event, words } or null |
|
POST /api/admin/workers |
{ name, pool? } |
201 { id, token }: the worker's token, once |
POST /api/admin/workers/{id}/update |
none | { worker }: its next beat answer asks it to update now. It looks for new code at once and restarts on it after the job in hand (a person's job is never cut off). Each worker in GET /api/admin/workers has update: state (current, updating while behind the site's version for under 3 minutes, behind after), since, behindMs, site, worker, commit (first 12 hex), peopleHeld, peopleWaiting, askedAt, words and needsOwner |
PATCH /api/admin/workers/{id} |
any of paused, pauseNow, drain, autoResume, ramGuard (true or false: the worker's RAM guard, which its next beat answer carries; its numbers stay in its worker.json, gpu-workers.md), hours, allow, claimAfterMs, switchAfterMs, pickOrder (a whole number from -100 to 100, 0 by default: a free worker with a higher one gets first pick, gpu-workers.md), clearNoStream (true for its whole noStream list, or a list of workflow ids: it may stream them from RAM again), rotate (needs workers:tokens), revoke |
{ worker, token? }: a new worker token after rotate, once. 400 with the reason for a value that isn't allowed |
GET /api/admin/workers/jobs |
before, limit (1 to 200, 50), worker, generation |
{ items, next }: the workers' log, newest first. Each item: { id, at, event, workerId, workerName, taskId, generationId, principal, lane, execMs, device } (gpu-workers.md) |
GET /api/admin/workers/events |
worker, kinds (a comma list of state, job, stage, looking, admin, version, log; all when not given), before, after, generation, limit (1 to 500, 100) |
{ items, next, latest }: the workers' timeline, newest first. Each item: { id, at, workerId, workerName, kind, event, words, taskId, generationId, lane, laneLabel, state, detail }. next pages back (as before); latest is the newest row id (as after, for new rows only) (gpu-workers.md) |
GET /api/admin/audit |
before (the last page's next), limit (1 to 200, default 50), actor (owner, token or system), token (a token id), action, changes=1 (changes only: no reads, file views or refusals) |
{ items, next } |
GET /api/admin/tokens/self |
{ id, name, prefix, scopes, expiresAt, createdAt } |
A log row is { id, at, actor: "owner" | "token" | "system", token: { id, name } | null, action, target, detail, status }.
token.name is the name the token had at the time. Actions: account.disable, account.enable, account.signout, account.password, account.email,
account.delete, run.delete, outputs.hide, outputs.unhide, outputs.remove, worker.add, worker.change,
worker.rotate, worker.revoke, worker.revoke_all (Sign everyone out with every API token), queue.settings (with
the values before and after), queue.mode, queue.override, queue.override.end, queue.cancel, run.rerun (the run as its target, with the account, the new run's ids and the reason), queue.mode.end
(actor system when a mode, a hold or a boost ended by itself), site.uploads (the upload switches, with the values before and after), site.runs (what people read when a run fails, with the values before and after), token.create, token.revoke,
token.revoke_all, settings.comfy_where (where ComfyUI runs, with the values before and after), settings.run_failure_detail (Settings → Failed runs, changed in the owner's browser, with the values before and after); a token's reads
accounts.list, accounts.csv, account.read, runs.list, reports.list, audit.read (one row per token and action
every 10 minutes); reads of accounts' content by a token or the owner: runs.content (one row per reader and account
every 10 minutes, the account as its target, or owner for the owner's own runs) and file.view (one row per reader and file every hour); refusals
scope.denied and rate.limited; and the studio's own alerts worker.alert (actor system: a worker's token used
from a new country, a new network, or two networks at once; gpu-workers.md) and
runs.waiting (actor system, at most once every 5 minutes: runs on this install's GPUs that have waited longer than
5 minutes for the billing or moderation service to answer, as counts only: waiting, billing, moderation,
oldestMin). The owner's other reads in the browser aren't logged. Rows go after a year. actor can be system, and
the actor filter takes it.
A row is written once the change is made. If the server can't write it (a full disk, say), the change still stands and the server's own log notes the missing row.
Errors and limits
Errors are { "error": "…" }, with a code where a tool may want to act on it:
| Status | When | Body |
|---|---|---|
| 400 | a wrong body or query | { error } |
| 401 | the token is unknown, revoked or expired | { error: "This admin token isn't valid.", code: "token" } |
| 403 | the token doesn't have the scope | { error: "This admin token can't do that.", code: "scope", scope } |
| 403 | an admin token outside /api/admin |
{ error: "An admin token only works on the admin API." } |
| 404 | not found | { error } |
| 429 | too many requests | { error: "Too many requests. Try again in a minute.", code: "rate" } and Retry-After |
Each minute, a token may send 120 reads, 30 changes and 600 file views (/api/admin/files), each counted on its own,
so a page of previews never uses up the next change. Wrong tokens count against their sender only (10 a minute per
client behind a trusted proxy, FUOBE_TRUST_PROXY=1; else 60 a minute together) and never slow down a valid token.
The limits are kept in the server's memory: a restart starts them again.
Behind a proxy or a CDN
The Authorization header must reach Fuobe: most reverse proxies forward it as it is. If a CDN or a bot check sits in
front of the site, a script's request may get a challenge page instead of JSON. Let /api/admin/ requests that carry
Authorization: Bearer fuobe_adm_… through without a challenge. Call the site's own HTTPS address, and don't follow
redirects with the token.