Skip to main content
Integrate Zipline into your applications using the REST API or community-built libraries. This guide covers authentication, basic usage, and available client libraries.

​
Authentication

All API requests require authentication using your API token. You can obtain your token from the Zipline dashboard.

​
Getting Your API Token

1

Log in to Zipline

Navigate to your Zipline instance and log in.
2

Access Settings

Go to Settings → User → API Token.
3

Copy or Regenerate Token

View your existing token or generate a new one if needed.
Keep your API token secure. Anyone with your token can upload files and manage your content. Never commit tokens to version control.

​
Using the Token

Include your token in the Authorization header: 
Authorization: your-api-token-here

​
Quick Start Examples

​
cURL

The simplest way to interact with Zipline’s API: 
curl -X POST https://your-zipline-instance.com/api/upload \
  -H "Authorization: your-api-token" \
  -F "file=@/path/to/file.png"

​
JavaScript/TypeScript

Using fetch API: 
const ZIPLINE_URL = 'https://your-zipline-instance.com';
const API_TOKEN = 'your-api-token';

// Upload a file
async function uploadFile(file: File) {
  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch(`${ZIPLINE_URL}/api/upload`, {
    method: 'POST',
    headers: {
      'Authorization': API_TOKEN,
    },
    body: formData,
  });

  const data = await response.json();
  return data.files[0].url;
}

// Create short URL
async function shortenUrl(destination: string) {
  const response = await fetch(`${ZIPLINE_URL}/api/user/urls`, {
    method: 'POST',
    headers: {
      'Authorization': API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ destination }),
  });

  const data = await response.json();
  return data.url;
}

// List user files
async function listFiles() {
  const response = await fetch(`${ZIPLINE_URL}/api/user/files`, {
    headers: {
      'Authorization': API_TOKEN,
    },
  });

  return await response.json();
}

​
Python

Using requests library: 
import requests

ZIPLINE_URL = 'https://your-zipline-instance.com'
API_TOKEN = 'your-api-token'

headers = {
    'Authorization': API_TOKEN
}

# Upload a file
def upload_file(file_path):
    with open(file_path, 'rb') as f:
        files = {'file': f}
        response = requests.post(
            f'{ZIPLINE_URL}/api/upload',
            headers=headers,
            files=files
        )
    return response.json()['files'][0]['url']

# Create short URL
def shorten_url(destination):
    response = requests.post(
        f'{ZIPLINE_URL}/api/user/urls',
        headers={**headers, 'Content-Type': 'application/json'},
        json={'destination': destination}
    )
    return response.json()['url']

# List files
def list_files():
    response = requests.get(
        f'{ZIPLINE_URL}/api/user/files',
        headers=headers
    )
    return response.json()

# Delete file
def delete_file(file_id):
    response = requests.delete(
        f'{ZIPLINE_URL}/api/user/files/{file_id}',
        headers=headers
    )
    return response.status_code == 204

​
Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

const (
    ziplineURL = "https://your-zipline-instance.com"
    apiToken   = "your-api-token"
)

// Upload a file
func uploadFile(filePath string) (string, error) {
    file, err := os.Open(filePath)
    if err != nil {
        return "", err
    }
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, err := writer.CreateFormFile("file", filePath)
    if err != nil {
        return "", err
    }
    io.Copy(part, file)
    writer.Close()

    req, err := http.NewRequest("POST", ziplineURL+"/api/upload", body)
    if err != nil {
        return "", err
    }
    req.Header.Set("Authorization", apiToken)
    req.Header.Set("Content-Type", writer.FormDataContentType())

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result struct {
        Files []struct {
            URL string `json:"url"`
        } `json:"files"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    return result.Files[0].URL, nil
}

// Create short URL
func shortenURL(destination string) (string, error) {
    payload := map[string]string{"destination": destination}
    jsonData, _ := json.Marshal(payload)

    req, err := http.NewRequest("POST", ziplineURL+"/api/user/urls", bytes.NewBuffer(jsonData))
    if err != nil {
        return "", err
    }
    req.Header.Set("Authorization", apiToken)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result struct {
        URL string `json:"url"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    return result.URL, nil
}

​
Advanced Upload Options

Customize your uploads using custom headers:

​
Upload with Expiration

curl -X POST https://your-zipline-instance.com/api/upload \
  -H "Authorization: your-api-token" \
  -H "X-Zipline-Deletes-At: 24h" \
  -F "[email protected]"

​
Image Compression

curl -X POST https://your-zipline-instance.com/api/upload \
  -H "Authorization: your-api-token" \
  -H "X-Zipline-Image-Compression-Percent: 80" \
  -F "[email protected]"

​
Custom Filename Format

curl -X POST https://your-zipline-instance.com/api/upload \
  -H "Authorization: your-api-token" \
  -H "X-Zipline-Format: uuid" \
  -F "[email protected]"

​
Password Protection

curl -X POST https://your-zipline-instance.com/api/upload \
  -H "Authorization: your-api-token" \
  -H "X-Zipline-Password: secret123" \
  -F "[email protected]"

​
Available Headers

HeaderTypeDescription
X-Zipline-Deletes-AtstringExpiration time (24h, 7d, never, date=2024-12-31)
X-Zipline-FormatstringFilename format (random, uuid, date, name, gfycat)
X-Zipline-Image-Compression-PercentnumberCompression quality (0-100)
X-Zipline-Image-Compression-TypestringCompression format (webp, jpeg, png)
X-Zipline-PasswordstringPassword protect the file
X-Zipline-Max-ViewsnumberMaximum views before deletion
X-Zipline-Original-NamebooleanKeep original filename (true/false)
X-Zipline-No-JSONbooleanReturn plain text URL
X-Zipline-DomainstringCustom return domain
X-Zipline-FolderstringUpload to specific folder (folder ID)

​
Response Formats

​
Successful Upload

{
  "files": [
    {
      "id": "abc123",
      "name": "xyz789.png",
      "type": "image/png",
      "url": "https://your-zipline-instance.com/xyz789.png",
      "removedGps": false
    }
  ],
  "deletesAt": "2024-03-04T22:36:00.000Z"
}

​
Error Response

{
  "error": "Unauthorized",
  "message": "Invalid authorization token",
  "statusCode": 401
}

​
Rate Limiting

Zipline implements rate limiting to prevent abuse. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.
Implement exponential backoff in your client to handle rate limiting gracefully.

​
Error Handling

Always handle errors appropriately in your client: 
async function uploadFile(file: File) {
  try {
    const formData = new FormData();
    formData.append('file', file);

    const response = await fetch(`${ZIPLINE_URL}/api/upload`, {
      method: 'POST',
      headers: { 'Authorization': API_TOKEN },
      body: formData,
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'Upload failed');
    }

    const data = await response.json();
    return data.files[0].url;
  } catch (error) {
    console.error('Upload error:', error);
    throw error;
  }
}

​
Community Libraries

These are community-maintained libraries. Check their documentation for usage instructions and support.
If you’ve created a library for Zipline, please contribute it to the ecosystem!

​
Next Steps

API Reference

Explore the complete API documentation

Upload API

Detailed upload endpoint documentation

ShareX Integration

Set up ShareX for Windows

Flameshot Integration

Configure Flameshot for Linux

Build docs developers (and LLMs) love

Get started for freeTalk to us