Install. Quickstart. Reference.

Create an asset and receive an upload descriptor (single PUT for ≤100 MiB, multipart above). The SDK's client.upload(...) wraps this plus the part PUT and complete calls.

khs upload clip.mov

await client.upload(
  await sourceFromPath('clip.mov')
);

curl -X POST https://api.khaosstorage.com/v1/assets \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename":"clip.mov",
    "type":"video",
    "content_type":"video/quicktime",
    "size_bytes":3621090133,
    "multipart":true
  }'

List assets. Supports limit, cursor, status, type, search, and modified_after.

Node

const assets = await client.assets.list({
  type: 'video',
  status: 'active',
  limit: 50,
});

Fetch one asset by id. The response carries any populated thumb_url and preview_url as 1-hour signed GETs.

await client.assets.get('ast_…');

Update tags, filename, or attributes. Returns the full asset.

await client.assets.patch('ast_…', { tags: ['raw','drone'] });

Hard-delete the asset and its R2 objects (original, thumb, preview). Idempotent.

await client.assets.delete('ast_…');

Mint a signed download URL for the original. Default 1-hour TTL via expires_in.

await client.assets.url('ast_…', 3600);

Mint a per-attempt presigned PUT URL for one part of a multipart upload. Refresh per attempt; URLs expire in 15 minutes.

await client.assets.presignPart('ast_…', uploadId, partNumber);

Finalize the upload. Pass upload_id + parts for multipart; empty body for single PUT. Triggers the processor fan-out.

await client.assets.completeUpload('ast_…', uploadId, parts);

Abort an in-flight multipart upload. Cleans up R2 state. Called automatically by the SDK when an upload is cancelled.

await client.assets.abortUpload('ast_…', uploadId);

Re-run the image / video processor. Useful after a processor bug fix or to regenerate thumbnails.

await client.assets.reprocess('ast_…');

Paginated bulk reprocess. Each call processes up to limit active assets (default 50, max 100) and returns a next_cursor to continue. Loop on has_more until exhausted. Skips non-active assets server-side. Useful after a XIFty / processor upgrade lands and existing assets need fresh metadata. Same idempotent fan-out as the per-asset endpoint.

// Walk every batch:
let cursor;
for (;;) {
  const batch = await client.assets.bulkReprocess({ cursor });
  if (!batch.has_more) break;
  cursor = batch.next_cursor;
}

// Or from the CLI:
khs reprocess --all
khs reprocess --all --type image --limit 100

List the spaces an asset is currently published into.

await client.assets.spaces('ast_…');

Create a space. visibility defaults to private (owner-only grouping). Pass public for an open share URL, or protected with a password for a password-gated URL.

await client.spaces.create({
  name: 'Highlights',
  visibility: 'public',
});

List your spaces.

await client.spaces.list();

Get one space, including asset_count.

await client.spaces.get('spc_…');

Update name, description, visibility, or password. Pass password: null to clear.

await client.spaces.update('spc_…', { visibility: 'public', password: null });

Delete the space. Cascades publications. Underlying assets are not affected.

await client.spaces.delete('spc_…');

Publish one or more assets into the space. Returns per-asset success / error.

await client.spaces.publish('spc_…', ['ast_…','ast_…']);

List the assets published into a space, decorated with signed thumb/preview URLs.

await client.spaces.listPublications('spc_…');

Unpublish one asset from a space. The asset itself stays.

await client.spaces.unpublish('spc_…','ast_…');

List your keys. Hashes only; never the raw value.

await client.apiKeys.list();

Mint a new key. The response includes the raw key exactly once. Persist it now.

await client.apiKeys.create({
  name: 'ingest-bot',
  scopes: ['write'],
});

Revoke. Idempotent. Subsequent requests bearing the revoked key fail at the authorizer.

await client.apiKeys.revoke('key_…');

List configured connections.

Add a connection. The server runs HEAD / LIST / PUT / DELETE probes against the bucket before persisting.

Run the same probes without persisting. Useful for the onboarding wizard.

Discovery: enumerate buckets visible to the credentials. Used during connection setup.

Discovery: create a new bucket using the credentials. Region-aware.

Read the current account: display_name, email, plan, status, plus optional onboarded_at, avatar_url (1-hour signed), handle, bio, links, is_public. The first authenticated read after sign-up auto-derives a unique handle from the email local part.

await client.account.get();

Update display_name or email. Profile-shaped fields go through the dedicated profile route below.

await client.account.patch({ display_name: 'K' });

Stamp onboarded_at idempotently and (optionally) set display_name in one atomic write. Body is optional — empty body is "skip the welcome prompt, just mark me onboarded." Console calls this once after email verification.

await client.account.onboard({ display_name: 'Khaos Studio' });

Step 1 of avatar upload. Returns a presigned PUT URL plus a storage_key. Resize the image to 256×256 before sending the bytes — JPEG quality 85 is what the console emits. Allow-list: image/jpeg, image/png, image/webp; max 10 MB raw input.

const desc = await client.account.startAvatarUpload({
  content_type: 'image/jpeg',
  size_bytes: bytes.length,
});
await fetch(desc.url, { method: 'PUT', headers: desc.headers, body: bytes });

Step 2. Confirms the bytes landed (server HEADs the storage_key) and atomically swaps avatar_storage_key on the account. The previous avatar object is best-effort deleted from R2. Returns the account with a fresh signed avatar_url.

await client.account.completeAvatarUpload(desc.storage_key);

Clear the custom avatar; UI falls back to initials. Idempotent.

await client.account.deleteAvatar();

Update the public profile: handle, bio (≤280 chars), links (max 6, http(s) only), is_public. Renaming the handle atomically releases the old slug; surface a warning in your UI before submit. Conflicts return 409 handle_taken.

await client.account.updateProfile({
  handle: 'kimi',
  bio: 'photographer / filmmaker',
  links: [{ label: 'site', url: 'https://example.com' }],
  is_public: true,
});

Returns total_assets, total_bytes, and the same broken out by managed_* and byok_*.

If the space is public, returns the manifest with signed asset URLs. If protected, returns { requires_password: true }. Private spaces 404 (existence not leaked).

Submit { password }; on match, returns the manifest. No tokens, no sessions; re-auth per request.

Returns display_name, bio, links, signed avatar_url, and the owner's public spaces (cover-decorated, sorted newest-first, capped at 24). Strictly less than the authenticated /v1/account projection — never leaks email, plan, status, or onboarded_at.

await client.publicProfiles.get('kimi');