# Docs

- Documentation
  - Get started
    - [Get started](/docs/get-started): The following guides will help you get started with Zipline.
    - [Docker](/docs/get-started/docker): Install and run Zipline with Docker*
    - [Building from source](/docs/get-started/source): Build and run Zipline from source. Not recommended for most users.
  - Configuration
    - [Config](/docs/config): All the environment variables / settings you can use to configure Zipline
    - [Core](/docs/config/core): This page documents the core configuration options available
    - [Datasource](/docs/config/datasource): This page will document the configuration options available for the datasource
    - [Settings](/docs/config/settings): Settings that can be configured through the dashboard, as well as environment variables
    - [SSL (Deprecated)](/docs/config/ssl): Deprecated SSL support (4.4.1+)
  - Guides
    - OAuth
      - [OAuth](/docs/guides/oauth): Configure OAuth providers for authentication
      - [Discord](/docs/guides/oauth/discord): Set up Discord OAuth in Zipline
      - [GitHub](/docs/guides/oauth/github): Set up GitHub OAuth for Zipline
      - [Google](/docs/guides/oauth/google): Setting up Google OAuth for Zipline
      - [OIDC](/docs/guides/oauth/oidc): Setting up Open ID Connect (OIDC) for authentication
    - CTL
      - [ziplinectl](/docs/guides/ctl/ziplinectl): Manage specific parts of your Zipline instance with the ziplinectl command line utility
      - [ziplinectl export-config](/docs/guides/ctl/ziplinectl-export-config): Export the current configuration as environment variables
      - [ziplinectl import-dir](/docs/guides/ctl/ziplinectl-import-dir): Import a directory of files into Zipline
      - [ziplinectl list-users](/docs/guides/ctl/ziplinectl-list-users): List all users in Zipline
      - [ziplinectl read-config](/docs/guides/ctl/ziplinectl-read-config): Output the current configuration as JSON.
      - [ziplinectl set-user](/docs/guides/ctl/ziplinectl-set-user): Modify a user's properties
    - Backup
      - [Import & Export](/docs/guides/backup/instance): Export and import data between Zipline instances
      - [Backup Postgres](/docs/guides/backup/pg): How to backup a Postgres database
    - Uploaders
      - [Windows: ShareX](/docs/guides/uploaders/windows-sharex): Use ShareX to upload files to Zipline on Windows
      - [iOS: Shortcuts](/docs/guides/uploaders/ios-shortcuts): Use the Zipline shortcut on iOS to upload and shorten links from your device
      - [Android: xshare](/docs/guides/uploaders/android-xshare): Use the xshare app to upload files from your Android device to Zipline
      - [Flameshot](/docs/guides/uploaders/flameshot): Upload screenshots taken with Flameshot to Zipline
      - [macOS: ishare](/docs/guides/uploaders/macos-ishare): Use iSshare to upload screenshots/recordings on macOS
      - [Shell Script](/docs/guides/uploaders/shell-script): Uploading a file using a shell script
    - [2FA](/docs/guides/2fa): How to enable 2 Factor Authentication (2FA) with TOTP in Zipline
    - [Bytes](/docs/guides/bytes): Byte sizes used in env vars and settings
    - [Customizing the Dashboard](/docs/guides/customize-dash): How to customize the Zipline dashboard with the available settings
    - [Debug](/docs/guides/debug): Enable verbose logging or detailed memory usage to help diagnose issues
    - [Discord Webhooks](/docs/guides/discord-webhooks): Discord webhooks integration with Zipline for notifications on file uploads and URL shortening.
    - [External Links](/docs/guides/external-links): Configure sidebar links on the dashboard
    - [Hardening](/docs/guides/hardening): Things to turn on if you're sharing your instance with anyone besides yourself
    - [HTTP Webhooks](/docs/guides/http-webhooks): Configure HTTP webhooks to send JSON POST requests to specified URLs
    - [Milliseconds](/docs/guides/ms): Time units used in env vars and settings
    - [Passkeys](/docs/guides/passkeys): Authenticate users with WebAuthn passkeys instead of passwords
    - [Releases](/docs/guides/releases): Information about Zipline releases and how to update
    - [Reverse Proxy](/docs/guides/reverse-proxy): Guides for setting up reverse proxies for Zipline, including NGINX and Caddy
    - [Server Actions](/docs/guides/server-actions): Perform maintenance actions on the server, such as clearing temp files, requerying file sizes, and managing imports
    - [SSL](/docs/guides/ssl): Setting up SSL with Zipline
    - [Themes](/docs/guides/themes): Create custom themes
    - [Thumbnails](/docs/guides/thumbnails): Configure video thumbnail generation
    - [Upload Options](/docs/guides/upload-options): HTTP headers that can be used to change various settings for file uploads.
    - [Variables](/docs/guides/variables): Use variables to customize your messages with dynamic content
    - [Version Checking](/docs/guides/version-checking): Configure version checking settings
    - [View Routes](/docs/guides/view-routes): Customize the preview of files when viewed through the browser
    - [Wayland Guide](/docs/guides/wayland): How to upload videos/screenshots from a Wayland session
  - [Contributing](/docs/contributing): How to contribute to Zipline, including bug reports, feature requests, and pull requests.
  - [Migrate from v3](/docs/migrate): A guide to help you migrate from Zipline v3 to v4.
  - [Security Policy](/docs/security): How to report security vulnerabilities and the supported versions of Zipline.
