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_…');

List the spaces an asset is currently published into.

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

Create a space. visibility is public or protected; the latter requires a password.

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.

Update display name or email.

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 }.

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