Endpoint inventory
Flare's dashboard also talks to HTTP routes. Their existence does not make all of them part of the named-token API. This inventory distinguishes the supported automation surface from session-based account/admin actions and public content routes.
Use the OpenAPI document for custom clients using flr_… tokens. It describes the 12 supported method/path combinations across seven paths. The rest of this page is a map for operators and contributors, not a promise of a general administrator REST API.
Paths use {id} for a dynamic segment. {path} and {nextauth} are catch-all path segments. Methods listed here are the implemented handlers; do not assume another method is supported because the path exists.
Named-token API
All of these routes also use Flare's shared account authentication helper. A named token must have the specific scope, and results are limited to its owner's account.
| Path | Method | Scope | Purpose |
|---|---|---|---|
/api/files | GET | files:read | Paginated file metadata, search, filters, and image neighbors. |
/api/files | POST | files:upload | One multipart file upload. |
/api/files/types | GET | files:read | MIME types present in the account. |
/api/files/chunks | POST | files:upload | Initialize a chunk upload. |
/api/files/chunks | GET | files:upload | Obtain a part URL using uploadId and partNumber query parameters. |
/api/files/chunks | PUT | files:upload | Complete an upload, returning a data wrapper. |
/api/files/chunks/{uploadId}/part/{partNumber} | GET | files:upload | Obtain a part upload URL. |
/api/files/chunks/{uploadId}/part/{partNumber} | PUT | files:upload | Upload raw part bytes through Flare. |
/api/files/chunks/{uploadId}/complete | POST | files:upload | Complete an upload, returning links without a wrapper. |
/api/urls | GET | urls:read | List the account's short links. |
/api/urls | POST | urls:write | Create a short link. |
/api/urls/{id} | DELETE | urls:write | Delete an owned short link. |
See files, short links, and authentication for request/response details.
File content and access checks
These routes check the file's visibility, password, and an optional browser session. They do not use named bearer tokens to grant file access. Public unprotected files can be fetched anonymously. Private files require an owner or administrator session and return 404 to ineligible viewers. A password-protected public file requires its password unless the browser session belongs to its owner or an administrator.
| Path | Methods | Purpose |
|---|---|---|
/api/files/{path} | GET | Raw stored content by file URL path; download=true requests attachment handling. |
/api/files/{id}/download | GET, POST | Download content. GET accepts a password query value; POST accepts password JSON. S3 storage can redirect after access validation. |
/api/files/{id}/thumbnail | GET | Serve an image for thumbnail display; currently streams the original image. |
/api/files/{id}/ocr | GET | Fetch image OCR text, processing it if necessary, after access validation. |
Raw/thumbnail/OCR GET requests accept a password query parameter when applicable. Prefer the normal share-page password flow for people using a browser; URLs containing passwords can be retained in history or logs.
The public-facing route /{userUrlId}/{filename}/raw also enforces file access. /{userUrlId}/{filename}/direct is a video-only lookup that returns JSON containing a signed storage URL or raw-route fallback after checking access; it does not stream the file itself. An issued S3 URL can remain valid until its own expiry after Flare access settings change. /{userUrlId}/{filename} is the rendered share page. GET /u/{shortCode} publicly redirects a short link and increments its count.
Dashboard account routes requiring a browser session
These routes explicitly read an interactive session. Neither a named API token nor a legacy account upload token by itself supplies that session. Ownership and feature-policy checks still apply.
| Path | Methods | Purpose |
|---|---|---|
/api/integrations | GET, POST | List/manage named tokens, webhooks, and deliveries. POST uses action commands and validates same-origin JSON requests. |
/api/upload-profiles | GET, POST | List profiles; create/import a profile. |
/api/upload-profiles/{id} | PUT, DELETE | Update an owned profile using its revision or delete it. |
/api/upload-profiles/{id}/export | GET | Export a portable profile recipe. |
/api/upload-profiles/default | PUT | Select or clear the account's default profile. |
/api/customization | GET | Read published appearance; administrators also receive draft/history state. |
/api/customization/preferences | GET, PATCH | Read/save personal appearance preference. |
/api/profile/avatar | POST | Upload an account avatar. |
/api/profile/sharex | GET | Download a ShareX uploader configuration. |
/api/profile/itake | GET | Download an iTake uploader configuration. |
/api/profile/bash | GET | Download the Bash uploader script. |
/api/profile/flameshot | POST | Generate a Flameshot script from submitted tool options. |
/api/profile/spectacle | POST | Generate a Spectacle script from submitted tool options. |
/api/profile/export/progress | GET | Stream account-export progress using server-sent events. |
/api/files/{id} | PATCH, DELETE | Change an owned file's visibility/password or delete it. |
Profile and appearance mutations have explicit origin/content-type guards. Integration commands likewise enforce same-origin JSON and a bounded body size. Generated uploader configurations contain a credential and should be treated as private downloads.
Email account flows
Email enrollment and change operations use an account session that remains available for verification/recovery flows. They deliberately do not use upload bearer credentials.
| Path | Methods | Authentication and purpose |
|---|---|---|
/api/auth/email/status | GET | Session; current verification, enrollment, change, and recovery eligibility. |
/api/auth/email/enroll | POST | Session and recent identity/password requirements; begin local verification enrollment. |
/api/auth/email/change | POST | Session and identity/policy checks; request an address change. |
/api/auth/email/resend | POST | Session; resend an eligible pending verification. |
/api/auth/email/cancel-change | POST | Session; cancel the pending address change. |
/api/auth/email/request-reset | POST | Public recovery request, rate-limited with a generic eligibility response. |
/api/auth/email/reset | POST | A valid one-time reset token and new password; not an API bearer token. |
/api/auth/email/verify | POST | A valid one-time email action token. |
/api/auth/email/capabilities | GET | Public view of enabled email capabilities. |
Email session mutations validate the request origin when provided. Password/identity confirmation, feature enablement, verified-address policy, and cooldowns are additional checks beyond the authentication column.
Dashboard routes using the shared account helper
These routes use requireAuth, whose compatibility path accepts a browser session or the legacy account upload token. They are absent from the named-token allowlist, so an flr_… token cannot authorize them. This is why the legacy token should not be described as a narrowly scoped credential.
| Path | Methods | Purpose |
|---|---|---|
/api/profile | PUT, DELETE | Update the account or delete it, subject to route-specific safeguards. |
/api/profile/upload-token | GET, POST | Read or regenerate the legacy account upload credential. |
/api/profile/export | GET | Export account data/files. |
/api/files/{id}/expiry | GET, POST, DELETE | Inspect, schedule, or cancel expiration for an owned file. |
/api/folders | GET, POST | List or create folders. |
/api/folders/{id} | PATCH, DELETE | Rename/move or delete an owned folder. |
/api/files/folders | POST | Move owned files into a folder or make them unfiled. |
/api/tags | GET, POST | List or create tags and their rules. |
/api/tags/{id} | PATCH, DELETE | Edit or delete an owned tag. |
/api/tags/{id}/apply | POST | Apply a tag's rule to existing files. |
/api/files/tags | PATCH | Change tag associations for selected owned files. |
Folder/tag mutations also require their origin and content-type guards. This table describes actual authentication code, not a recommendation to use the legacy token to automate account changes. New integrations should use the documented named-token API, and people should use the dashboard for these operations.
Administrator session routes
These operations require a signed-in administrator. Named tokens do not inherit an administrator's authority.
| Path | Methods | Purpose |
|---|---|---|
/api/users | GET, POST, PUT | List, create, or edit users. |
/api/users/{id} | DELETE | Delete a user. |
/api/users/{id}/avatar | DELETE | Remove a user's avatar. |
/api/users/{id}/sessions | DELETE | Invalidate a user's sessions. |
/api/users/{id}/email | GET, POST | View email-policy state and perform permitted administrator email actions. |
/api/users/{id}/files | GET | Inspect a user's file list. |
/api/users/{id}/files/{fileId} | PATCH, DELETE | Change file access settings or remove a user's file. |
/api/users/{id}/urls | GET | Inspect a user's short links. |
/api/users/{id}/login | POST | Fetch target-user information used by the administrator's account-switching flow; this endpoint alone does not issue a login session. |
/api/settings | PATCH, POST | Update a settings section or legacy whole-settings payload. Email/customization use their dedicated routes. |
/api/settings/favicon | POST | Upload a legacy instance favicon. |
/api/settings/email | GET, PUT | Read/save email configuration and diagnostics. |
/api/settings/email/impact | GET, POST | Preview the affected users for saved or proposed email policy. |
/api/settings/email/test | POST | Test SMTP connection or send a test message. |
/api/settings/email/retry | POST | Retry an eligible mail-outbox entry. |
/api/customization | POST | Save/import/publish/restore appearance using action commands. |
/api/customization/assets | POST | Upload a validated appearance asset. |
/api/updates/check | GET | Check for a newer Flare release. |
Email administration validates origins for mutations; appearance administration uses explicit same-origin/content-type guards. Role checks are independent of these request guards.
Public and bootstrap routes
| Path | Methods | Authentication and purpose |
|---|---|---|
/api/health | GET | Public process liveness: { "success": true, "data": { "status": "ok" } }. Does not probe PostgreSQL or storage. |
/api/storage/type | GET | Public storage kind (local or s3); falls back to local on an initialization error. Not a storage health check. |
/api/setup/check | GET | Public setup-completion state. |
/api/setup | POST | First-run bootstrap only while no users exist; creates the initial administrator/settings atomically and rate-limits attempts. |
/api/auth/registration-status | GET | Public registration availability and message. |
/api/auth/register | POST | Public account creation, subject to registration settings, validation, email policy, and rate limits. |
/api/auth/{nextauth} | GET, POST | NextAuth session, sign-in/out, provider, CSRF, and callback flows; protocol-specific protections apply. |
/api/settings | GET | Returns public settings anonymously or to non-admins; an authenticated administrator through the shared helper receives the fuller settings view. Named tokens receive only the public fallback. |
/api/favicon | GET | Serve the configured favicon/fallback. |
/api/avatars/{filename} | GET | Serve an avatar image. |
Public does not mean unrestricted mutation: registration can be closed and bootstrap stops once a user exists. Email one-time-token routes are listed separately because possession of the relevant action token is their authorization.
Maintaining an integration
Build new automation against the named-token routes and their OpenAPI schemas. For dashboard behavior, treat route bodies and session flows as application internals that can evolve with Flare. There is currently no named-token administrator API, no general token-authorized file deletion/download API, and no chunk-cancel endpoint.
The route inventory is checked against the source tree when the documentation is validated, so a newly added route prompts a documentation update instead of silently expanding a token's authority.