Get Started

Minds Client Library

A lean TypeScript client for Node: typed messaging, reply waiting, and live events.

When you're ready to build on Minds: add this library to the server side of your project so your app can use your Minds. You keep shaping the product (screens, flows, what users see); your coding agent can wire up the connection in code using a clear, consistent interface instead of guessing at raw API calls.

Install

Requires Node 22+.

npm install @animocabrands/minds-client-lib

Create a client

import { createMindsClient } from "@animocabrands/minds-client-lib";
 
const client = createMindsClient({ builderApiKey: yourBuilderApiKey });

Minds List

listMinds() returns every Mind on your account (mindId, name, model, species, and related fields).

const minds = await client.listMinds();
const mindId = minds[0]?.mindId;

humanId is resolved from your Builder API key automatically. Pass listMinds({ humanId }) when you need an explicit override.

Conversations

Bind a stable alias (e.g. main) to a Mind before messaging:

await client.ensureConversation("main", mindId);

ensureConversation is idempotent — if the alias already exists for that Mind, the existing conversation is returned. Lower-level helpers when you manage aliases yourself:

const conversations = await client.listConversations();
const conversation = await client.getConversation("main");
await client.createConversation({ alias: "main", mindId });

Send and history

await client.sendMessage({ alias: "main", messageText: "Hello" });
 
const rows = await client.getHistory("main", { limit: 50 });
const after = rows.at(-1)?.fingerprint;
const newer = await client.getHistory("main", { after, limit: 50 });

sendMessage requires alias and messageText. Optional attachments accept outbound objects — prefer a public HTTPS url with fileName and mimeType:

await client.sendMessage({
  alias: "main",
  messageText: "Summarize this PDF in one sentence.",
  attachments: [
    {
      url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
      fileName: "dummy.pdf",
      mimeType: "application/pdf",
      extension: "pdf",
    },
  ],
});

Image URLs use the same shape (mimeType: "image/png", etc.). Mind replies on getHistory, waitForReply, and SSE events may include inbound artifacts — for example:

// One attachment on a Mind reply (PDF; artifact body truncated)
{
  artifactId: "7388b65d-144a-49ff-a4dc-cb7c23ded982",
  slug: "whale_watchtower_skill_artifact_1_0_5",
  logicalType: "document",
  mimeType: "application/pdf",
  extension: "pdf",
  artifact: "JVBERi0xLjQK...",
}

Outbound send uses content for inline payloads; inbound replies use artifact for the same role. slug and logicalType are optional strings, treat values as hints, not a fixed enum. See the API reference for field details. getLatestHistoryFingerprint returns the fingerprint of the newest message — pass it as after on getHistory to fetch only newer rows, or as afterFingerprint before waitForReply so you spot replies that arrived after you sent.

Resolve which Mind an alias last talked to:

const mindId = await client.getMindIdForAlias("main");

Wait for a Mind reply

waitForReply listens on the live event stream first, then polls history until a reply arrives or the timeout hits.

const before = await client.getLatestHistoryFingerprint("main");
 
await client.sendMessage({ alias: "main", messageText: "Summarize our plan." });
 
const outcome = await client.waitForReply({
  alias: "main",
  timeoutMs: 180_000,
  afterFingerprint: before,
  sentMessageText: "Summarize our plan.",
});
 
if (!outcome.timedOut) {
  console.log(outcome.reply.messageText);
}

Use isReplyEvent from the package when you filter SSE or history rows yourself.

Live events (SSE)

Subscribe with callbacks:

const sub = client.subscribeEvents({
  alias: "main",
  onEvent: (event) => {
    console.log(event.messageText);
  },
  onError: (err) => console.error(err),
});
 
// later
sub.close();

Or consume the async iterator:

for await (const event of client.eventsIterator({ alias: "main" })) {
  console.log(event.fingerprint, event.messageText);
}

Pass signal on iterator or subscribe options to cancel when your process shuts down.

Errors

Failed HTTP calls throw MindsApiError with status, code, and message. Map 401/403 to a missing or revoked Builder API key; 429 may include retry guidance.

Methods

Area	Methods
Account	`listMinds`
Conversations	`createConversation`, `listConversations`, `getConversation`, `ensureConversation`, `getMindIdForAlias`
Messaging	`sendMessage`, `getHistory`, `getLatestHistoryFingerprint`
Replies	`waitForReply`, `isReplyEvent`, `isReplyHistoryRow`
Events	`subscribeEvents`, `eventsIterator`, `parseSseChunk`

Types (BuilderMind, Conversation, MessageRecord, MessagingEvent, …) and parseHumanIdFromBuilderApiKey are exported from the package entry.