Betav1

Warpbin API

Programmatic access to upload, retrieve, and manage files on Warpbin galleries.

“Drive” and “gallery” are the same thing. Galleries were formerly called drives, so field and parameter names keep the drive_ prefix (e.g. drive_id, drive_url) for backwards compatibility. They refer to your gallery throughout this API.

Base URL

All API requests use this base URL. Append the endpoint path to make your calls.

https://warpbin.com/api/v1

How to Use This API

Get an API Key

Reach out to contact@warpbin.com to request your API key. Keys are tied to your account and start with wb_live_.

Find your gallery identifiers

If you already have a gallery, you can find its identifiers in the URLs you already have:

drive_idthe unique identifier for your gallery

warpbin.com/{drive_id}

admin_idthe admin password for your gallery (only needed for certain operations)

warpbin.com/manage/{drive_id}?pd={admin_id}

Create galleries programmatically

Pro

If you have an active Pro subscription on the email associated with your API key, you can use the /createGallery endpoint to create new galleries via the API. The response includes the drive_id and admin_id for immediate use.

Authentication

Include your API key in every request using one of the following headers. You only need to pick one — they are interchangeable.

Pick one header

X-API-Keystring

Your Warpbin API key as-is — wb_live_xxx

Authorizationstring

Bearer token format — Bearer wb_live_xxx

Error responses

401

Missing API key

{
  "error": "API key required",
  "type": "MISSING_API_KEY"
}

401

Invalid API key

{
  "error": "Invalid API key",
  "type": "INVALID_API_KEY"
}

Code example

Authentication

import requests

headers = {'X-API-Key': 'wb_live_xxxxxxxxxxxx'}

# Or use Bearer token
headers = {'Authorization': 'Bearer wb_live_xxxxxxxxxxxx'}

Upload File

POST/v1/uploadFile

Upload a file to a gallery and get instant access URLs. Files are processed asynchronously after upload. The returned URLs will not display the uploaded photo or video until the file is done processing. This can take a couple seconds to minutes depending on the file size.

Form data parameters

file_contentsfilerequired

The file to upload

filenamestringrequired

Filename including extension

drive_idstringrequired

Target gallery identifier

consent_givenboolean

User consent for processing (default: false)

user_idstring

User identifier for tracking

admin_idstring

The gallery's admin password. Required when public uploads are disabled on the gallery.

Response fields

filenameFinal filename after sanitization

file_preview_urlURL to view the file (no API key required)

file_download_urlDirect download URL (requires API key)

Errors

400

Missing required fields

{
  "error": "Missing required field: drive_id",
  "type": "MISSING_FIELD"
}

400

Invalid gallery ID

{
  "error": "Invalid gallery ID",
  "type": "INVALID_DRIVE_ID"
}

507

Storage limit exceeded

{
  "error": "Uploading this file would exceed the gallery's storage limit.",
  "type": "STORAGE_SPACE"
}

Code example

Request

import requests

with open('photo.jpg', 'rb') as f:
    response = requests.post(
        'https://warpbin.com/api/v1/uploadFile',
        headers={'X-API-Key': 'wb_live_xxxxxxxxxxxx'},
        files={'file_contents': f},
        data={
            'filename': 'photo.jpg',
            'drive_id': 'abc123xyz'
        }
    )

result = response.json()
print(result['file_preview_url'])

Response · 202 Accepted

{
  "message": "File upload accepted for processing.",
  "filename": "photo_2.jpg",
  "file_preview_url": "https://warpbin.com/file?id=abc123xyz&file=photo_2.jpg",
  "file_download_url": "https://warpbin.com/api/v1/getFile?id=abc123xyz&file=photo_2.jpg"
}

Retrieve File

GET/v1/getFile?id={drive_id}&file={filename}

Download a file from a gallery. Returns the raw file data with appropriate content-type headers for direct download or display.

This endpoint uses shortened parameter names: id is your drive_id and file is the filename.

Query parameters

idstringrequired

Your drive_id — the gallery to retrieve from

filestringrequired

The filename to retrieve (same as filename in other endpoints)

Errors

400

Missing drive ID

{
  "error": "Missing 'id' parameter",
  "type": "MISSING_PARAMETER"
}

400

Invalid gallery ID

{
  "error": "Invalid gallery ID",
  "type": "INVALID_DRIVE_ID"
}

400

Missing filename