- API Reference: OpenAPI specification for the API endpoints
  - [API Documentation](/docs/api): Learn how to use the Zipline API to programmatically
  - [Authentication](/docs/api/authentication): Learn how to authenticate with the Zipline API
  - [Error Handling](/docs/api/errors): Learn how to handle errors returned by the Zipline API

  - **Routes**
  - [/api/healthcheck](/docs/api/api/healthcheck/get): Perform a simple healthcheck on the database and backend of Zipline. Returns a simple pass/fail response.
  - [/api/setup](/docs/api/api/setup/get): Return whether Zipline is in first-time setup mode, used by the initial setup flow.
  - [/api/setup](/docs/api/api/setup/post): Perform the first-time setup by creating the initial SUPERADMIN user.
  - [/api/stats](/docs/api/api/stats/get): Get instance-wide metrics and statistics for Zipline over a given date range or for all time.
  - [/api/version](/docs/api/api/version/get): Return backend version information, including current build details and upstream/latest version metadata.
  - [/api/auth/login](/docs/api/api/auth/login/post): Authenticate a user, creating a session and optionally requiring a TOTP code when multi-factor auth is enabled.
  - [/api/auth/logout](/docs/api/api/auth/logout/get): Log out the currently authenticated user and invalidate their active session.
  - [/api/auth/register](/docs/api/api/auth/register/post): Register a new user account and immediately authenticate them, optionally consuming an invite code.
  - [/api/auth/webauthn/options](/docs/api/api/auth/webauthn/options/get): Generate WebAuthn authentication options for logging in with an existing passkey.
  - [/api/auth/webauthn](/docs/api/api/auth/webauthn/post): Verify a WebAuthn authentication response and log in the user associated with the matching passkey.
  - [/api/server/clear_temp](/docs/api/api/server/clear_temp/delete): Delete temporary files on the Zipline server and return a short status message (admin only).
  - [/api/server/clear_zeros](/docs/api/api/server/clear_zeros/get): Scan for zero-byte files on disk and return the list of candidates to delete (admin only).
  - [/api/server/clear_zeros](/docs/api/api/server/clear_zeros/delete): Delete zero-byte files previously detected on disk and return a short status message (admin only).
  - [/api/server/export](/docs/api/api/server/export/get): Export Zipline server data as a version 4 export bundle or return aggregate counts of core resources.
  - [/api/server/folder/{id}](/docs/api/api/server/folder/id/get): Fetch a folder by ID/name. Behavior varies based on public and allowUploads flags.
  - [/api/server/public](/docs/api/api/server/public/get): Return the public Zipline configuration used by the client, including OAuth, website, feature, file and chunk settings.
  - [/api/server/requery_size](/docs/api/api/server/requery_size/post): Re-scan stored files to update their sizes and optionally delete missing ones, returning a short status message (admin only).
  - [/api/server/status](/docs/api/api/server/status/get): Get disk status for the configured datasource
  - [/api/server/themes](/docs/api/api/server/themes/get): List all available themes and indicate which theme is currently configured as the default.
  - [/api/server/thumbnails](/docs/api/api/server/thumbnails/post): Manually trigger the thumbnails background task, optionally rerunning it for existing files (admin only).
  - [/api/upload](/docs/api/api/upload/post): Upload one or more files for the authenticated user, applying quota, folder, and upload option restrictions.
  - [/api/upload/partial](/docs/api/api/upload/partial/post): Upload a single file in chunks as a partial upload session, using headers to control chunking and resumption.
  - [/api/user/activity](/docs/api/api/user/activity/get): Daily upload and login counts for the authenticated user over a recent window.
  - [/api/user/avatar](/docs/api/api/user/avatar/get): Return the current user's avatar as a base64 data URL.
  - [/api/user/export](/docs/api/api/user/export/get): List your exports or download a specific completed export archive by ID.
  - [/api/user/export](/docs/api/api/user/export/post): Start an export job that zips all of your files into a downloadable archive.
  - [/api/user/export](/docs/api/api/user/export/delete): Delete a specific export and remove its archive file from storage.
  - [/api/user](/docs/api/api/user/get): Get the currently authenticated user and their token.
  - [/api/user](/docs/api/api/user/patch): Update the current user's profile, credentials, avatar, and view settings.
  - [/api/user/recent](/docs/api/api/user/recent/get): Get the most recently uploaded files for the authenticated user.
  - [/api/user/sessions](/docs/api/api/user/sessions/get): List the current browser session and other active sessions for the authenticated user.
  - [/api/user/sessions](/docs/api/api/user/sessions/delete): Invalidate one or all other sessions for the authenticated user.
  - [/api/user/stats](/docs/api/api/user/stats/get): View aggregate statistics for the authenticated user's files and URLs.
  - [/api/user/token](/docs/api/api/user/token/get): Return an encrypted API token for the authenticated user.
  - [/api/user/token](/docs/api/api/user/token/patch): Refresh the user's underlying token secret and return an updated token and user object.
  - [/api/users](/docs/api/api/users/get): List users in the instance, optionally excluding the current admin from the results (admin only).
  - [/api/users](/docs/api/api/users/post): Create a new user with the given username, password, avatar, and role (admin only).
  - [/api/auth/invites/{id}](/docs/api/api/auth/invites/id/get): Fetch a specific invite by ID or code, including information about the inviter (admin only).
  - [/api/auth/invites/{id}](/docs/api/api/auth/invites/id/delete): Delete a specific invite by ID (admin only).
  - [/api/auth/invites](/docs/api/api/auth/invites/get): List all existing invite codes and their metadata (admin only).
  - [/api/auth/invites](/docs/api/api/auth/invites/post): Create a new invite code for user registration, optionally limiting uses and expiration (admin only).
  - [/api/auth/invites/web](/docs/api/api/auth/invites/web/get): Look up a public invite by code for the web UI, returning basic information about the inviter and usage limits.
  - [/api/auth/oauth/discord](/docs/api/api/auth/oauth/discord/get)
  - [/api/auth/oauth/github](/docs/api/api/auth/oauth/github/get)
  - [/api/auth/oauth/google](/docs/api/api/auth/oauth/google/get)
  - [/api/auth/oauth](/docs/api/api/auth/oauth/get): List OAuth providers currently linked to the authenticated user.
  - [/api/auth/oauth](/docs/api/api/auth/oauth/delete): Unlink one OAuth provider from the authenticated user, enforcing that at least one login method remains.
  - [/api/auth/oauth/oidc](/docs/api/api/auth/oauth/oidc/get)
  - [/api/server/import/v3](/docs/api/api/server/import/v3/post): Import data from a legacy Zipline v3 export file, creating users, files, folders and URLs and returning a mapping of old IDs to new IDs.
  - [/api/server/import/v4](/docs/api/api/server/import/v4/post): Import data from a Zipline v4 export file, optionally merging into the current user and returning counts of imported records.
  - [/api/server/settings](/docs/api/api/server/settings/get): Fetch the full Zipline server settings row along with a list of configuration keys that were overridden at runtime (admin only).
  - [/api/server/settings](/docs/api/api/server/settings/patch): Partially update Zipline server settings using a validated subset of configuration keys (admin only).
  - [/api/server/settings/web](/docs/api/api/server/settings/web/get): Return the safe dashboard configuration and MIME type code map used by the web UI.
  - [/api/user/files/incomplete](/docs/api/api/user/files/incomplete/get): List incomplete or still-processing file uploads for the authenticated user.
  - [/api/user/files/incomplete](/docs/api/api/user/files/incomplete/delete): Delete one or more incomplete file records owned by the authenticated user.
  - [/api/user/files](/docs/api/api/user/files/get): List, filter, and search files for the authenticated user (or another user if permitted).
  - [/api/user/files/transaction](/docs/api/api/user/files/transaction/patch): Bulk update files owned by the user: favorite/unfavorite or move them into a folder.
  - [/api/user/files/transaction](/docs/api/api/user/files/transaction/delete): Bulk delete files (and optionally delete the underlying datasource objects).
  - [/api/user/folders](/docs/api/api/user/folders/get): List folders for the authenticated user, optionally including files or filtering by parent/root.
  - [/api/user/folders](/docs/api/api/user/folders/post): Create a new folder for the authenticated user, optionally public and/or seeded with files.
  - [/api/user/mfa/passkey](/docs/api/api/user/mfa/passkey/get): List all registered passkey credentials for the authenticated user.
  - [/api/user/mfa/passkey](/docs/api/api/user/mfa/passkey/post): Register a new WebAuthn passkey for the authenticated user.
  - [/api/user/mfa/passkey](/docs/api/api/user/mfa/passkey/delete): Remove an existing passkey credential from your account.
  - [/api/user/mfa/passkey/options](/docs/api/api/user/mfa/passkey/options/get): Generate WebAuthn registration options for creating a new passkey.
  - [/api/user/mfa/totp](/docs/api/api/user/mfa/totp/get): Get your current TOTP secret, generating one (and a QR code) if not yet enabled.
  - [/api/user/mfa/totp](/docs/api/api/user/mfa/totp/post): Enable TOTP for your account by verifying a code for the provided secret.
  - [/api/user/mfa/totp](/docs/api/api/user/mfa/totp/delete): Disable TOTP for your account after confirming a valid TOTP code.
  - [/api/user/tags/{id}](/docs/api/api/user/tags/id/get): Fetch a specific tag by ID, ensuring it is owned by the authenticated user.
  - [/api/user/tags/{id}](/docs/api/api/user/tags/id/patch): Update the name and/or color of a specific tag.
  - [/api/user/tags/{id}](/docs/api/api/user/tags/id/delete): Delete a specific tag owned by the authenticated user.
  - [/api/user/tags](/docs/api/api/user/tags/get): List all tags created by the authenticated user.
  - [/api/user/tags](/docs/api/api/user/tags/post): Create a new tag with a name and color for organizing files.
  - [/api/user/urls](/docs/api/api/user/urls/get): List or search shortened URLs owned by the authenticated user.
  - [/api/user/urls](/docs/api/api/user/urls/post): Create a new shortened URL for the authenticated user, with optional vanity, password, and max-views settings.
  - [/api/users/{id}](/docs/api/api/users/id/get): Fetch a specific user by ID, including their profile and role (admin only).
  - [/api/users/{id}](/docs/api/api/users/id/patch): Update another user's profile, credentials, role, and optional file quota limits (admin only).
  - [/api/users/{id}](/docs/api/api/users/id/delete): Delete another user by ID, optionally cascading deletion of their files and URLs (admin only).
  - [/api/users/{id}/tags](/docs/api/api/users/id/tags/get): List tags owned by the specified user, enforcing role-based interaction rules (admin only).
  - [/api/user/files/{id}](/docs/api/api/user/files/id/get): Fetch a single file owned by the authenticated user (or another user if permitted) by ID or short name.
  - [/api/user/files/{id}](/docs/api/api/user/files/id/patch): Update metadata for a single file, including favorite, name, tags, password, and view limits.
  - [/api/user/files/{id}](/docs/api/api/user/files/id/delete)
  - [/api/user/files/{id}/password](/docs/api/api/user/files/id/password/post): Verify the password for a password-protected file by ID or name and receive an access token if the password is correct
  - [/api/user/files/{id}/raw](/docs/api/api/user/files/id/raw/get): Stream a file or thumbnail owned by the authenticated user by ID, with optional password and download handling.
  - [/api/user/folders/{id}/export](/docs/api/api/user/folders/id/export/get): Download a ZIP archive of all files contained in a folder and its subfolders.
  - [/api/user/folders/{id}](/docs/api/api/user/folders/id/get): Fetch a specific folder by ID, optionally including files, children, and its parent chain.
  - [/api/user/folders/{id}](/docs/api/api/user/folders/id/patch): Update a folder's visibility, name, upload permissions, or parent.
  - [/api/user/folders/{id}](/docs/api/api/user/folders/id/delete)
  - [/api/user/folders/{id}](/docs/api/api/user/folders/id/put): Add a file to a specific folder owned by the user.
  - [/api/user/urls/{id}](/docs/api/api/user/urls/id/get)
  - [/api/user/urls/{id}](/docs/api/api/user/urls/id/patch)
  - [/api/user/urls/{id}](/docs/api/api/user/urls/id/delete)
  - [/api/user/urls/{id}/password](/docs/api/api/user/urls/id/password/post): Verify the password for a password-protected short URL by ID, code, or vanity.