AuraClient

Thin client for the Strangeworks Aura public /api/v1 surface.

Authenticates with a company API key (sk-aura-…). chat delivers a turn live over the project WebSocket (key on the upgrade header) and reconciles the final message via /chat/sync; when the socket can’t be held open it degrades to dispatch + poll.

Constructors

Constructor

new AuraClient(options): AuraClient;

Parameters

Parameter	Type
options	AuraClientOptions

Returns

AuraClient

Methods

cancel()

cancel(projectId, conversationId?): Promise<boolean>;

Stop a running turn, scoped to conversationId when given and to the whole project otherwise. Returns whether anything was cancelled.

Parameters

Parameter	Type
projectId	string
conversationId?	string

Returns

Promise<boolean>

---

chat()

chat(
   projectId,
   content,
   opts?): Promise<{
}>;

Send a message, follow the turn live, and return the reply to this dispatch. onDelta receives assistant text as it is generated and onToolActivity each tool start/completion, streamed over the project WebSocket. The stream is liveness only — the returned message always comes from a final /chat/sync reconcile, and when the socket can’t be opened or dies mid-turn the call silently degrades to a polling wait (see waitForIdleReply): the reply is unaffected, only the live callbacks stop.

The wait is pinned to the conversation the dispatch resolved to, so a concurrent activate or createConversation on the same project cannot make it watch another thread.

Throws AuraTurnTimeoutError on timeout — it carries the pinned conversation id to pass to cancel, and the turn keeps running server-side — and AuraTurnCancelledError when the turn ended partially or opts.signal aborts, carrying whatever partial output was streamed or stored, so a caller that stopped the turn can still show what it produced.

Parameters

Parameter	Type
projectId	string
content	string
opts	ChatTurnOptions

Returns

Promise<{ }>

---

checkDeployment()

checkDeployment(name): Promise<{
}>;

Run the server-side run contract against a deployment: does it have a solver package under run/ and a dataset under data/?

Parameters

Parameter	Type
name	string

Returns

Promise<{ }>

ok, plus missing and warnings naming what a project created from this deployment would fail on.

---

checkout()

checkout(
   projectId,
   source,
   conversationId?): Promise<{
}>;

Point the project’s workspace at source, which the server dispatches on segment count: one segment is a snapshot id or a tag name, two is a <group>/<name> deployment handle, three is a <group>/<project>/<name> in-project snapshot tag.

Parameters

Parameter	Type
projectId	string
source	string
conversationId?	string

Returns

Promise<{ }>

---

createConversation()

createConversation(projectId, title?): Promise<{
}>;

Start a new conversation in a project.

Parameters

Parameter	Type	Description
projectId	string	-
title?	string	Optional label; the server names it if omitted.

Returns

Promise<{ }>

---

createDeployment()

createDeployment(name): Promise<{
}>;

Create an empty deployment. Upload its files with deployFromFolder or uploadFile against a { source: "deployment", deploymentName } container, then confirm it with checkDeployment.

Parameters

Parameter	Type	Description
name	string	Deployment name — lowercase letters, digits and hyphens.

Returns

Promise<{ }>

---

createProject()

createProject(input): Promise<{
}>;

Create a project, optionally seeded from a published deployment. A project seeded from a deployment lands directly in run mode, so the run agent is usable on it immediately.

Parameters

Parameter	Type	Description
input	{ description?: string; fromDeployment?: string; name: string; shortDescription?: string; }	-
input.description?	string	-
input.fromDeployment?	string	A deployment handle, “/”. The wire field is from.
input.name	string	-
input.shortDescription?	string	-

Returns

Promise<{ }>

Throws

AuraApiError when the deployment handle is unknown or fails its run contract.

---

deleteConversation()

deleteConversation(projectId, conversationId): Promise<void>;

Delete one conversation and its messages. The project is untouched.

Parameters

Parameter	Type
projectId	string
conversationId	string

Returns

Promise<void>

---

deleteDeployment()

deleteDeployment(name): Promise<{
}>;

Delete a deployment: its files are purged and its name is freed for reuse.

Irreversible — there is no undelete, and a new deployment claiming the same name starts empty. Projects already seeded from this deployment keep their own copy of the workspace and are not touched; the returned seeded_project_count reports how many there were.

Requires an admin, which every API key satisfies.

Parameters

Parameter	Type
name	string

Returns

Promise<{ }>

Throws

AuraApiError with status 404 when no such deployment exists.

---

deleteFile()

deleteFile(container, path): Promise<{
}>;

Remove one file from a container. Not recursive — pass a file path, not a directory.

Parameters

Parameter	Type
container	FileContainer
path	string

Returns

Promise<{ }>

