Build with Flare

Upload from a script, publish a build artifact, make a short link, or notify your own service when a file is ready. Flare's HTTP API uses your existing account, storage, and sharing settings. Named API tokens let each connection have its own permissions and lifetime.

You need a running Flare instance and an account. Every example uses https://files.example.com as a placeholder for your instance, not a shared Flare service.

Your first upload

1. Open Profile → Integrations on your Flare instance.
2. Create a named API token with files:upload. Give it a recognizable name, such as “Build artifacts,” and choose an expiration if appropriate.
3. Copy the secret when it appears. Flare cannot show it again.
4. Set FLARE_URL to your instance's HTTPS origin and provide FLARE_TOKEN through your shell environment or secret manager.
5. Send one file:

curl --fail-with-body \
  -H "Authorization: Bearer $FLARE_TOKEN" \
  -F 'file=@./screenshot.png' \
  "$FLARE_URL/api/files"

The response includes data.pageUrl, the share page to send to someone, alongside raw and download URLs. Let your HTTP client generate the multipart Content-Type boundary; do not set that header yourself.

Each account manages its own tokens, webhook destinations, and delivery history in Profile → Integrations.

Each account manages its own tokens, webhook destinations, and delivery history in Profile → Integrations.

Explore a request

Use the builder to see how your choices change a request. It generates a command locally; run the command against your own instance when you are ready.

BUILD YOUR FIRST REQUESTNo requests sent

Choose an operation and copy a working starting point. Set FLARE_TOKEN in your terminal to a named token with the required scope. The token owner must also have the current role permission. This builder covers named-token operations; account security changes and owner-library archive operations require a browser session. Use the signed-in Flare interface for bulk tag editing. Shared archive browsing and entry downloads instead follow file visibility and password rules; this token builder does not authorize them.

Instance URL

OperationUpload a fileList your filesBrowse your file timelineRefresh selected file metadataList short linksCreate a short link

POST /api/filesScope: files:uploadAccount permission: files.upload

curl --fail-with-body 'https://files.example.com/api/files' \
  -H "Authorization: Bearer $FLARE_TOKEN" \
  -F "file=@./screenshot.png"

Credentials never enter this demo. Run these requests yourself against your instance; uploads and short-link creation change your data.

Choose the right connection

What you want to do	Start here
Give a script only the permissions it needs	Authentication and scopes
Upload, list, search, or filter files	Files API
Upload a large file in parts	Chunked uploads
Browse shared archives or manage archives in your library	Archive API contracts
Create, list, or remove short links	Short links API
Run your own automation after an upload	Webhooks
Start with working code	Recipes
Integrate with browser sign-in, passkey requirements, and recovery	Session security contracts
Build browser session history or audit views	Sessions and audit contracts
Understand the rest of the application's routes	Endpoint inventory

For ShareX, iTake, Flameshot, Spectacle, and Bash, Flare can generate the uploader configuration for you in Profile → Uploads → Screenshot tools and scripts. Those downloads already contain your account upload credential. Named tokens are useful when building a custom connection, restricting permissions, or revoking one tool independently.

Machine-readable references

• Download the OpenAPI 3.1 document for all routes supported by named API tokens. Import it into an API client and replace the server URL with your instance.
• Download the file.ready JSON Schema for validating webhook payloads.
• Read the runnable Node.js example. It supports both uploading and receiving signed webhooks without extra packages.

The OpenAPI security scheme is HTTP Bearer authentication. Flare's permission names are application scopes; this is not an OAuth authorization flow.

Response conventions

The API has a few established response shapes. Check the HTTP status before reading the body, and use the reference for the endpoint you call.

Operation	Successful response
Multipart upload, file types, create/list short links	{ "success": true, "data": ... }
List files	{ "success": true, "data": [...], "pagination": ... }
Initialize upload, obtain part URL, upload part	{ "data": ... }
Complete with PUT /api/files/chunks	{ "data": ... }
Complete with POST /api/files/chunks/{uploadId}/complete	Upload links directly, with no data wrapper
Delete short link	204 No Content, with no JSON body

Errors contain an error string. Some include success: false; others do not. Authentication failures are 401 with { "error": "Unauthorized" }, including an expired token or a missing scope. Authenticated requests without the required role permission return 403. Do not depend on a success field being present on every response.

Limits and compatibility

Uploads follow the same maximum file size, storage quotas, file checks, upload profiles, and expiration rules as the dashboard. There is no separate API storage pool. A named token owned by an administrator still has only its selected API scopes. Every token request also requires the owner's current role permission; role revocation applies on the next request.

The API paths currently have no version prefix. These references describe the implementation shipped with the documentation. Webhook payloads do carry an explicit version: 1; check that field when processing events. Use the documentation from your Flare release when maintaining an older instance.

The sessions and audit routes require an interactive browser session. The request builder deliberately offers no token-authenticated session-revocation or audit operation. Audit events do not add a webhook type; file.ready and its schema/signing/retry behavior are unchanged.

Named tokens currently cover file listing/uploads and short links. Account administration, token/webhook management, file deletion, changing an existing file's settings, and organization management are dashboard operations. The endpoint inventory identifies their authentication boundaries without implying that they are additional bearer-token APIs.