Get Started

Minds Client Library

Embed Minds in your product, configure with the CLI first, then wire the same Builder API into your Node backend with full TypeScript types.

@animocabrands/minds-client-lib is how you wrap and embed Minds in your application or product. Most builders start with the Minds CLI , list Minds, inspect detail, monitor cognition, manage circles, browse the Bazaar, then move here when they are ready to ship. The library exposes the same Builder API with TypeScript types: messaging, waitForReply, SSE events, and the account operations you already ran from the terminal.

Add the package to the server side of your project. Your UI, branding, and user flows stay yours; the client handles typed HTTP and streaming to api.build. Complete Account setup , validate your Mind with the CLI, then wire the examples below, or hand them to a coding agent once configuration is done.

Install

Requires Node 22+.

npm install @animocabrands/minds-client-lib

Authentication

Pass your Builder API key for account and messaging calls. The library sends X-Api-Key only on authenticated requests (≥0.1.2). X-Access-Key is deprecated, do not use it. Env name remains MINDS_BUILDER_API_KEY.

import {
  BUILDER_API_KEY_ENV,
  BUILDER_API_KEY_HEADER,
  createMindsClient,
} from "@animocabrands/minds-client-lib";
 
const builderApiKey = process.env[BUILDER_API_KEY_ENV];
if (!builderApiKey) throw new Error(`${BUILDER_API_KEY_ENV} is not set`);
 
const client = createMindsClient({ builderApiKey });

Create a client

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

createMindsClient({}) is valid for the public Bazaar catalog only (client.bazaar.*). Auth methods throw MindsApiError with code missing_builder_api_key at call time if no key was provided, not at construction.

Create a Mind

Mind names are unique. Call checkMindName first (public, no Builder API key) to see whether a name is already taken, then awakenMind (requires a key). id selects the type of pre-built Mind to create. The package does not export the catalog. Run minds mind awaken --help in the Minds CLI to list each type with a short description. The same list is in the API reference . If the name is taken or id is not valid, awakenMind throws MindsApiError. The example is a sales Mind named J-Belfort. Sell me this pen.

const check = await client.checkMindName("J-Belfort");
if (!check.isAvailable) throw new Error("name taken");
 
const mind = await client.awakenMind({ name: "J-Belfort", id: "sales" });
await client.ensureConversation("main", mind.mindId);

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.

Mind details

getMind(mindId) returns full detail - email, wallet address, chain, species, isEnabled, and more:

const detail = await client.getMind(mindId);
console.log(detail.email, detail.walletAddress, detail.chain);

Cognition balance and usage

Per-Mind cognition usage and balance mirror the CLI commands. Minds consume cognition when they reason, run tools, and carry out autonomous tasks, not only in conversation. Both take a mindId (UUID) and an optional AbortSignal. Cognition powers a Mind's reasoning, tool use, and autonomous work. Use getCognitionUsage and getCognitionUsageByTool for usage over time and per tool. Use getCognitionBalance for the remaining cognition balance:

const mindId = (await client.listMinds())[0]?.mindId;
if (!mindId) throw new Error("No Minds on this account");
 
const usage = await client.getCognitionUsage(mindId, { interval: "1d" });
console.log(usage.items); // [{ bucket, value }, ...]
 
const byTool = await client.getCognitionUsageByTool(mindId, { interval: "day" });
console.log(byTool.summary); // [{ tool, callCount, creditsUsed, ... }, ...]
console.log(byTool.timeline); // [{ tool, timeBucket, callCount, creditsUsed }, ...]
 
const balance = await client.getCognitionBalance(mindId);
console.log(balance.cognition);

The two usage methods accept different interval values: getCognitionUsage accepts 1m, 5m, 15m, 1h, 1d, 1w, 1M; getCognitionUsageByTool accepts hour, day, week, month only. Optional startTime and endTime (ISO date-time) bound the window on both.

Mind status

Enable or disable a Mind without deleting it:

await client.updateMindStatus(mindId, { isEnabled: false });
await client.updateMindStatus(mindId, { isEnabled: true });

updateMindStatus returns the updated BuilderMind.

Circles

A Mind's circle is its set of collaborators - humans and other Minds. getCircle returns a CircleMember[] array directly; addCircleMembers and removeCircleMembers return a CircleMutationResult envelope with per-email outcomes and a best-effort summary:

const members = await client.getCircle(mindId);
console.log(members.map((m) => m.email));
 
const added = await client.addCircleMembers(mindId, {
  emails: ["someone@company.com", "the.dude@hellominds.ai"],
  isActive: true,
});
console.log(added.items);
 
const removed = await client.removeCircleMembers(mindId, {
  emails: ["someone@company.com"],
});
console.log(removed.items);

