All errors are formatted as JSON objects with the following structure. The statusCode field is the same as the HTTP status code returned by the server.

Zipline's API ratelimits certain endpoints to prevent spam and is usually only

Ratelimit

Most API endpoints require authentication. Zipline supports cookie-based and token-based authentication

Authentication

The following guides will help you get started with Zipline.

Docker

Building from source

Getting Started

This page documents and guides you through setting up OAuth for Zipline.

This page explains how to set up Discord OAuth in Zipline.

Discord

This page guides you through setting up GitHub OAuth for Zipline.

GitHub

This page guides you through setting up Google OAuth for Zipline.

Google

This page documents and guides you through setting up Open ID Connect (OIDC) for Zipline. If you are having trouble configuring a different OIDC provider that is not listed here, feel free to join the Discord and ask for help.

OIDC

OAuth

Zipline can generate a .sxcu (ShareX Custom Uploader) file for you to use with ShareX. With this you can easily upload files to your Zipline instance using ShareX.

Windows: ShareX

This section requires Flameshot, jq, and xsel.

Flameshot

iOS: Shortcuts

This guide uses the github.com/tsudoku/xshare app as a way to upload files from an Android device.

Android: xshare

Zipline can generate a .iscu (iShare Custom Uploader) file for you to use with iShare. With this you can easily upload screenshots/recordings on MacOS to your Zipline instance using iShare.

MacOS: ishare

This guide will show you how to generate a shell-script that takes an argument (file/url) and uploads it to Zipline.

Shell Script

Uploaders

Zipline provides a command line utility called ziplinectl to manage specific parts of your Zipline instance.

ziplinectl

Output the current configuration as JSON.

ziplinectl read-config

Import a directory of files into Zipline.

ziplinectl import-dir

ziplinectl set-user

Lists all users in Zipline in a JSON format.

ziplinectl list-users

Export the current configuration as environment variables.

ziplinectl export-config

Command Line

2 Factor Authentication with TOTP (time-based one-time password) is a security feature that adds an extra layer of protection to your account. It requires you to enter a code from your phone (an app like 2FAS, Authy, Google Authenticator, etc.) in addition to your password when logging in.

Some settings use human readable byte sizes. Here is a table of the byte sizes and their human readable counterparts.

Bytes

Zipline offers a couple of settings that let you customize the dashboard to your liking. This guide will walk you through the available options.

Customizing the Dashboard

Enabling debug mode will show more verbose logs. This is mostly useful when debugging an issue with Zipline.

Debug

Discord webhooks are a simple way to get "notifications" sent to a text channel in your Discord server. Zipline offers a way to send notifications to a Discord webhook whenever a file is uploaded or a URL is shortened.

Discord Webhooks

External links are links configured to show up on the bottom of the sidebar.

External Links

If you have enabled HTTP Webhooks within the dashboard settings, Zipline will send a POST request to the URL with the file/url information.

HTTP Webhooks

Some settings use human readable relative time. Here is a table of the time units and their human readable counterparts.

Milliseconds

Passkeys are a way to authenticate users without requiring them to enter a password. Instead, users can click "Login with a passkey" and follow their device prompts to authenticate.

Passkeys

This guide aims to explain and walk you through how to backup any postgres

Backup Postgres

Zipline is currently being maintained by me (@diced) and only me. New releases can come out frequently or take a while depending on my schedule. If a new minor/patch release (4.x.x) is not out, you can build from source or use the trunk tag on docker for the latest commit version.

Releases

This page will guide you through setting up a reverse proxy for Zipline using various different methods.

Reverse Proxy

These are small "maintenance" actions that can be performed on the server. This section is found under the "Settings" button when clicking your user icon in the top right corner.

Server Actions

Zipline supports using SSL natively through the SSLCERT and SSLKEY environment variables.

You can create custom themes for Zipline by adding JSON files within the themes/ directory (relative to the root of Zipline).

Themes

Video Thumbnails are generated by ffmpeg and are used to display a preview image of the video file. Thumbnails are generated on a scheduled interval, but you can also generate them manually.

Video Thumbnails

Upload options are HTTP headers that can be used to change various settings for file uploads.

Upload Options

Variables can be used in Discord Webhook messages and the view route to customize the message with dynamic content.

Variables

Version checking is a feature that notifies you on the dashboard whenever a new version is available, or if you are using a version that is outdated.

Version Checking

View Routes on Zipline allow you to customize the appearance of files when they are viewed through the browser. By this we mean that instead of just showing the raw file and letting the browser handle it, the file is rendered in a more "user-friendly" way.

View Routes

Having trouble taking screenshots or recording on Wayland (Linux)? Here are a bunch of different ways to do both of those things. Most problems arise when using a wlroots based compositor, it's easier when using GNOME or KDE with Flameshot.

