@animocabrands/minds-client-lib

TypeScript client library for the Hello Minds Builder API (api.build) — messaging, account automation, and builder operations for programmatic agents and apps.

Get started: Minds Client Library guide on build.hellominds.ai

Requirements: Node.js ≥ 22 (ESM) for Node apps. Connect also uses this library in the browser.

Install

npm install @animocabrands/minds-client-lib

Authentication

Account and messaging routes need an OAuth access token or a Builder API key. When both are set, the access token wins (Authorization: Bearer). Otherwise the client sends X-Api-Key. Call setAccessToken(null) (or a blank string) to clear the token and fall back to the key. Pass getAccessToken to supply a fresh Bearer before each authed HTTP/SSE request (wins over a static accessToken for that request).

Create a Builder API key at build.hellominds.ai/console. The library does not load .env — your app or the minds CLI handles that.

OAuth apps can use this client in either place:

• Browser — @animocabrands/minds-connect passes getAccessToken so each request refreshes via the session store (oauth.client).
• Backend — after Connect login, send the access token as Authorization: Bearer on your API and pass it into createMindsClient({ accessToken }).

Bazaar catalog (client.bazaar.*) is public — no credential required. Omit both for catalog-only use, or pass a token/key when you want auth headers sent on bazaar requests (e.g. future protected metadata).

import { BUILDER_API_KEY_ENV, 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 });
// or: createMindsClient({ accessToken }); then client.setAccessToken(nextToken)

| Constant | Value | | ------------------------ | ----------------------- | | BUILDER_API_KEY_ENV | MINDS_BUILDER_API_KEY | | BUILDER_API_KEY_HEADER | X-Api-Key |

The api.build host is fixed in the library — builders cannot configure a base URL.

Quick start — messaging

import { createMindsClient } from "@animocabrands/minds-client-lib";

const client = createMindsClient({ builderApiKey: process.env.MINDS_BUILDER_API_KEY! });

// List Minds on your account (mindId + name)
const minds = await client.listMinds();

// Ensure a conversation, then send
await client.ensureConversation("main", minds[0]!.mindId);
await client.sendMessage({ alias: "main", messageText: "Hello" });

// Wait for a Mind reply (SSE + history poll)
const outcome = await client.waitForReply({
  alias: "main",
  timeoutMs: 120_000,
});
if (!outcome.timedOut) {
  console.log(outcome.reply.messageText);
}

API reference

All methods require an access token or Builder API key unless noted. Errors throw MindsApiError with status, code, and message.

Account & Minds

| Method | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | listMinds(opts?) | List Minds on the builder account. humanId defaults from the access token sub or the key JWT (parseHumanIdFromAccessToken / parseHumanIdFromBuilderApiKey). | | getMind(mindId) | Full Mind details (walletAddress, chain, email, …). | | checkMindName(name) | Public name availability ({ isAvailable }). Key optional. | | awakenMind({ name, id }) | Create a Mind. id is a string slug (POST /v1/minds/awaken), not a closed enum — see API reference. |

The package does not export an archetype catalog. See the API reference. 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);

Messaging

| Method | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | createConversation(body) | Create conversation { alias, mindId }. | | ensureConversation(alias, mindId) | Create or return existing (handles 409). | | listConversations() | List all conversations. | | getConversation(alias) | Get one conversation. | | sendMessage(body) | Send { alias, messageText, attachments? }. | | getHistory(alias, opts?) | Newest-first transcript. cursor (deprecated after) is sent as wire before. Rows use senderType (0 Mind, 1 human). | | getLatestHistoryFingerprint(alias) | Convenience for reply detection. | | getMindIdForAlias(alias) | Resolve mindId from conversation or Mind history rows. |

Events (SSE)

| Method | Description | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | subscribeEvents({ alias?, onEvent, onError?, signal? }) | Callback-based SSE subscription. | | eventsIterator({ alias?, signal? }) | Async generator over SSE events. | | waitForReply({ alias, timeoutMs, afterFingerprint?, sentMessageText?, signal? }) | Wait for a Mind reply; returns { reply, timedOut: false } or { timedOut: true }. |

Use isReplyEvent(event, context) to detect Mind replies in custom SSE handling.

Cognition balance & usage

| Method | Description | | ---------------------------------------- | ----------------------------------------------------------------------- | | getCognitionUsage(mindId, opts?) | Spend over time. interval: 1m, 5m, 15m, 1h, 1d, 1w, 1M. | | getCognitionUsageByTool(mindId, opts?) | Breakdown by tool. interval: hour, day, week, month only. | | getCognitionBalance(mindId) | Cognition balance available for the Mind ({ mindId, cognition }). |

Mind status

| Method | Description | | ----------------------------------------- | ------------------------------------- | | updateMindStatus(mindId, { isEnabled, isListed? }) | Enable/disable a Mind (optional isListed). Returns { msg, result } — not a Mind; call getMind if you need the updated record. |

Equipped skills & apps

Discover catalog IDs via client.bazaar, then equip on a Mind. Body is always { ids: string[] } (UUIDs).

| Method | Description | | -------------------------------- | ------------------------------------------- | | listEquippedSkills(mindId) | Skills currently equipped on the Mind. | | equipSkills(mindId, { ids }) | Equip skills. Returns { results: [...] }. | | unequipSkills(mindId, { ids }) | Unequip skills. | | listEquippedApps(mindId) | Apps currently equipped on the Mind. | | equipApps(mindId, { ids }) | Equip apps. | | unequipApps(mindId, { ids }) | Unequip apps. |

Circles

| Method | Description | | ------------------------------------------------- | -------------------------------------------------------------------------------- | | getCircle(mindId) | Member array (CircleMember[]) — steward, humans, and other Minds. | | addCircleMembers(mindId, { emails, isActive? }) | Add by email (humans or Minds). Returns CircleMutationResult. | | removeCircleMembers(mindId, { emails }) | Remove by email. | | listCirclesForAccount(opts?) | listMinds() + parallel getCircle() per Mind. |

Human emails can be any address. Mind emails end in @hellominds.ai. Confirm with getCircle().

Bazaar (public catalog)

No Builder API key required. Access via client.bazaar on any MindsClient (including createMindsClient({})).

| Method | Description | | ----------------------------------- | --------------------------------------------------- | | bazaar.listSkills(opts?) | Search/list skills (search, page, pageSize). | | bazaar.getSkill(skillId) | Skill detail. | | bazaar.listApps(opts?) | Search/list apps (search, tier, pagination). | | bazaar.getApp(appId) | App detail (includes tools[]). | | bazaar.collectSearchResults(opts) | Auto-paginate, sort, filter, slice (CLI uses this). |

const client = createMindsClient();
const apps = await client.bazaar.listApps({ search: "notion", tier: "verified" });

Types

Exported types include BuilderMind, CheckMindNameResult, AwakenMindResult, BazaarSkill, BazaarApp, EquippedSkill, EquippedApp, EquipIdsBody, Conversation, MessageRecord, MessagingEvent, CognitionBalance, CognitionUsageResponse, CognitionUsageByToolResponse, CircleMember, CircleMutationResult, AccountCircle, and option/body types for each method.

MessageRecord / SSE events expose senderType (0 = Mind, 1 = human).

CLI alternative

Prefer a shell workflow? Use @animocabrands/minds-cli — same api.build surface with JSON stdout, exit codes, and --help examples on every command.

npx @animocabrands/minds-cli@latest doctor
npx @animocabrands/minds-cli@latest list

License

UNLICENSED — private alpha tooling.