Referensi REST API

Endpoint Penyimpanan (Storage)

Spesifikasi endpoint HTTP langsung untuk unggahan presigned langsung, CRUD File lengkap, CRUD Folder Virtual, dan penelusuran direktori aset.

POST

/api/storage/presign

Menghasilkan URL PUT presigned dengan batas waktu dan r2Key yang rapi, memungkinkan klien mengalirkan biner langsung ke penyimpanan Cloudizero.

Request

curl -X POST https://api.cloudizero.com/api/storage/presign \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_LXAlEW70v24YSc0y",
    "fileName": "avatar.png",
    "mimeType": "image/png",
    "fileSize": 1048576,
    "folderId": null
  }'

Response (200 OK)

{
  "uploadUrl": "https://api.cloudizero.com/api/storage/upload?token=...",
  "storageKey": "username/project-slug/avatar.png",
  "r2Key": "username/project-slug/avatar.png",
  "fileId": "fil_tsvSl4yYKEOlO4KN",
  "finalFileName": "avatar.png"
}

POST

/api/storage/complete

Mendaftarkan aset yang berhasil diunggah ke basis data relasional Cloudizero setelah klien selesai mengalirkan data ke penyimpanan objek.

Request

curl -X POST https://api.cloudizero.com/api/storage/complete \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "fil_tsvSl4yYKEOlO4KN",
    "projectId": "prj_LXAlEW70v24YSc0y",
    "folderId": null,
    "name": "avatar.png",
    "mimeType": "image/png",
    "size": 1048576,
    "storageKey": "username/project-slug/avatar.png"
  }'

POST

