Files¶

Files are binary blobs stored in lake-scale object storage. Images, video, audio, PDFs — anything.

You upload a file. You get back a UUID. You store that UUID in a table column. That's the join key between your SQL rows and your binary assets.

All file operations use the REST endpoint:

/workspaces/{workspace}/files

Setup¶

import requests

API_URL = "https://api.deeplake.ai"
TOKEN = "YOUR_TOKEN"
WORKSPACE = "YOUR_WORKSPACE"

auth_headers = {"Authorization": f"Bearer {TOKEN}"}

Upload a file¶

Use multipart form-data. Do not send Content-Type: application/json.

with open("photo.png", "rb") as f:
    res = requests.post(
        f"{API_URL}/workspaces/{WORKSPACE}/files",
        headers=auth_headers,
        files={"file": ("photo.png", f, "image/png")},
    )

file_id = res.json()["id"]
print(file_id)  # "a1b2c3d4-e5f6-..."

Upload from memory¶

import io
from PIL import Image

img = Image.new("RGB", (256, 256), color=(40, 80, 200))
buf = io.BytesIO()
img.save(buf, format="PNG")

res = requests.post(
    f"{API_URL}/workspaces/{WORKSPACE}/files",
    headers=auth_headers,
    files={"file": ("generated.png", buf.getvalue(), "image/png")},
)
file_id = res.json()["id"]

Upload video¶

with open("clip.mp4", "rb") as f:
    res = requests.post(
        f"{API_URL}/workspaces/{WORKSPACE}/files",
        headers=auth_headers,
        files={"file": ("clip.mp4", f, "video/mp4")},
        timeout=120,
    )
file_id = res.json()["id"]

Download a file¶

res = requests.get(
    f"{API_URL}/workspaces/{WORKSPACE}/files/{file_id}/content",
    headers=auth_headers,
)

with open("downloaded.png", "wb") as f:
    f.write(res.content)

Get file info¶

res = requests.get(
    f"{API_URL}/workspaces/{WORKSPACE}/files/{file_id}",
    headers=auth_headers,
)
print(res.json())  # metadata, size, content type, etc.

List files¶

res = requests.get(
    f"{API_URL}/workspaces/{WORKSPACE}/files?limit=20&offset=0",
    headers=auth_headers,
)
print(res.json())

Delete a file¶

requests.delete(
    f"{API_URL}/workspaces/{WORKSPACE}/files/{file_id}",
    headers=auth_headers,
)

Link files to tables¶

The file_id UUID is your join key. Store it in a UUID column:

TABLE = "my_images"

# 1. Upload
res = requests.post(
    f"{API_URL}/workspaces/{WORKSPACE}/files",
    headers=auth_headers,
    files={"file": ("photo.png", img_bytes, "image/png")},
)
file_id = res.json()["id"]

# 2. Insert into table (schema-qualified with workspace)
requests.post(
    f"{API_URL}/workspaces/{WORKSPACE}/tables/query",
    headers={**auth_headers, "Content-Type": "application/json"},
    json={
        "query": f"""
            INSERT INTO "{WORKSPACE}"."{TABLE}" (title, file_id)
            VALUES ('Beach sunset', '{file_id}'::uuid)
        """
    },
)

Now you can query the table and use the file_id to download the original file or render it in the frontend.

Common MIME types¶

File type	MIME type
PNG	`image/png`
JPEG	`image/jpeg`
MP4	`video/mp4`
PDF	`application/pdf`
WAV	`audio/wav`
JSON	`application/json`