Uploads¶
The Konigle SDK provides comprehensive support for managing file uploads - general purpose private file uploads that represent temporary uploads for files in the Konigle platform. These differ from media assets as they are not used directly in the site but contribute to site storage. All upload operations support both synchronous and asynchronous clients with consistent APIs.
Creating Uploads¶
The SDK supports various ways to create uploads:
From File Path¶
import konigle
from konigle.models.core.upload import UploadCreate
client = konigle.Client(api_key="your-api-key")
# Create an upload from a file path
upload_data = UploadCreate(
name="user-document",
tags="user,document,important",
file="/path/to/document.pdf"
)
upload = client.uploads.create(upload_data)
print(f"Created upload: {upload.id}")
print(f"File URL: {upload.url}")
print(f"Status: {upload.status}")
From Bytes¶
# Read file as bytes
with open("/path/to/document.pdf", "rb") as f:
file_bytes = f.read()
upload_data = UploadCreate(
name="attachment",
tags="email,attachment",
file=file_bytes
)
upload = client.uploads.create(upload_data)
From BytesIO¶
import io
# Create upload from BytesIO (useful for generated files)
file_buffer = io.BytesIO()
# ... write data to buffer ...
file_buffer.seek(0)
upload_data = UploadCreate(
name="generated-report",
tags="generated,report",
file=(file_buffer, "report.pdf") # Tuple with filename
)
upload = client.uploads.create(upload_data)
Listing Uploads¶
# List all uploads with pagination
uploads = client.uploads.list(page=1, page_size=20)
print(f"Total uploads: {uploads.count}")
print(f"Current page: {uploads.current_page}")
print(f"Total pages: {uploads.num_pages}")
for upload in uploads.payload:
print(f"- {upload.name} ({upload.id})")
print(f" Size: {upload.size} bytes")
print(f" MIME type: {upload.mime_type}")
print(f" Status: {upload.status}")
print(f" URL: {upload.url}")
print(f" Created: {upload.created_at}")
# Check if there are more pages
if uploads.has_next():
next_page = client.uploads.list(page=2, page_size=20)
Getting a Specific Upload¶
# Get upload by ID
upload = client.uploads.get("upload_123456789")
print(f"Upload: {upload.name}")
print(f"MIME type: {upload.mime_type}")
print(f"Size: {upload.size} bytes")
print(f"Status: {upload.status}")
print(f"Tags: {upload.tags}")
print(f"Storage path: {upload.storage_path}")
print(f"ETag: {upload.etag}")
Deleting Uploads¶
# Delete an upload
success = client.uploads.delete("upload_123456789")
if success:
print("Upload deleted successfully")
else:
print("Failed to delete upload")
Cloud Upload Workflow¶
For large files or direct browser uploads, use the cloud upload workflow:
Creating a Presigned Upload URL¶
# Create a presigned upload URL for direct to cloud upload
upload_info = client.uploads.create_cloud_upload(
mime_type="application/pdf",
file_size=1024000, # File size in bytes
filename="large-document.pdf",
name="Large Document" # Optional display name
)
print("Upload info:")
for key, value in upload_info.items():
print(f" {key}: {value}")
# The response typically contains:
# - upload_id: The upload ID to reference later
# - upload_url: Presigned URL for uploading
# - form_data: Additional form fields required for upload
Managing Upload Status¶
upload_id = "upload_123456789"
# Mark upload as started (when client begins upload)
upload = client.uploads.mark_started(upload_id)
print(f"Upload status: {upload.status}") # "uploading"
# Mark upload as completed (when client finishes upload)
upload = client.uploads.mark_completed(upload_id)
print(f"Upload status: {upload.status}") # "completed"
# Mark upload as failed (if upload fails)
upload = client.uploads.mark_failed(upload_id)
print(f"Upload status: {upload.status}") # "failed"
Complete Cloud Upload Example¶
import konigle
client = konigle.Client(api_key="your-api-key")
# Step 1: Create presigned upload URL
upload_info = client.uploads.create_cloud_upload(
mime_type="application/pdf",
file_size=5000000, # 5MB
filename="report.pdf",
name="Monthly Report"
)
upload_id = upload_info["upload_id"]
upload_url = upload_info["upload_url"]
print(f"Upload ID: {upload_id}")
print(f"Upload URL: {upload_url}")
# Step 2: Mark as started before uploading
client.uploads.mark_started(upload_id)
# Step 3: Perform the actual upload to cloud storage
# (This would typically be done by frontend/client)
# ... upload file to upload_url using form data ...
# Step 4: Mark as completed after successful upload
completed_upload = client.uploads.mark_completed(upload_id)
print(f"Upload completed: {completed_upload.status}")
# Or mark as failed if upload fails
# failed_upload = client.uploads.mark_failed(upload_id)
Async Operations¶
import asyncio
import konigle
async def manage_uploads():
async with konigle.AsyncClient(api_key="your-api-key") as client:
# Create upload
upload_data = UploadCreate(
name="async-upload",
tags="async,example",
file="/path/to/document.pdf"
)
upload = await client.uploads.create(upload_data)
print(f"Created upload: {upload.id}")
# List uploads
uploads = await client.uploads.list(page_size=10)
print(f"Found {uploads.count} uploads")
# Get specific upload
retrieved_upload = await client.uploads.get(upload.id)
print(f"Retrieved: {retrieved_upload.name}")
# Cloud upload workflow
upload_info = await client.uploads.create_cloud_upload(
mime_type="text/plain",
file_size=1024,
filename="async-file.txt"
)
cloud_upload_id = upload_info["upload_id"]
# Mark as started
await client.uploads.mark_started(cloud_upload_id)
# Mark as completed
completed = await client.uploads.mark_completed(cloud_upload_id)
print(f"Cloud upload status: {completed.status}")
# Delete uploads
await client.uploads.delete(upload.id)
await client.uploads.delete(cloud_upload_id)
asyncio.run(manage_uploads())
CLI Commands¶
The Konigle SDK provides command-line interface commands for managing uploads.
Creating Uploads¶
# Create upload from a file
konigle uploads create --file /path/to/document.pdf --name "My Document" --tags "important,user"
# Create upload with minimal options
konigle uploads create --file /path/to/image.png
# Create upload without name (will use filename)
konigle uploads create --file /path/to/spreadsheet.csv --tags "data,analysis"
Listing Uploads¶
# List uploads with default pagination (page 1, 10 items)
konigle uploads list
# List uploads with custom pagination
konigle uploads list --page 2 --page-size 20
# List uploads with pagination shortcuts
konigle uploads list -p 1 -s 5
Getting Upload Details¶
Deleting Uploads¶
# Delete upload with confirmation prompt
konigle uploads delete upload_123456789
# Delete upload without confirmation
konigle uploads delete upload_123456789 --yes
konigle uploads delete upload_123456789 -y
Cloud Upload Commands¶
Create Presigned Upload URL¶
# Create cloud upload URL for a PDF file
konigle uploads create-cloud-upload \
--mime-type "application/pdf" \
--file-size 5000000 \
--filename "large-document.pdf" \
--name "Large Document"
# Create cloud upload URL with short options
konigle uploads create-cloud-upload \
-m "image/png" \
-s 2048000 \
-f "image.png" \
-n "Product Image"
# Create cloud upload URL without display name
konigle uploads create-cloud-upload \
--mime-type "text/csv" \
--file-size 1024000 \
--filename "data.csv"
Manage Upload Status¶
# Mark upload as started
konigle uploads mark-started upload_123456789
# Mark upload as completed
konigle uploads mark-completed upload_123456789
# Mark upload as failed
konigle uploads mark-failed upload_123456789
Supported File Formats¶
The SDK supports the following file formats for uploads:
- Documents: PDF (
.pdf), CSV (.csv), Text (.txt), Word (.docx,.doc), Excel (.xlsx,.xls) - Images: PNG (
.png), JPEG (.jpg,.jpeg), GIF (.gif), WebP (.webp), SVG (.svg) - Archives: ZIP (
.zip)
Upload Limits¶
- Maximum file size: 500 MB
- Recommended for cloud uploads: Files larger than 20 MB should use the cloud upload workflow with presigned URLs