/api/storage/multipart/*

Siklus hidup unggahan multipart paralel untuk file berukuran besar hingga 50 GB: inisialisasi uploadId, presign chunk parts, selesaikan upload, atau batalkan upload.

1. Inisialisasi: POST /api/storage/multipart/initiate

Initiate Request

curl -X POST https://api.cloudizero.com/api/storage/multipart/initiate \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_LXAlEW70v24YSc0y",
    "fileName": "large-video.mp4",
    "mimeType": "video/mp4",
    "fileSize": 1073741824,
    "folderId": null
  }'

Initiate Response (201 Created)

{
  "uploadId": "mp_9f8ab2e4b830d9...",
  "fileId": "fil_tsvSl4yYKEOlO4KN",
  "r2Key": "usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/large-video.mp4",
  "finalFileName": "large-video.mp4",
  "partSize": 10485760,
  "totalParts": 103,
  "cacheControl": "public, max-age=31536000, immutable"
}

2. Presign Parts: POST /api/storage/multipart/presign-parts

Presign Parts Request

curl -X POST https://api.cloudizero.com/api/storage/multipart/presign-parts \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "fil_tsvSl4yYKEOlO4KN",
    "uploadId": "mp_9f8ab2e4b830d9...",
    "partNumbers": [1, 2, 3]
  }'

Presign Parts Response (200 OK)

{
  "presignedUrls": {
    "1": "https://api.cloudizero.com/api/storage/upload?part=1&token=...",
    "2": "https://api.cloudizero.com/api/storage/upload?part=2&token=...",
    "3": "https://api.cloudizero.com/api/storage/upload?part=3&token=..."
  }
}

3. Selesaikan: POST /api/storage/multipart/complete

Complete Request

curl -X POST https://api.cloudizero.com/api/storage/multipart/complete \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "fil_tsvSl4yYKEOlO4KN",
    "uploadId": "mp_9f8ab2e4b830d9...",
    "parts": [
      { "PartNumber": 1, "ETag": "9b2cf52...01" },
      { "PartNumber": 2, "ETag": "7a3be41...02" }
    ],
    "projectId": "prj_LXAlEW70v24YSc0y",
    "name": "large-video.mp4",
    "mimeType": "video/mp4",
    "size": 1073741824
  }'

Complete Response (200 OK)

{
  "file": {
    "id": "fil_tsvSl4yYKEOlO4KN",
    "name": "large-video.mp4",
    "size": 1073741824,
    "mimeType": "video/mp4",
    "processingStatus": "ready",
    "r2Key": "usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/large-video.mp4"
  }
}

4. Batalkan: POST /api/storage/multipart/abort

Abort Request

curl -X POST https://api.cloudizero.com/api/storage/multipart/abort \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "fil_tsvSl4yYKEOlO4KN",
    "uploadId": "mp_9f8ab2e4b830d9..."
  }'

GET

/api/storage/contents

Mengambil semua file, folder virtual, dan jejak breadcrumbs untuk projectId dan folderId yang ditentukan.

Request

curl -X GET "https://api.cloudizero.com/api/storage/contents?projectId=prj_LXAlEW70v24YSc0y&folderId=root" \
  -H "Authorization: Bearer cz_live_..."

GETPATCHDELETE

/api/storage/files

Membaca metadata file & URL unduhan presigned, memperbarui metadata file (ubah nama/pindah folder di penyimpanan objek atau meminta URL PUT penggantian biner), atau menghapus aset secara permanen.

File CRUD Requests

# 1. Ambil Metadata File & URL Unduhan Presigned
curl -X GET "https://api.cloudizero.com/api/storage/files?fileId=fil_tsvSl4yY..." \
  -H "Authorization: Bearer cz_live_..."

# 2. Update Metadata File (Ubah Nama / Pindah Folder / Minta URL Timpa Biner)
curl -X PATCH https://api.cloudizero.com/api/storage/files \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "fil_tsvSl4yY...",
    "name": "avatar-v2.png",
    "folderId": "fld_ARaZjwdP...",
    "requestReplaceUploadUrl": false
  }'

# 3. Hapus File Permanen (Storage + Database)
curl -X DELETE "https://api.cloudizero.com/api/storage/files?fileId=fil_tsvSl4yY..." \
  -H "Authorization: Bearer cz_live_..."

POSTGETPATCHDELETE

/api/storage/folders

Operasi CRUD penuh untuk folder virtual, termasuk sinkronisasi jalur rekursif & storage key saat ubah nama/pindah folder serta pembersihan objek penyimpanan secara rekursif saat dihapus.

Folder CRUD Requests

# 1. Buat Folder Virtual
curl -X POST https://api.cloudizero.com/api/storage/folders \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_LXAlEW70v24YSc0y",
    "name": "Banner Pemasaran",
    "parentId": null
  }'

# 2. Ambil Folder Tunggal atau Daftar Folder Proyek
curl -X GET "https://api.cloudizero.com/api/storage/folders?projectId=prj_LXAlEW70v24YSc0y&parentId=root" \
  -H "Authorization: Bearer cz_live_..."

# 3. Ubah Nama atau Pindahkan Folder (Otomatis Sinkronisasi Path Subfolder & Storage Key)
curl -X PATCH https://api.cloudizero.com/api/storage/folders \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "fld_ARaZjwdP...",
    "name": "Aset Brand",
    "parentId": null
  }'

# 4. Hapus Folder Rekursif (Menghapus Subfolder & Objek Penyimpanan di dalamnya)
curl -X DELETE "https://api.cloudizero.com/api/storage/folders?folderId=fld_ARaZjwdP..." \
  -H "Authorization: Bearer cz_live_..."

POSTGET

/api/storage/files/[fileId]/pages

Ekstraksi asinkron halaman dokumen PDF ke gambar WebP beresolusi tinggi, pembuatan thumbnail sampul, dan pengambilan daftar halaman serta bab navigasi via CDN bebas egress.

PDF Extraction & Pages Requests

# 1. Ekstraksi Halaman PDF (Asinkron)
curl -X POST "https://api.cloudizero.com/api/storage/files/fil_tsvSl4yYKEOlO4KN/extract" \
  -H "Authorization: Bearer cz_live_..."

# 2. Ambil Halaman Dokumen, Thumbnail & Daftar Bab
curl -X GET "https://api.cloudizero.com/api/storage/files/fil_tsvSl4yYKEOlO4KN/pages" \
  -H "Authorization: Bearer cz_live_..."

Response (200 OK)

{
  "fileId": "fil_tsvSl4yYKEOlO4KN",
  "fileName": "handbook.pdf",
  "mimeType": "application/pdf",
  "processingStatus": "ready",
  "pageCount": 12,
  "thumbnailUrl": "https://cdn.cloudizero.com/user/project/handbook-thumb.webp",
  "chapters": [
    { "title": "Introduction", "page": 1, "level": 1 }
  ],
  "pages": [
    {
      "pageNumber": 1,
      "url": "https://cdn.cloudizero.com/user/project/pages/handbook-p1.webp",
      "width": 1200,
      "height": 1600,
      "size": 184320
    }
  ]
}

GET

/api/storage/search

Pencarian multimodal hibrida menggabungkan pemindaian semantik berbasis vektor 768 dimensi dan pencocokan teks presisi di seluruh aset proyek Cloudizero.

Search Request

curl -X GET "https://api.cloudizero.com/api/storage/search?projectId=prj_LXAlEW70v24YSc0y&q=sunset+over+the+beach" \
  -H "Authorization: Bearer cz_live_..."

Response (200 OK)

{
  "results": [
    {
      "id": "fil_tsvSl4yYKEOlO4KN",
      "projectId": "prj_LXAlEW70v24YSc0y",
      "name": "beach-sunset.webp",
      "mimeType": "image/webp",
      "size": 458290,
      "similarityScore": 0.892,
      "matchType": "hybrid",
      "altText": "Golden sunset glowing over tropical palm trees on a tranquil sandy beach",
      "aiMetadata": {
        "tags": ["beach", "sunset", "tropical", "nature"],
        "description": "Vibrant dusk colors reflecting on calm ocean waters with silhouette palms."
      }
    }
  ],
  "query": "sunset over the beach",
  "mode": "hybrid",
  "totalCount": 1
}

POST

/api/storage/files/[fileId]/ai-describe

Analisis visual aset gambar berbasis model AI vision untuk menghasilkan teks alternatif aksesibilitas WCAG, tag SEO, deskripsi visual, dan palet warna dominan secara otomatis.

AI Describe Request

curl -X POST "https://api.cloudizero.com/api/storage/files/fil_tsvSl4yYKEOlO4KN/ai-describe" \
  -H "Authorization: Bearer cz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "en",
    "force": false
  }'

Response (200 OK)

{
  "success": true,
  "altText": "A sleek modern laptop workstation on a wooden minimalist desk with soft morning daylight.",
  "aiMetadata": {
    "altText": "A sleek modern laptop workstation on a wooden minimalist desk with soft morning daylight.",
    "tags": ["laptop", "workspace", "minimalist", "tech", "productivity"],
    "description": "Clean desktop setup featuring an open notebook computer and ambient lighting.",
    "dominantColors": ["#1E293B", "#F8FAFC", "#94A3B8"],
    "generatedAt": "2026-10-21T12:00:00.000Z",
    "locale": "en"
  }
}