Start
Conventions
Shared lifecycle, REST behavior, and the rules the SDK hides.
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.
| SDK | Purpose |
|---|---|
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:
https://api.ultrahost.com/v1Project resources live under:
/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.
| Verb | Meaning |
|---|---|
GET | Retrieve a resource or a list |
POST | Create a resource, or run an operation such as query, search, or invoke |
PATCH | Partial update |
PUT | Replace a resource, or set a singleton such as a budget |
DELETE | Remove 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.
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:
{
id: "operation-123",
status: "running",
progress: 45
}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:
"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
| Section | What it answers |
|---|---|
| Create | How to provision the capability, including the REST endpoint and the default |
| Configure | Settings, defaults, and what changes operationally |
| Use | How 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.