@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).

Install

npm install @animocabrands/minds-client-lib

Authentication

Create a Builder API key at build.hellominds.ai/console, then pass it to createMindsClient for account and messaging routes. The library does not load .env — your app or the minds CLI handles that.

Bazaar catalog (client.bazaar.*) is public — no API key required. Omit builderApiKey for catalog-only use, or pass it 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 });

| 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 do not 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 { reply, timedOut } = await client.waitForReply({
  alias: "main",
  timeoutMs: 120_000,
});
if (!timedOut && reply) {
  console.log(reply.messageText);
}

API reference

All methods require a valid Builder API key unless noted. Errors throw MindsApiError with status, code, and message.

Account & Minds

| Method | Route | Description | | ------------------ | -------------------------------- | ----------------------------------------------------------------------- | | listMinds(opts?) | GET /v1/humans/{humanId}/minds | List Minds on the builder account. humanId defaults from the key JWT. | | getMind(mindId) | GET /v1/minds/{id} | Full Mind details (walletAddress, chain, email, …). |

Messaging

| Method | Route | Description | | ------------------------------------ | ----------------------------------------- | -------------------------------------------- | | createConversation(body) | POST /v1/messaging/conversation | Create conversation { alias, mindId }. | | ensureConversation(alias, mindId) | same | Create or return existing (handles 409). | | listConversations() | GET /v1/messaging/conversations | List all conversations. | | getConversation(alias) | GET /v1/messaging/conversations/{alias} | Get one conversation. | | sendMessage(body) | POST /v1/messaging/message | Send { alias, messageText, attachments? }. | | getHistory(alias, opts?) | GET /v1/messaging/history/{alias} | Paginated history (limit, after). | | getLatestHistoryFingerprint(alias) | — | Convenience for reply detection. | | getMindIdForAlias(alias) | — | Resolve mindId from history. |

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 | Route | Description | | ---------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------- | | getCognitionUsage(mindId, opts?) | GET /v1/minds/{id}/cognition/usage | Spend over time. interval: 1m, 5m, 15m, 1h, 1d, 1w, 1M. | | getCognitionUsageByTool(mindId, opts?) | GET …/cognition/usage-by-tool | Breakdown by tool. interval: hour, day, week, month only. | | getCognitionBalance(mindId) | GET /v1/minds/{id}/credits | Cognition balance available for the Mind ({ mindId, cognition }). |

Mind status

| Method | Route | Description | | ----------------------------------------- | ---------------------- | ------------------------------------- | | updateMindStatus(mindId, { isEnabled }) | PATCH /v1/minds/{id} | Enable or disable a Mind. Idempotent. |

Circles (human collaborators)

| Method | Route | Description | | ------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------- | | getCircle(mindId) | GET /v1/circles/{mindId} | Member array (CircleMember[]) — steward + human collaborators. | | addCircleMembers(mindId, { emails, isActive? }) | POST /v1/circles/{mindId} | Add human collaborators by email. Returns CircleMutationResult. | | removeCircleMembers(mindId, { emails }) | DELETE /v1/circles/{mindId} | Remove human collaborators by email. | | listCirclesForAccount(opts?) | — | listMinds() + parallel getCircle() per Mind. |

Not documented for builders today: adding other Minds via these routes — use external human emails (e.g. [email protected]). If the platform later supports Mind platform emails on POST/DELETE, the client passes them through; verify with result and getCircle().

Bazaar (public catalog)

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

| Method | Route | Description | | ----------------------------------- | ---------------------------- | --------------------------------------------------- | | bazaar.listSkills(opts?) | GET /v1/bazaar/skills | Search/list skills (search, page, pageSize). | | bazaar.getSkill(skillId) | GET /v1/bazaar/skills/{id} | Skill detail. | | bazaar.listApps(opts?) | GET /v1/bazaar/apps | Search/list apps (search, tier, pagination). | | bazaar.getApp(appId) | GET /v1/bazaar/apps/{id} | 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, BazaarSkill, BazaarApp, Conversation, MessageRecord, MessagingEvent, CognitionBalance, CognitionUsageResponse, CognitionUsageByToolResponse, CircleMember, CircleMutationResult, AccountCircle, and option/body types for each method.

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.