Ultrahost/ docs

Ultrahost is usable by a coding agent without a private tour of the infrastructure. The agent gets the same contract a person gets: typed methods, named resources, and a capabilities document.

What the agent should call

Give the agent the user client or the admin client, not both mixed together.

ts
import { createClient } from "@ultrahost/sdk";
import { createAdminClient } from "@ultrahost/admin";

const app = createClient({
  projectId: "my-project",
  token: userAccessToken
});

const admin = createAdminClient({
  projectId: "my-project",
  token: adminAccessToken
});

Use app for the product's runtime behavior. Use admin to provision collections, indexes, policies, and functions. Do not place adminAccessToken in frontend code, even if an agent generated that frontend.

Discover before assuming

Deployments do not all enable the same features. The agent checks capabilities before depending on one.

ts
const capabilities = await ultrahost.projects.getCapabilities();
json
{
  "documents": {
    "available": true,
    "features": ["indexes", "batch", "pagination"]
  },
  "vectors": {
    "available": true,
    "features": ["cosine", "metadata-filtering"]
  },
  "graph": {
    "available": true,
    "features": ["neighbors", "traversal"]
  }
}

If a feature is absent, the agent should not invent a workaround that depends on a specific database, region, or cloud API. It should use another documented Ultrahost capability or stop and say the feature is unavailable.

Rules that keep generated code portable

  • Call ultrahost.documents, ultrahost.search, and the other namespaces. Do not generate AWS, Azure, or DynamoDB calls.
  • Address resources by name: "projects", "daily-report", "company-docs".
  • Create a collection, index, or bucket explicitly. Do not rely on the first write to provision it.
  • Treat authorization checks in React as interface hints. Enforce the rule with Authorization on the API.
  • For LLM calls, request a capability such as "summarize-document". Do not select a provider model or override a budget from the browser. See LLM Plane.
  • Long-running work returns an operation. Wait with operations.wait(id) instead of sleeping on an undocumented URL.

One contract, three surfaces

The OpenAPI spec is the source the TypeScript SDK is generated from or checked against. An MCP server exposes that same contract to agents: same resources, same permissions, no second business API.

An agent implementing against Ultrahost follows the method tables in each building block and the shared rules in Conventions.

A prompt that matches the contract

When you ask an agent to add Ultrahost to an app, name the building block, the resource name, and the credential boundary:

text
Add Ultrahost Document Database to this app.
Use @ultrahost/sdk with the signed-in user's token.
Create a collection named "projects" from the admin client, then
read and write documents from the user client.
Do not create cloud resources directly.
If projects.getCapabilities() says a feature is missing, stop and tell me.

The same shape works for search, files, functions, and the other blocks. Point the agent at the page for that block so it uses the methods listed there.