{
  "error": "Missing 'file' parameter",
  "type": "MISSING_PARAMETER"
}

400

Invalid filename

{
  "error": "Invalid filename format",
  "type": "INVALID_FILENAME"
}

403

Access denied

{
  "error": "File not found or access denied",
  "type": "ACCESS_DENIED"
}

404

File not found

{
  "error": "File not found in storage",
  "type": "NOT_FOUND"
}

Code example

Request

import requests

response = requests.get(
    'https://warpbin.com/api/v1/getFile',
    headers={'X-API-Key': 'wb_live_xxxxxxxxxxxx'},
    params={'id': 'abc123xyz', 'file': 'photo.jpg'}
)

with open('photo.jpg', 'wb') as f:
    f.write(response.content)

Response

Returns raw file data with appropriate Content-Type headers.

File Info

GET/v1/fileInfo?drive_id={drive_id}&filename={filename}

Get the preview and download URLs for a file without downloading its content.

Query parameters

drive_idstringrequired

Gallery identifier

filenamestringrequired

Filename to look up

Response fields

filenameFilename as stored on the gallery

file_preview_urlURL to view in Warpbin (no API key required)

file_download_urlDirect download URL (requires API key)

Errors

400

Missing parameters

{
  "error": "Missing 'drive_id' parameter",
  "type": "MISSING_PARAMETER"
}

400

Invalid gallery ID

{
  "error": "Invalid gallery ID",
  "type": "INVALID_DRIVE_ID"
}

400

Missing filename

{
  "error": "Missing 'filename' parameter",
  "type": "MISSING_PARAMETER"
}

404

File not found

{
  "error": "File not found",
  "type": "NOT_FOUND"
}

Code example

Request

import requests

response = requests.get(
    'https://warpbin.com/api/v1/fileInfo',
    headers={'X-API-Key': 'wb_live_xxxxxxxxxxxx'},
    params={'drive_id': 'abc123xyz', 'filename': 'photo.jpg'}
)

info = response.json()
print(info['file_preview_url'])

Response · 200 OK

{
  "filename": "photo.jpg",
  "file_preview_url": "https://warpbin.com/file?id=abc123xyz&file=photo.jpg",
  "file_download_url": "https://warpbin.com/api/v1/getFile?id=abc123xyz&file=photo.jpg"
}

Create Gallery

POST/v1/createGallery

Create a new Warpbin gallery linked to your account. Returns the gallery credentials and URL for immediate use.

The legacy endpoint /v1/createDrive continues to work and is fully equivalent — both names hit the same handler.

Requires an active Pro subscription on the email associated with your API key.

Request body

alt_tenant_urlstring

Custom gallery URL slug that helps you identify it in your dashboard (e.g. "brazil-trip")

Response fields

drive_idUnique drive identifier for API calls

admin_idAdmin password for drive management (the pd value in your manage URL)

drive_urlPublic URL to access the drive

manage_urlManagement panel URL for drive settings

Store credentials securely. The drive_id and admin_id (admin password) are returned at creation time — save them for future API calls. You can also find them later in your manage URL (/manage/{drive_id}?pd={admin_id}) or view all your galleries on your dashboard.

Errors

403

No active subscription

{
  "success": false,
  "drive_id": null,
  "admin_id": null,
  "drive_url": null,
  "manage_url": null,
  "message": "Active Pro subscription required"
}

500

Server error

{
  "success": false,
  "drive_id": null,
  "admin_id": null,
  "drive_url": null,
  "manage_url": null,
  "message": "Failed to create gallery"
}

Code example

Request

import requests

response = requests.post(
    'https://warpbin.com/api/v1/createGallery',
    headers={'X-API-Key': 'wb_live_xxxxxxxxxxxx'},
    json={'alt_tenant_url': 'my-project'}
)

gallery = response.json()
print(gallery['drive_url'])

Response

{
  "success": true,
  "drive_id": "abc123xyz",
  "admin_id": "UxCIkRbY",
  "drive_url": "https://warpbin.com/abc123xyz",
  "manage_url": "https://warpbin.com/manage/abc123xyz?pd=UxCIkRbY",
  "message": "Gallery created successfully"
}

Rate Limits

API requests are subject to a global rate limit to ensure service stability. Excessive requests will receive a 429 Too Many Requests response. This should not be hit for any legitimate use case. Reach out to us if you think we are incorrectly rate limiting you.