Changelog

What shipped

No Connect API changes. This release depends on @animocabrands/minds-client-lib 0.1.7, so oauth.client.listMinds() uses the user id path from that release.

What shipped

• createMindsClient({ accessToken }) and createMindsClient({ getAccessToken }). A token is sent as Authorization: Bearer. A Builder API key is still X-Api-Key. When both are set, the token wins.
• setAccessToken updates or clears the token after construction. getAccessToken runs before each authed HTTP or SSE request.
• parseHumanIdFromAccessToken reads sub from an access token. parseHumanIdFromBuilderApiKey is unchanged.
• updateMindStatus returns { msg, result }.

Full walkthrough: client library guide .

What shipped

• Install: npm install @animocabrands/minds-connect
• OAuth 2.1 authorization code + PKCE. Register the client on the OAuth Client tab. The client ID is public.
• signIn, handleRedirect, signOut, getAccessToken, and hasScopes
• React bindings on @animocabrands/minds-connect/react: MindsConnect, useMindsConnect, and LoginCallback
• oauth.client is the client library . It refreshes the user's access token before each Builder API call
• MindsScope for the scopes you request. The console lists that client's available scopes as read-only

Get started in the Minds Connect SDK guide .

What shipped

• minds mind check-name --name and minds mind awaken --name --id. --id is a pre-built Mind type. Names are unique; check first. minds mind awaken --help lists each type; the same list is in the API reference .
• minds history is newest-first. --cursor is the last fingerprint on the current page (next older page).
• minds circle add now accepts emails from humans as well as Minds. Human emails can be any address; Mind emails end in @hellominds.ai.

Full walkthrough: CLI guide .

What shipped

• checkMindName (public) and awakenMind({ name, id }). id is a pre-built Mind type. Names are unique; check first. Types are listed in the API reference and in minds mind awaken --help. The package does not export the catalog.
• getHistory is newest-first. SDK cursor (deprecated after) is sent as before.
• addCircleMembers / removeCircleMembers now accept emails from humans as well as Minds. Human emails can be any address; Mind emails end in @hellominds.ai.

Full walkthrough: client library guide .

What shipped

Updates in the API reference :

• GET /v1/messaging/histories/{alias} — conversation transcript is newest-first. Paginate with limit and exclusive before (last-row fingerprint → next older page).
• GET /v1/minds/check/name — public name availability (isAvailable). No Builder API key.
• POST /v1/minds/awaken — create a Mind. id is the pre-built type (enum on this operation). mindName must be unique. 201 is a slim created Mind (mindId, name, email, isEnabled, createdAt).
• POST / DELETE /v1/circles/{mindId} now accept emails from humans as well as Minds.

Notes

• Names are unique; check with GET /v1/minds/check/name first.
• The client library maps SDK cursor / after onto wire before for /histories.

See the CLI and client library guides for command and method names that wrap these routes.

What shipped

• minds history <alias> — conversation history. Paginate with --limit and --cursor (fingerprint).
• minds mind skills list|equip|unequip --mind <uuid> [--id <uuid>]
• minds mind apps list|equip|unequip --mind <uuid> [--id <uuid>]

Browse the Bazaar for skillId / appId, then equip on a Mind with the commands above. Full walkthrough: CLI guide .

What shipped

• getHistory — conversation history for an alias
• listEquippedSkills / equipSkills / unequipSkills
• listEquippedApps / equipApps / unequipApps

Use client.bazaar.* for catalog ID discovery, then the equip methods above to change a Mind's armory. Full walkthrough: client library guide .

What shipped

New and updated public routes in the API reference :

• GET /v1/messaging/histories/{alias} — conversation history (HistoryMessageRecord[]). Paginate with limit and after.
• GET /v1/messaging/history/{alias} — deprecated. Use /histories instead.
• GET / PUT / DELETE /v1/minds/{mindId}/skills — list, equip, and unequip skills ({ "ids": ["uuid"] }; mutations return { "results": [...] }).
• GET / PUT / DELETE /v1/minds/{mindId}/apps — list, equip, and unequip apps (same body/result pattern; app results may include appVersionId and version).

Bazaar remains the public catalog for ID discovery (skillId, appId). Equip and unequip happen on the Mind routes above.

Notes