Human emails can be any address; Mind emails end in @hellominds.ai. listCirclesForAccount() is a convenience that calls listMinds() then getCircle() for each Mind in parallel; use it for account-wide overviews rather than hot paths.

Bazaar catalog

The public Bazaar catalog is available as client.bazaar, no API key required. Use Bazaar for ID discovery (skillId, appId), then equip those IDs with the Mind equip methods below. Route shapes are in the API reference Bazaar and Minds tags; the CLI exposes the same catalog via minds bazaar. List items may include equippedCount, how many Minds have equipped that item platform-wide. That is popularity across the platform. Use listEquippedSkills / listEquippedApps for the per-Mind equipped set.

const catalog = createMindsClient({}).bazaar;
 
const skills = await catalog.listSkills({ search: "research", page: 1, pageSize: 25 });
const skill = await catalog.getSkill("skill_abc123");
 
const apps = await catalog.listApps({ search: "notion", tier: "verified" });
const app = await catalog.getApp("app_xyz789");
 
const result = await catalog.collectSearchResults({
  scanMax: 200,
  max: 50,
  sort: "equipped",
  fetchPage: (page, pageSize) => catalog.listSkills({ search: "agent", page, pageSize }),
  getEquippedCount: (s) => s.equippedCount ?? 0,
  getName: (s) => s.name,
  getCreatedAt: (s) => s.createdAt,
});

Apps use appId and appName (not name). collectSearchResults auto-paginates up to scanMax, applies client-side sort/filter, and reports truncated when the scanned set exceeds max. sort: "equipped" orders by equippedCount descending (platform popularity), not per-Mind equip status.

Equip skills and apps

List, equip, or unequip skills and apps on a Mind (requires a Builder API key). Bodies use { ids: string[] }; mutations return { results: [...] } with skillId / appId, isEquipped, and changed (app results may also include appVersionId and version):

const equippedSkills = await client.listEquippedSkills(mindId);
await client.equipSkills(mindId, { ids: [skill.skillId] });
await client.unequipSkills(mindId, { ids: [skill.skillId] });
 
const equippedApps = await client.listEquippedApps(mindId);
await client.equipApps(mindId, { ids: [app.appId] });
await client.unequipApps(mindId, { ids: [app.appId] });

Discover IDs via client.bazaar first when you need catalog browse. Equipped skills include source: mind for catalog / Mind-authored skills, system for platform skills (e.g. Skill Architect).

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 });
// rows[0] is newest. Last fingerprint → next older page (wire `before`).
const cursor = rows.at(-1)?.fingerprint;
const older = await client.getHistory("main", { cursor, limit: 50 });

getHistory returns the full human + Mind transcript, newest-first. Rows use senderType (1 = human, 0 = Mind). The SDK cursor (and deprecated after) is sent as query before - exclusive next older page. The same senderType field appears on SSE events from subscribeEvents / eventsIterator / waitForReply. 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 afterFingerprint to waitForReply so you only accept replies that arrived after you sent. The first getHistory page (no cursor) is already the newest window - do not pass that fingerprint as cursor expecting newer rows.

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. Calling an auth method without builderApiKey throws missing_builder_api_key at call time. Map 401/403 to a missing or revoked Builder API key; 429 may include retry guidance.

Methods

Area	Methods
Account	`listMinds`
Minds	`checkMindName`, `awakenMind`, `getMind`, `updateMindStatus`
Cognition	`getCognitionUsage`, `getCognitionUsageByTool`, `getCognitionBalance`
Equip	`listEquippedSkills`, `equipSkills`, `unequipSkills`, `listEquippedApps`, `equipApps`, `unequipApps`
Circles	`getCircle`, `addCircleMembers`, `removeCircleMembers`, `listCirclesForAccount`
Bazaar	`bazaar.listSkills`, `bazaar.getSkill`, `bazaar.listApps`, `bazaar.getApp`, `bazaar.collectSearchResults`
Conversations	`createConversation`, `listConversations`, `getConversation`, `ensureConversation`, `getMindIdForAlias`
Messaging	`sendMessage`, `getHistory`, `getLatestHistoryFingerprint`
Replies	`waitForReply`, `isReplyEvent`, `isReplyHistoryRow`
Events	`subscribeEvents`, `eventsIterator`, `parseSseChunk`

Types (BuilderMind, Conversation, MessageRecord, MessagingEvent, CognitionBalance, BazaarSkill, BazaarApp, EquippedSkill, EquippedApp, CircleMember, CircleMutationResult, CognitionUsageResponse, CognitionUsageByToolResponse, UpdateMindStatusBody, CheckMindNameResult, AwakenMindResult, …) and parseHumanIdFromBuilderApiKey are exported from the package entry.