Python API

Fileglancer’s HTTP API can be driven from Python using an API token. The client ships inside the same fileglancer package as the command-line tool, so pip install fileglancer is all you need on the machine running your script or notebook.

Creating a Token

The API Tokens page is available from the profile menu in the upper-right corner of any Fileglancer page.

Click your username or profile icon in the top-right corner, then select API Tokens from the dropdown menu.

Click New Token, then fill in the dialog:

• Name — a label you will recognize later, such as laptop notebook.
• Scopes — check the boxes for what the token should be allowed to do. See Scopes below.
• Expires in — 30, 90, or 365 days. There is no option to create a token that never expires.

Click Create.

Copy this now — it will not be shown again

The token secret is never stored by Fileglancer. A Token created dialog shows two lines:

export FILEGLANCER_URL=https://your-fileglancer-server
export FILEGLANCER_TOKEN=fgt_...

Click Copy and save both lines somewhere safe, such as your shell profile or a .env file, before closing the dialog. If you lose the secret, revoke the token and create another.

Scopes

Scope	Grants
files:read	List directories and read file contents
files:write	Create, rename, delete, and write files
links:read	List data links and Neuroglancer links
links:write	Create and delete data links and Neuroglancer links
jobs:read	List jobs and read each job’s full details, parameters, environment, and log files
jobs:write	Submit and cancel jobs

files:write and jobs:write are not enabled by default. Both amount to full access to your files, so each server opts into them deliberately — if they are missing from the scope list when you create a token, contact your Fileglancer administrator to ask whether they can be enabled.

A server can withhold any scope, not just those two. The token creation dialog shows only the scopes your server supports, and a token that carries a scope the server has since stopped supporting loses it: requests needing it fail with a 403 saying the scope is not enabled on this server.

A :write scope also grants the matching :read.

jobs:write runs code (pre_run, post_run, and the job command itself) on your behalf, so it has the same access to your files as you do — it is not confined by files:read or files:write.

Tokens cannot reach every endpoint. SSH keys, apps and the app catalog, preferences, file-conversion tickets, and token management itself are available only in the web interface, so a leaked token cannot be used to mint another one or change your account.

Connecting from Python

The client reads two environment variables:

export FILEGLANCER_URL=https://your-fileglancer-server
export FILEGLANCER_TOKEN=fgt_...

from fileglancer import Fileglancer

fg = Fileglancer()

You can also pass them directly, which takes precedence over the environment:

fg = Fileglancer(url="https://your-fileglancer-server", token="fgt_...")

Fileglancer also works as a context manager, which closes its connection pool automatically:

with Fileglancer() as fg:
    fg.ls("/data/alice")

Otherwise, call fg.close() when you are done with it.

Working with Paths

Every method takes an absolute filesystem path, the same path you would use on the command line.

fg.ls("/data/alice")
fg.stat("/data/alice/notes.txt")
fg.mkdir("/data/alice/analysis")
fg.write("/data/alice/notes.txt", b"hello")
fg.read("/data/alice/notes.txt")
fg.rename("/data/alice/a.zarr", "/data/alice/b.zarr")
fg.delete("/data/alice/tmp")

ls raises FileglancerError if the path is not a directory, rather than returning an empty list. stat returns metadata for a single file or directory without listing its contents.

mkdir and write both require the parent directory to already exist.

Paths in Mac (smb://...) and Windows (\\server\share\...) form are accepted too. Paths returned by the client are always in Linux form.

fg.file_share_paths() lists the shares available to you. A path that matches no share raises FileglancerError naming the path; call file_share_paths() to see what is available.

Data Links

A data link serves a folder over HTTP so that a viewer can read it.

link = fg.create_data_link("/data/alice/sample.zarr")
print(link.url)

fg.data_links()
fg.delete_data_link(link.sharing_key)

Neuroglancer Links

create_ng_link takes a Neuroglancer state as a plain dictionary, which is what neuroglancer.ViewerState.to_json() produces.

import neuroglancer
from fileglancer import Fileglancer

fg = Fileglancer()
link = fg.create_data_link("/data/alice/sample.zarr")

state = neuroglancer.ViewerState()
state.layers["sample"] = neuroglancer.ImageLayer(source=f"zarr://{link.url}")

print(fg.create_ng_link(state.to_json(), title="sample"))

This needs links:write on the token, and neuroglancer installed separately — the Fileglancer client does not depend on it.

Pass url_base to open the link in a different Neuroglancer instance.

Jobs

fg.jobs()
fg.jobs(status="RUNNING")
fg.job(job_id)
fg.cancel_job(job_id)

submit_job requires the app’s URL and an entry point id. The server requires a parameters field even when the entry point takes no arguments, so the client defaults it to an empty dict:

job = fg.submit_job(
    "https://github.com/owner/repo",
    "entry-point-id",
    parameters={"threshold": 0.5},
)

Any other field the /api/jobs endpoint accepts — resources, name, env, container, and so on — can be passed as an extra keyword argument.

Handling Errors

Anything the server rejects raises FileglancerError, carrying the server’s message and its HTTP status code.

from fileglancer import FileglancerError

try:
    fg.mkdir("/data/alice/new")
except FileglancerError as error:
    print(error, error.status_code)

A 403 usually means the token is missing a scope; the message names the one it needs.

A 401 with a message like API token expired on 2026-08-24 means the token’s expiry has passed. Expired tokens are not deleted — the API Tokens page still lists them, marked with an Expired badge, so you can tell which one lapsed. Tokens cannot be renewed or extended; create a new one and revoke the expired one.

Revoking a Token

Open the API Tokens page from the profile menu and click Revoke on the token you want to remove. A confirmation dialog asks you to confirm, since any script or notebook using that token will stop working immediately. Click Revoke Token to confirm, or Keep token to back out. This cannot be undone — create a new token if you need one again.