Storage Platform

The d1v storage platform is a tenant-scoped file service at storage.d1v.ai. It provides:

• folder-tree organization
• file metadata, downloads, previews, and movement
• single-part and multipart direct-to-storage uploads
• trash recovery and permanent deletion
• explicitly public file access
• storage usage summaries and team administration

The interactive Storage API reference contains the complete OpenAPI schemas and request examples.

Every request is evaluated in the current workspace (tenant). A user can belong to multiple workspaces and can switch the active one with POST /api/auth/current-tenant.

Keep the tenant ID with the rest of your session state. Never assume that a file ID from one workspace is visible in another workspace.

For a browser or first-time setup, use passwordless email authentication:

1. 1
   POST /api/auth/send-code with { "email": "user@example.com" }.
2. 2
   POST /api/auth/verify-login with the six-digit code.
3. 3
   Store the returned JWT securely. Browser clients can restore the cookie through POST /api/auth/sync-cookie.

   For scripts and services, create a named API key from the d1v Settings page and send it as Authorization: Bearer <token>.

   Use separate keys for local development, preview automation, and production. Revoke keys that are no longer needed.

Folders are managed with GET /api/folders, POST /api/folders, PATCH /api/folders/{folderId}, and DELETE /api/folders/{folderId}.

Use GET /api/files for the file list and GET /api/files/{fileId} for one file. File metadata can be updated or moved without re-uploading the bytes:

• PATCH /api/files/{fileId} updates metadata or visibility.
• POST /api/files/{fileId}/move changes the folder.
• POST /api/files/{fileId}/download creates a download response.
• GET /api/files/{fileId}/preview serves a preview when the file type is supported.

Treat metadata and file bytes as separate concerns. A successful metadata update does not mean a new upload is complete.

For a small or moderate file, use the single-part flow:

1. 1
   POST /api/files/upload/init.
2. 2
   Upload the bytes to the returned storage URL.
3. 3
   Confirm the upload with POST /api/files/upload/complete.

   For large files or unreliable networks, use multipart upload:

4. 4
   POST /api/files/upload/multipart/init.
5. 5
   Request each part URL with POST /api/files/upload/multipart/part-url.
6. 6
   Upload parts in parallel with bounded concurrency.
7. 7
   Complete with POST /api/files/upload/complete.
8. 8
   Call POST /api/files/upload/abort when the user cancels or a part cannot be retried.

   Only show a file as available after the complete call succeeds. Keep the upload ID so a failed client can abort or resume safely.

Files are private by default. To publish a file, explicitly set its visibility through the file update endpoint, then expose it through GET /public/files/{fileId}.

Use public visibility only for assets that are safe to distribute. Do not publish credentials, private exports, customer data, or temporary upload objects.

For private downloads and previews, keep the request authenticated and let the API enforce tenant visibility.

Deleting a file moves it into the trash so it can be recovered:

• GET /api/trash lists deleted files.
• POST /api/files/{fileId}/restore restores a file.
• DELETE /api/files/{fileId}/purge permanently deletes one file.
• DELETE /api/trash permanently clears the trash.

Use GET /api/storage/summary to display total usage and composition in an admin or settings surface. Cache the result briefly; usage is a summary, not a replacement for the file list.

Workspace administrators can manage members and their credentials through the Team administration endpoints:

• GET /api/admin/users and POST /api/admin/users
• GET /api/admin/users/{userId}/keys
• POST /api/admin/users/{userId}/disable / enable
• POST /api/admin/keys/{keyId}/revoke

Keep these controls behind an owner/admin permission check and record who performed credential changes.

• Use a production API key stored in a secret manager.
• Verify the current tenant before every file operation in a multi-workspace client.
• Make upload completion idempotent in your client and abort abandoned multipart uploads.
• Keep private files private; publish only an explicit allow-list of assets.
• Test restore and permanent deletion separately.
• Display usage from /api/storage/summary, but derive file-level truth from /api/files.