Skip to main content

​
Upload File

Upload a file to ClassQuiz storage.

​
Request Body

​
file
file
required
File to upload (multipart/form-data)

​
Authentication

Required

​
Supported File Types

  • Images: image/jpeg, image/png, image/gif, image/webp, image/svg+xml
  • Other allowed MIME types as configured

​
Response

​
id
uuid
Unique file ID
​
uploaded_at
datetime
Upload timestamp
​
mime_type
string
File MIME type
​
hash
string
File content hash (hex)
​
size
integer
File size in bytes
​
alt_text
string
Alt text for accessibility
​
filename
string
Original filename
​
thumbhash
string
Thumbnail hash for blur placeholder

​
Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "uploaded_at": "2024-01-15T10:30:00Z",
  "mime_type": "image/png",
  "hash": "a1b2c3d4...",
  "size": 245678,
  "alt_text": null,
  "filename": null,
  "thumbhash": "abc123...",
  "server": null,
  "imported": false
}

​
Error Codes

  • 422: Unsupported file type
  • 409: Storage limit reached

​
Upload Raw File

Upload raw file data via request body (streaming).

​
Request Body

Raw file bytes streamed in request body.

​
Headers

​
Content-Type
string
required
MIME type of the file

​
Authentication

Required

​
Response

Same as standard file upload endpoint.

​
Download File

Download a file by its name or ID.

​
Path Parameters

​
file_name
string
required
File name or UUID with optional user ID (format: uuid--user-uuid)

​
Response

Returns file stream with appropriate headers:
  • Content-Type: File MIME type
  • Cache-Control: public, immutable, max-age=31536000
  • X-Hash: File content hash
  • X-Thumbhash: Thumbnail hash
  • X-Alt-Text: Base64-encoded alt text
  • Content-Size: File size in bytes

​
S3 Backend

If using S3 storage, returns a redirect (302) to a signed URL valid for 300 seconds.

​
Get File Info

Get file metadata without downloading the file.

​
Path Parameters

​
file_name
string
required
File name or UUID

​
Response

Returns HTTP 200 with headers containing file metadata (same as download endpoint).

​
File Metadata (HEAD)

Get file metadata using HEAD request.

​
Path Parameters

​
file_name
string
required
File name or UUID

​
Response

Returns headers only, no body. For S3 storage, returns 307 redirect.

​
Get File Metadata

Get detailed metadata for a file.

​
Path Parameters

​
file_id
uuid
required
File UUID

​
Authentication

Required - Must be file owner

​
Response

Returns public storage item object (see Upload File response).

​
Update File Metadata

Update file metadata (alt text, filename).

​
Path Parameters

​
file_id
uuid
required
File UUID

​
Request Body

​
alt_text
string
Accessibility alt text (empty string to remove)
​
filename
string
Display filename (empty string to remove)

​
Authentication

Required - Must be file owner

​
Example Request

{
  "alt_text": "A beautiful sunset over the ocean",
  "filename": "sunset.jpg"
}

​
Delete File

Mark a file as deleted (soft delete).

​
Path Parameters

​
file_id
uuid
required
File UUID

​
Authentication

Required - Must be file owner

​
Response

Returns HTTP 200. File is marked with deleted_at timestamp and removed from storage backend.

​
List Files

List user’s uploaded files.

​
Query Parameters

​
since
datetime
Only return files uploaded after this date (default: 9999 weeks ago)

​
Authentication

Required

​
Response

Array of private storage items:
​
id
uuid
File ID
​
uploaded_at
datetime
Upload timestamp
​
mime_type
string
File MIME type
​
size
integer
File size in bytes
​
quizzes
array
Array of quiz IDs using this file
​
quiztivities
array
Array of quiztivity IDs using this file

​
Example Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "uploaded_at": "2024-01-15T10:30:00Z",
    "mime_type": "image/png",
    "size": 245678,
    "quizzes": [
      {"id": "quiz-uuid-1"},
      {"id": "quiz-uuid-2"}
    ],
    "quiztivities": []
  }
]

​
Get Latest Files

Get the most recently uploaded files.

​
Query Parameters

​
count
integer
default:"50"
Number of files to return (max 50)

​
Authentication

Required

​
Response

Array of private storage items (same format as List Files).

​
Get Storage Limit

Get user’s storage usage and limit information.

​
Authentication

Required

​
Response

​
limit
integer
Storage limit in bytes
​
limit_reached
boolean
Whether storage limit has been exceeded
​
used
integer
Storage used in bytes

​
Example Response

{
  "limit": 104857600,
  "limit_reached": false,
  "used": 45678901
}

​
Storage Best Practices

​
File Naming

Files are stored with UUID-based names. The system supports two formats:
  1. Simple UUID: 123e4567-e89b-12d3-a456-426614174000
  2. UUID with user: file-uuid--user-uuid

​
Caching

Files are served with aggressive caching headers (max-age=31536000). Files are immutable once uploaded.

​
Deduplication

The system calculates file hashes asynchronously. Identical files can be deduplicated based on content hash.

​
ThumbHash

Images are processed to generate ThumbHash - a compact representation for blur placeholders while the image loads.

​
Storage Backends

ClassQuiz supports multiple storage backends:
  • Local filesystem: Files served directly
  • S3-compatible: Returns signed URLs for direct access

Build docs developers (and LLMs) love

Get started for freeTalk to us