Wayland Guide

Guides

This page will document every configuration option available in Zipline through environment variables, as well as through the settings dashboard.

This page documents the core configuration options available.

Core

This page will document the configuration options available for the datasource.

Datasource

This page documents the configuration options available for SSL. Both the SSLCERT and SSLKEY environment variables are required to enable SSL.

As of Zipline v4, most configuration options can be managed through the settings dashboard. However, some settings require a server restart.

Settings

Config

This guide will help you migrate from v3 to v4

Migrate From v3

Contributions of any kind are welcome, whether they are bug reports, pull requests, or feature requests.

Contributing

Security Policy

API Documentation is a work-in-progress. The API is always subject to change, so please refer to the src/server/routes directory for the source code of the API routes.

Represents a stored file, its metadata, and associated properties.

File

Represents an invite created by a user to allow others to join a Zipline instance.

Folder

Represents an in-progress, partial upload for a user. Used to track uploads that are not yet complete, or are still processing in the background.

IncompleteFile

Invite

Represents a tag that can be associated with files.

The User object represents a Zipline user and their associated settings, authentication providers, security credentials, quotas, and view-route preferences.

User

Models

Errors

Perform various actions on users, or retrieve all the users in the database.

Get a specific user by their ID, and make changes to their user.

/api/users/:id

/api/users

Get the currently logged in user, and perform actions on the current user.

List and search files for the authenticated user (with pagination, sorting, and filters).

View, update, or delete a specific file you own (by ID or filename).

/api/user/files/:id

View processing files that are incomplete or not fully processed yet.

/api/user/files/incomplete

Perform bulk actions on your files: delete, favorite/unfavorite, or move to a folder.

/api/user/files/transaction

/api/user/files

View, update, or delete a specific folder by its ID.

/api/user/folders/:id

/api/user/folders

Create new shortened URLs or view all of your existing URLs.

/api/user/urls

View or create tags that are assigned to files.

View, update, or delete a specific tag owned by the currently authenticated user.

/api/user/tags/:id

/api/user/tags

/api/user/mfa/passkey

Manage TOTP (Time-based One-Time Password) for multi-factor authentication

/api/user/mfa/totp

/api/user/mfa

Get a base64 avatar image for the current user. This is the endpoint that you should use to get the avatar, as no other endpoint will include the avatar in the user object.

/api/user/avatar

Export, download, and delete a data archive (export) as the current user.

/api/user/export

/api/user/recent

View and manage the logged in user's sessions.

/api/user/sessions

/api/user/stats

Get a valid token or refresh the underlying key that generates valid tokens.

/api/user/token

/api/user

Get or update server-wide configuration settings.

/api/server/settings

/api/server/settings/web

Delete temporary files in your temp directory (useful for cleaning up after exports, failed uploads, etc).

/api/server/clear_temp

Find and (optionally) delete files with zero-byte size from your storage/database.

/api/server/clear_zeros

Get limited info on a folder while not being authenticated. This is used for the /folder/ route.

/api/server/folder/:id

This endpoint is used to fetch "public" configuration options. This may be useful for building custom clients, as it requires no authentication.

/api/server/public

Trigger a server-side re-query to recalculate or clean up file sizes.

/api/server/requery_size

Get a list of themes that are available on the instance. You don't need to authenticate to receieve themes.

/api/server/themes

Manually trigger the thumbnail generation task.

/api/server/thumbnails

/api/server

View all invites or create an invite code.

/api/auth/invites/:id

/api/auth/invites

Authenticate a user and register a session.

/api/auth/login

Log out the currently authenticated user and invalidate their current session.

/api/auth/logout

Register a new user account and log them in. Works with invites.

/api/auth/register

Use a WebAuthn credential to login to an account.

/api/auth/webauthn

/api/auth

Perform a simple healthcheck on the database and backend of Zipline. Returns a simple pass/fail response.

/api/healthcheck

Perform a first time setup of Zipline, or retrieve the current setup status. This endpoint is used internally during the first run of Zipline to initialize a user.

/api/setup

Get metrics and statistics of the current Zipline instance.

/api/stats

Upload one file as a partial upload. This route doesn't support regular uploads, and if it receives a normal upload, it wil reject it. Quota and folder restrictions may apply.

/api/upload/partial

Upload one or more files. Supports both regular and chunked ("partial") uploads. Quota and folder restrictions may apply.

/api/upload

Returns version details of the backend, including current version, release status, and upstream/latest version information.

Property	Type	Description
`error`	`string`	A short error code or message.
`statusCode`	`number`	HTTP status code (e.g., 400, 404).

Errors

Examples