upload
The upload domain has 4 actions. On the meta surface they are all reached through arcane_upload; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.
Summary
Section titled “Summary”| Action | Title | Kind |
|---|---|---|
upload.chunk_put | Upload a chunk | write |
upload.session_create | Create an upload session | write |
upload.session_delete | Delete an upload session | destructive |
upload.session_get | Get an upload session | read |
Actions
Section titled “Actions”upload.chunk_put
Section titled “upload.chunk_put”Upload a chunk
Upload one chunk of an upload session. Re-sending a chunk is idempotent
- Kind: write
- Required parameters:
kind,uploadId,index - Meta tool:
arcane_uploadwith"action": "chunk_put" - Individual tool:
arcane_upload_chunk_put - Arcane route:
PUT /api/environments/{id}/uploads/{kind}/{uploadId}/chunks/{index} - Operation ID:
upload-chunk - Usage: Sends chunk index (0-based, below totalChunks) of the session from upload.session_create, raw bytes as contentBase64. Every chunk must be exactly chunkSize bytes except the last, which holds the remainder, or the call fails with 422. Chunks may arrive in any order and re-sending one is harmless. The result shows receivedChunks and complete. When complete is true, pass the id as uploadId to image.upload, volume_backup.upload or build.upload, which use the session up even if the import or restore then fails (send the file again in a new session) and answer 409 while chunks are missing. Sessions idle for 24 hours are purged.
- Related actions:
upload.session_create,upload.session_get,image.upload,volume_backup.upload,build.upload
upload.session_create
Section titled “upload.session_create”Create an upload session
Start a chunked upload session. The file arrives as independently retryable chunks
- Kind: write
- Required parameters:
kind,filename,size - Meta tool:
arcane_uploadwith"action": "session_create" - Individual tool:
arcane_upload_session_create - Arcane route:
POST /api/environments/{id}/uploads/{kind} - Operation ID:
create-upload-session - Usage: First step of every file upload. kind picks the consumer: image for image.upload (.tar, .tar.gz, .tgz or .tar.xz, at most the maxImageUploadSize setting, 500 MB by default, needs images:upload), volume-backup for volume_backup.upload (.tar.gz or .tgz, needs volumes:upload) or build-workspace for build.upload (any file, needs build-workspaces:manage). Give filename and size in bytes. chunkSize defaults to 10 MiB and must be 1-50 MiB (1048576 keeps each upload.chunk_put small). Returns id (the uploadId for every later call), chunkSize and totalChunks. Use the same kind and environment for the chunks and the consuming action.
- Related actions:
upload.chunk_put,upload.session_get,image.upload,volume_backup.upload,build.upload
upload.session_delete
Section titled “upload.session_delete”Delete an upload session
Abort an upload session and discard its received chunks
- Kind: destructive — requires
confirm: true - Required parameters:
kind,uploadId - Meta tool:
arcane_uploadwith"action": "session_delete" - Individual tool:
arcane_upload_session_delete - Arcane route:
DELETE /api/environments/{id}/uploads/{kind}/{uploadId} - Operation ID:
delete-upload-session - Usage: Aborts an upload session (uploadId from upload.session_create, same kind) and deletes its received chunks. Use it to abandon an upload you will not consume. Not needed after image.upload, volume_backup.upload or build.upload, which remove the session themselves. A consumed, deleted or purged session gives 404.
- Related actions:
upload.session_get,upload.session_create
upload.session_get
Section titled “upload.session_get”Get an upload session
Inspect an upload session to resume by re-sending only the missing chunks
- Kind: read
- Required parameters:
kind,uploadId - Meta tool:
arcane_uploadwith"action": "session_get" - Individual tool:
arcane_upload_session_get - Arcane route:
GET /api/environments/{id}/uploads/{kind}/{uploadId} - Operation ID:
get-upload-session - Usage: Checks an upload session (uploadId from upload.session_create, same kind) before consuming it or to resume an interrupted upload: receivedChunks lists the chunk indexes already stored and complete says whether all totalChunks are in, so re-send only the missing ones with upload.chunk_put. Fails with 404 once the session is consumed, deleted or purged after 24 idle hours, and with 400 if kind differs from the session’s.
- Related actions:
upload.chunk_put,upload.session_create,upload.session_delete