Ultrahost/ docs

Building blocks differ in what they store. They do not differ in how a developer creates, lists, updates, and deletes them.

Resource lifecycle

Where a resource can be managed, the SDK exposes the same verbs.

SDKPurpose
create()Create a resource
get()Retrieve a resource and its configuration
list()List resources
update()Change configuration
delete()Delete a resource
enable()Enable a disabled resource
disable()Pause a resource without deleting it
stats()Usage and operational statistics

Not every resource implements every verb. A single document has no enable(). When a namespace manages more than one kind of resource, the method name says which kind: documents.createCollection() and documents.createIndex(), not a bare create() that could mean either. When the namespace manages one kind, the short name is enough: cron.create().

REST

Base URL:

text
https://api.ultrahost.com/v1

Project resources live under:

text
/projects/{projectId}/...

Tables in this reference omit that prefix. POST /documents/collections means POST /v1/projects/{projectId}/documents/collections. The SDK adds the prefix from the client configuration.

GET /health is the exception. It is not project-scoped. See Projects & operations.

VerbMeaning
GETRetrieve a resource or a list
POSTCreate a resource, or run an operation such as query, search, or invoke
PATCHPartial update
PUTReplace a resource, or set a singleton such as a budget
DELETERemove a resource

Shared behavior:

  • List endpoints filter and paginate with cursors.
  • Mutations accept an idempotency key so a retry does not apply twice.
  • Long-running work returns an operation instead of blocking until it finishes.
  • Errors use a consistent code and metadata shape.

The SDK hides the idempotency-key header, the cursor query parameters, and the error catalog. Callers rely on the behavior above.

Queries stay portable

Filters use a typed, portable format. They do not expose DynamoDB expressions, SQL, or another store's query language.

ts
const results = await ultrahost.documents.query("projects", {
  filter: { status: "active" },
  sort: [{ field: "createdAt", direction: "desc" }],
  limit: 20
});

Long-running operations

Some calls return immediately, such as documents.get(). Others, such as search.reindex(), can take minutes. Those return an operation:

ts
{
  id: "operation-123",
  status: "running",
  progress: 45
}
ts
await ultrahost.operations.wait("operation-123");

wait() is the same helper for indexing, ingestion, deployment, and other background work. Cancel with operations.cancel(id) when the operation supports it.

Names, not infrastructure ids

Application code uses names:

text
"products"
"customer-support"
"daily-report"
"company-knowledge"

Ultrahost maps those names to whatever the underlying storage is. The SDK does not accept or return cloud resource identifiers.

How each page is organized

SectionWhat it answers
CreateHow to provision the capability, including the REST endpoint and the default
ConfigureSettings, defaults, and what changes operationally
UseHow application code reads, writes, or executes

A page includes an SDK example, the matching REST path, and — where a UI is the normal caller — a React sketch. Full response schemas are in the OpenAPI spec.