Ultrahost/ docs

A session is the memory of a piece of agent work: who it is for, what has been said, and which checkpoint is safe to return to.

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

Create

SDKRESTDescription
sessions.create(config)POST /sessionsCreate a session
sessions.get(id)GET /sessions/{id}Retrieve a session
sessions.list(options?)GET /sessionsList sessions
sessions.update(id, data)PATCH /sessions/{id}Update session metadata
sessions.delete(id)DELETE /sessions/{id}Delete a session
sessions.clear(id)POST /sessions/{id}/clearClear stored context
sessions.fork(id)POST /sessions/{id}/forkBranch a session
ts
const session = await ultrahost.sessions.create({
  agent: "research-assistant",
  userId: user.id
});

fork copies a session so a second line of work can continue without rewriting the original.

Configure

clear drops stored context and keeps the session id. delete removes the session.

Concurrent agents use optimistic concurrency on state. Updates carry a revision, or an equivalent token, and fail when the revision is stale. A lost update does not overwrite a newer one.

Checkpoints are the restore points. Create them at boundaries the agent can safely resume from, not after every token.

Use

SDKRESTDescription
sessions.getState(id)GET /sessions/{id}/stateCurrent state
sessions.setState(id, state)PUT /sessions/{id}/stateReplace state
sessions.patchState(id, patch)PATCH /sessions/{id}/statePartial state update
sessions.appendMessage(id, message)POST /sessions/{id}/messagesAppend a message
sessions.getMessages(id, options?)GET /sessions/{id}/messagesConversation history
sessions.checkpoint(id)POST /sessions/{id}/checkpointsSave a checkpoint
sessions.restore(id, checkpointId)POST /sessions/{id}/restoreRestore a checkpoint
sessions.listCheckpoints(id)GET /sessions/{id}/checkpointsList checkpoints
ts
await ultrahost.sessions.appendMessage(session.id, {
  role: "user",
  content: "Research competitors in the CRM market"
});

await ultrahost.sessions.checkpoint(session.id);

useAgentSession(id) is the React hook for reading that state. Message history is cursor-paginated.