Endpoints
| Method | Path | Scope | Description |
|---|
POST | /media/presign | media:write | Get a presigned upload URL |
POST | /media/confirm | media:write | Confirm a completed upload |
Upload Flow
Uploading media to clarife is a three-step process:
Get a presigned URL
Call /media/presign with the file details. You receive a time-limited upload URL and a b2_key.
Upload the file
PUT the file directly to the presigned URL. This uploads to clarife’s storage without proxying through the API.
Confirm the upload
Call /media/confirm with the media_id to mark the file as active.
Step 1: Get a Presigned URL
curl -X POST https://my.clarife.app/api/v1/media/presign \
-H "Authorization: Bearer clrf_your_key" \
-H "Content-Type: application/json" \
-d '{
"document_id": "d1234567-...",
"media_id": "m1234567-...",
"filename": "step-3-screenshot.png",
"mime_type": "image/png",
"file_size_bytes": 245760
}'
| Field | Type | Required | Description |
|---|
document_id | uuid | Yes | Document to attach the media to |
media_id | uuid | Yes | Client-generated UUID for the media |
filename | string | Yes | Original filename (max 255 chars) |
mime_type | string | Yes | MIME type (see supported types below) |
file_size_bytes | integer | Yes | File size in bytes |
| Type | Extension |
|---|
image/png | .png |
image/jpeg | .jpg |
image/gif | .gif |
image/webp | .webp |
image/svg+xml | .svg |
image/bmp | .bmp |
image/tiff | .tiff |
{
"upload_url": "https://s3.us-west-004.backblazeb2.com/...",
"b2_key": "media/user-id/doc-id/media-id.png",
"media_id": "m1234567-..."
}
Maximum file size is 30 MB. The presigned URL expires after 15 minutes.
Step 2: Upload the File
Upload the file directly to the presigned URL using a PUT request:
curl -X PUT "https://s3.us-west-004.backblazeb2.com/..." \
-H "Content-Type: image/png" \
--data-binary @step-3-screenshot.png
Step 3: Confirm the Upload
curl -X POST https://my.clarife.app/api/v1/media/confirm \
-H "Authorization: Bearer clrf_your_key" \
-H "Content-Type: application/json" \
-d '{ "media_id": "m1234567-..." }'
{
"id": "m1234567-...",
"status": "active"
}
Complete Example
# 1. Get presigned URL
RESPONSE=$(curl -s -X POST https://my.clarife.app/api/v1/media/presign \
-H "Authorization: Bearer clrf_your_key" \
-H "Content-Type: application/json" \
-d '{
"document_id": "d1234567-...",
"media_id": "'$(uuidgen | tr A-Z a-z)'",
"filename": "screenshot.png",
"mime_type": "image/png",
"file_size_bytes": '$(stat -f%z screenshot.png)'
}')
UPLOAD_URL=$(echo $RESPONSE | jq -r '.upload_url')
MEDIA_ID=$(echo $RESPONSE | jq -r '.media_id')
# 2. Upload file to presigned URL
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/png" \
--data-binary @screenshot.png
# 3. Confirm the upload
curl -X POST https://my.clarife.app/api/v1/media/confirm \
-H "Authorization: Bearer clrf_your_key" \
-H "Content-Type: application/json" \
-d "{\"media_id\":\"$MEDIA_ID\"}"
Storage Limits
| Plan | Storage limit |
|---|
| Free | 100 MB |
| Pro | 10 GB |
| Business | 100 GB |
403 error with code PLAN_LIMIT_REACHED.
Uploads that are not confirmed within 24 hours are automatically cleaned up.