• Discover skill and app IDs with GET /v1/bazaar/* (no API key), then equip with a Builder API key on /v1/minds/{mindId}/skills|apps.
• Tools equip routes are not part of this public surface.

See the CLI and client library guides for command and method names that wrap these routes.

What shipped

New commands over your Builder API key:

• minds usage show --mind <uuid> and minds usage by-tool --mind <uuid> — cognition spend over time and broken down by tool
• minds cognition balance --mind <uuid> — per-Mind cognition balance
• minds mind show --mind <uuid> — full Mind detail (GET /v1/minds/{mindId}): email, walletAddress, chain, species, isEnabled, and more
• minds mind enable / minds mind disable — pause or resume a Mind without deleting it
• minds circle show|list|add|remove — manage human collaborators on a Mind's circle
• minds bazaar search|skills|apps — browse the public skills and apps catalog (no API key required)
• minds doctor now pings GET /v1/auth/ping and checks the npm registry for CLI updates

CLI polish in the same release:

• Authenticated routes send X-Api-Key only — X-Access-Key is deprecated (env/flag unchanged: MINDS_BUILDER_API_KEY, --builder-api-key)
• Nested --help for multi-segment commands (minds help usage by-tool, minds usage --help by-tool)
• circle add treats exists / already_in_circle as success; warns on stderr only when the mutation had no net effect
• minds --version matches the published package version (build-time injection)

Notes

• usage show and usage by-tool take different interval enums — 1m/5m/15m/1h/1d/1w/1M vs hour/day/week/month. The CLI validates the interval before calling the API.
• Circles accept human collaborator emails only; mind-to-mind circle membership is not supported via this API.
• Bazaar list commands use --search and --max (no --page / --page-size). The CLI auto-paginates internally when needed.
• Bazaar catalog is also in the client library as client.bazaar.*. minds bazaar search returns top-level skills and apps objects (not a single items array). Skills use skillId; apps use appId and appName. Equip HTTP APIs are not on api.build yet — Bazaar is for ID discovery only.
• Canonical help pattern: minds <group> <subcmd> --help.

Get started in the Minds CLI guide .

What shipped

New methods on createMindsClient({ builderApiKey }):

• getMind(mindId) — GET /v1/minds/{mindId} for full Mind detail (walletAddress, chain, …)
• getCognitionUsage, getCognitionUsageByTool — per-Mind cognition spend
• getCognitionBalance — per-Mind cognition balance
• updateMindStatus — enable or disable a Mind
• getCircle, addCircleMembers, removeCircleMembers, listCirclesForAccount — human collaborator circle management

client.bazaar namespace (public catalog — no API key required):

• listSkills, getSkill, listApps, getApp, collectSearchResults
• createMindsClient({}) is valid for Bazaar-only use; auth methods throw missing_builder_api_key at call time if no key was provided

Auth and types:

• Authenticated routes send X-Api-Key only — X-Access-Key is deprecated (not sent by the client library)
• BuilderMind and CognitionBalance exported for TypeScript consumers

Notes

• getCognitionUsage and getCognitionUsageByTool take different interval enums — 1m/5m/15m/1h/1d/1w/1M vs hour/day/week/month.
• Circles accept human collaborator emails only; mind-to-mind circle membership is not supported via this API.
• getCircle returns a CircleMember[] array; addCircleMembers and removeCircleMembers return a { items, summary } mutation envelope.
• Bazaar: skills use skillId; apps use appId and appName (not name). Equip HTTP APIs are not on api.build yet.

Get started in the client library guide .

What shipped

New and updated public routes:

• GET /v1/minds/{mindId} — full Mind detail (email, wallet addresses, chains, species, isEnabled, …)
• GET /v1/minds/{mindId}/cognition/usage — cognition usage over time
• GET /v1/minds/{mindId}/cognition/usage-by-tool — per-tool cognition usage
• GET /v1/minds/{mindId}/credits — per-Mind cognition balance
• PATCH /v1/minds/{mindId} — enable or disable a Mind (isEnabled only)
• GET / POST / DELETE /v1/circles/{mindId} — list, add, or remove human collaborators on a Mind's circle
• GET /v1/bazaar/skills, GET /v1/bazaar/skills/{skillId}, GET /v1/bazaar/apps, GET /v1/bazaar/apps/{appId} — public Bazaar catalog (no API key)

Authenticated routes use a Builder API key. X-Api-Key is the canonical header in the API reference and in client-lib ≥0.1.2. X-Access-Key is deprecated.

Notes

• cognition/usage and cognition/usage-by-tool take different interval enums — 1m/5m/15m/1h/1d/1w/1M vs hour/day/week/month. See the param descriptions in the API reference .
• GET /v1/circles/{mindId} returns a CircleMember[] array; POST and DELETE return a { items, summary } mutation envelope.
• Circles accept human collaborator emails only; mind-to-mind circle membership is not supported via this API.
• Bazaar routes are public — wrapped in client-lib as client.bazaar.* and CLI minds bazaar. Equip APIs are not on api.build yet.

The API reference documents the public contract — Builder API key auth on protected routes, Bazaar routes public, with examples aligned to the live API.

What shipped

• Global install: npm install -g @animocabrands/minds-cli
• One-off runs: npx @animocabrands/minds-cli@latest (no minds prefix on the package name)
• Agent-friendly JSON stdout, stable exit codes, and --help examples on every command
• minds list, minds chat create, minds send --wait, and minds events over your Builder API key
• minds doctor for key, connectivity, and version checks

Get started in the Minds CLI guide .

What shipped

• Install: npm install @animocabrands/minds-client-lib
• createMindsClient({ builderApiKey }) for Node — list Minds, conversations, messaging, history, and SSE events
• waitForReply for send-and-wait flows in application code
• isReplyEvent and history helpers when you filter replies yourself

Get started in the client library guide .