---

deleteProject()

deleteProject(projectId): Promise<void>;

Delete a project and everything in it — conversations, executions, snapshots and the workspace. Not recoverable.

Parameters

Parameter	Type
projectId	string

Returns

Promise<void>

---

getAgentStatus()

getAgentStatus(projectId): Promise<{
}>;

Whether a turn is in flight, without inferring it from /chat/sync.

Parameters

Parameter	Type
projectId	string

Returns

Promise<{ }>

---

getConversationState()

getConversationState(projectId, conversationId?): Promise<{
}>;

An atomic snapshot of a conversation: the messages the server has stored, plus whether a turn is in flight.

Parameters

Parameter	Type	Description
projectId	string	-
conversationId?	string	Defaults to the project’s active conversation at the time of the call, so pass it explicitly when polling a specific thread.

Returns

Promise<{ }>

---

getDeployment()

getDeployment(name): Promise<{
}>;

One deployment by name.

Parameters

Parameter	Type
name	string

Returns

Promise<{ }>

Throws

AuraApiError with status 404 when no such deployment exists.

---

getExecution()

getExecution(projectId, executionId): Promise<{
}>;

One solve execution by id.

Parameters

Parameter	Type
projectId	string
executionId	string

Returns

Promise<{ }>

---

getProject()

getProject(projectId): Promise<{
}>;

One project in full.

Parameters

Parameter	Type
projectId	string

Returns

Promise<{ }>

Throws

AuraApiError with status 404 when no such project exists.

---

getSnapshot()

getSnapshot(projectId, ref): Promise<{
}>;

One snapshot, including its files — which the list response omits.

Parameters

Parameter	Type	Description
projectId	string	-
ref	string	A snapshot id or a tag name defined in this project.

Returns

Promise<{ }>

---

listConversations()

listConversations(projectId): Promise<object[]>;

A project’s conversations, newest first. Reads all pages.

Parameters

Parameter	Type
projectId	string

Returns

Promise<object[]>

---

listDeployments()

listDeployments(): Promise<object[]>;

Every deployment in your company, newest first. Reads all pages.

Returns

Promise<object[]>

---

listExecutions()

listExecutions(projectId): Promise<object[]>;

Solve executions for the project, most recent first — the run the agent triggered.

Parameters

Parameter	Type
projectId	string

Returns

Promise<object[]>

---

listFiles()

listFiles(container, pathPrefix?): Promise<object[]>;

The files currently in a container. Reads all pages.

Parameters

Parameter	Type	Description
container	FileContainer	-
pathPrefix?	string	Restrict to one subtree, e.g. "run/output/".

Returns

Promise<object[]>

---

listProjects()

listProjects(): Promise<object[]>;

Every project in your company, as summaries rather than full projects. Reads all pages.

Returns

Promise<object[]>

---

listSnapshots()

listSnapshots(projectId): Promise<object[]>;

A project’s snapshots, newest first, so index 0 is the most recent. Reads all pages.

Parameters

Parameter	Type
projectId	string

Returns

Promise<object[]>

---

listTags()

listTags(projectId): Promise<object[]>;

A project’s snapshot tags. Reads all pages.

Parameters

Parameter	Type
projectId	string

Returns

Promise<object[]>

---

readFile()

readFile(container, path): Promise<{
}>;

Read one file. text is set for text files, base64 for binary.

Parameters

Parameter	Type
container	FileContainer
path	string

Returns

Promise<{ }>

---

sendMessage()

sendMessage(projectId, input): Promise<{
}>;

Dispatch a message without waiting for the agent’s reply — chat is the one-await version. Use this when you want to drive the polling yourself with getConversationState.

Parameters

Parameter	Type
projectId	string
input	object & SendChatOptions

Returns

Promise<{ }>

The dispatch result, including the stored user message and its sequence — which is what identifies the reply to this message.

---

setTag()

setTag(
   projectId,
   name,
   snapshotId): Promise<{
}>;

Point a tag at a snapshot, creating it or moving an existing one. Idempotent.

Parameters

Parameter	Type	Description
projectId	string	-
name	string	The tag name, e.g. "best-known".
snapshotId	string	-

Returns

Promise<{ }>

---

uploadFile()

uploadFile(
   container,
   path,
   body,
   contentType): Promise<{
}>;

Upload one file via the unified files API: plan → PUT the bytes to the plan URL → complete. The byte PUT targets the plan URL directly (presigned on R2, a tokenized backend URL in dev) with only the plan’s headers — never the API key.

Parameters

Parameter	Type
container	FileContainer
path	string
body	string | Uint8Array<ArrayBufferLike>
contentType	string

Returns

Promise<{ }>