Ultrahost/ docs

Buckets are logical names. Ultrahost maps them to storage. Application code uses paths such as users/${user.id}/resume.pdf, not bucket URLs from a cloud console.

Paths in the tables are relative to https://api.ultrahost.com/v1/projects/{projectId}. Pagination, idempotency, and errors are described in Conventions.

Create

SDKRESTDescription
files.createBucket(name, config?)POST /files/bucketsCreate a logical bucket
files.getBucket(name)GET /files/buckets/{name}Retrieve configuration
files.listBuckets()GET /files/bucketsList buckets
files.updateBucket(name, config)PATCH /files/buckets/{name}Update storage settings
files.deleteBucket(name)DELETE /files/buckets/{name}Delete a bucket

Creating a bucket is administrative. Uploading into an existing bucket can be an end-user action when policy allows it.

Configure

Bucket settings cover privacy defaults and which transforms the bucket allows. Per-object privacy can still be set at upload time with private: true.

Transforms are for file types the bucket declares. The API does not treat every format as resizable or convertible.

Direct uploads use a temporary URL from files.getUploadUrl() so large files are not proxied through the application server. The React SDK exposes progress, cancellation, and resume on top of that URL via useFileUpload(bucket).

Use

SDKRESTDescription
files.upload(bucket, file, options?)POST /files/{bucket}/uploadsUpload a file
files.download(bucket, path)GET /files/{bucket}/objects/{path}Download a file
files.get(bucket, path)GET /files/{bucket}/metadata/{path}Retrieve metadata
files.list(bucket, options?)GET /files/{bucket}/objectsList files
files.delete(bucket, path)DELETE /files/{bucket}/objects/{path}Delete a file
files.copy(bucket, source, target)POST /files/{bucket}/copyCopy a file
files.move(bucket, source, target)POST /files/{bucket}/moveMove a file
files.getSignedUrl(bucket, path, options?)POST /files/{bucket}/signed-urlTemporary access URL
files.transform(bucket, path, options)POST /files/{bucket}/transformTransform a supported file
files.getUploadUrl(bucket, options)POST /files/{bucket}/upload-urlDirect upload URL
ts
await ultrahost.files.upload("documents", selectedFile, {
  path: `users/${user.id}/resume.pdf`,
  private: true
});

const url = await ultrahost.files.getSignedUrl(
  "documents",
  `users/${user.id}/resume.pdf`,
  { expiresIn: 300 }
);