​
Upload artifacts

Artifacts are uploaded directly to object storage using presigned URLs issued by the portal. This avoids proxying large files through the portal and keeps uploads fast and cost-effective.

​
Before you upload

  1. Sign in to the portal at least once so a default organization and storage namespace exist.
  2. Have an active subscription or default plan with enough storage quota.
  3. Install kvcdn and configure an API key.

​
The upload flow

  1. Create artifact metadata in the portal (status pending).
  2. Request a presigned upload URL from /api/v1/artifacts/upload-url.
  3. PUT the file to the returned URL with the required headers.
  4. The CLI calls POST /api/v1/artifacts/{id}/confirm-upload to finalize the upload.
  5. The portal confirms the upload and updates your storage usage.

​
CLI upload

The easiest way is kvcdn upload: 
kvcdn upload ./context.kv --name "Qwen system prompt" --visibility private
The CLI reads the artifact’s JSON sidecar for model_name, dtype, and num_tokens. You can override the inferred name with --name.

​
Share or consume a public artifact

Public artifacts are served from the CDN at: 
https://x.kvcdn.io/{org_slug}/{project_slug}/{artifact_id}
The dashboard shows this URL for any artifact with visibility public. Consumers can download it with a plain GET: 
curl -L -o context.kv https://x.kvcdn.io/{org_slug}/{project_slug}/{artifact_id}
After downloading, load the KV-cache tensors into the same model that produced them and run generation from the cached position. The num_tokens value in the sidecar tells you how many context tokens are already encoded.

​
Storage quota

Free accounts are limited to 20 artifacts. The portal rejects uploads that would exceed this limit with 403 Forbidden. Upgrade in the dashboard to raise the limit.

​
Presigned URL expiration

Presigned URLs expire after 15 minutes. If your upload fails with 403 Forbidden or 400 Bad Request, request a fresh URL and retry.

​
Resuming or retrying

If a PUT to the presigned URL fails halfway through, you must restart the upload from the beginning. The presigned URL is single-use and time-bound.

​
Large files

For files larger than 5 GB, split the artifact into smaller shards at the source. KV Cache Store does not support multipart uploads through presigned URLs.

​
Checksum verification

The portal records the SHA-256 checksum you provide when requesting the upload URL. If the checksum does not match the object in storage, the artifact remains in pending status and the upload must be retried.

​
Example with curl

# 1. Create metadata and get upload URL
RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_name":"Qwen/Qwen3-0.6B","dtype":"F32","num_tokens":512,"visibility":"private","size_bytes":1048576,"checksum":"..."}' \
  https://api.kvcachestore.com/api/v1/artifacts/upload-url)

UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.url')
ARTIFACT_ID=$(echo "$RESPONSE" | jq -r '.artifact_id')

# 2. Upload
curl -X PUT -H "Content-Type: application/octet-stream" \
  --upload-file ./context.kv "$UPLOAD_URL"

# 3. Confirm (optional if your tooling does not confirm automatically)
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"size_bytes\":1048576,\"checksum\":\"$(sha256sum ./context.kv | cut -d' ' -f1)\"}" \
  "https://api.kvcachestore.com/api/v1/artifacts/$ARTIFACT_ID/confirm-upload"

​
Next steps