JavaScript SDK - Cominty Docs

The Cominty JavaScript SDK wraps the chat API: start a conversation with an agent, stream its progress, continue the thread, manage threads, cancel or export a message, upload and download files, and store memory files an agent can read back later. It also configures what an admin configures in the console: list MCP integrations, create agents, upload skills, and index files as a source. Chat and threads are scoped to a single end user (userId) that you set once on the client. Memory files are scoped to a namespace you choose, shared by the API key. See Memory namespaces. It is written in TypeScript and works from plain JavaScript too. It tracks the same API as the Python SDK.

Quickstart

Task-by-task examples, most with a runnable script on GitHub.

Guides

Concepts behind capabilities, memory namespaces, and tool-round caps.

Use cases

Recipes that show what a capability changes.

Reference

Every resource, type, event, and error.

GitHub

Source, issues, and the full examples/ directory.

API reference

The HTTP endpoints the SDK calls, with a live playground.

Package @cominty-ai/sdk (

) · runtime Node 20+, Bun, Deno, edge workers · module ESM only, types included · dependencies none (native fetch and ReadableStream).

Install

npm install @cominty-ai/sdk     # or: pnpm add, yarn add, bun add

The resources for MCP, agents, skills, sources, and documents need version 0.4.0 or later. Capabilities, cancel, export, and file uploads need 0.3.0 or later. The package is ESM only. From CommonJS, require('@cominty-ai/sdk') works on Node 22.12 and later. On an older Node, use await import('@cominty-ai/sdk').

Server-side only. Your API key must never reach a browser: anyone who opens the developer tools could read it. Building a client in a browser throws. Call the SDK from your own backend, and relay the progress to your web app. See Relay progress to a browser.

Authenticate

You need two credentials, both from platform.cominty.ai:

Get your API key

Open the API keys page and create a key. A key created now starts with sk-cmt-. Copy it when you create it: it is shown once. Use the string as is. Do not add a second sk-cmt- prefix. A key created before the prefix existed has no sk-cmt- and still works.

Get your user id

Open your avatar → Profile. It looks like user_31HPTBuBvX20xlQNAbvxjOxPbKB.

Export both

export COMINTY_API_KEY="sk-cmt-..."
export COMINTY_USER_ID="user_..."

With both set, new Cominty() picks them up automatically. No arguments needed. On a runtime without process.env, such as an edge worker, pass apiToken and userId explicitly.

Pick an agentId from platform.cominty.ai/agents (for example __cominty_agents::agent.chat). See Built-in agents for what Chat, Hive, and Planner can do.

Your first call

Save this as first-call.mjs and run node first-call.mjs:

import { Cominty } from '@cominty-ai/sdk'

const client = new Cominty() // reads COMINTY_API_KEY + COMINTY_USER_ID

const run = await client.chat.start({
    agentId: '__cominty_agents::agent.chat',
    message: 'What is Cominty?',
})
console.log(await run.text())

The same code runs as TypeScript. Every argument and every response is typed.

Core concepts

Client: one user per client

Cominty is bound to a single userId, validated when you build it. Chat and thread requests send it. Memory requests do not. Resource methods never take userId. The client holds no persistent connection, so closing it is optional. client.close() aborts every request still in flight, and await using client = new Cominty() calls it for you. See Client for all settings.

Resources: chat, threads, memory, and configuration

client.chat starts and continues conversations, streams progress, cancels or exports a message, and uploads/downloads files. client.threads lists, fetches, updates, and archives threads. client.memory creates, lists, reads, updates, and deletes memory files in a namespace you choose. See Memory namespaces and Resources.Five more resources configure the organization (SDK 0.4.0): client.mcp lists MCP integrations, client.agents manages custom agents and their models, client.skills manages skills, client.sources turns files into an indexed source, and client.documents resolves a cited document. See Custom agents, Skills, and Sources.

The API key: an admin of its organization

An API key acts as an admin of its own organization. What it creates is owned by the user who created the key. It never sees another member’s private agents, skills, or drives, and a read by id throws NotFoundError. See What an API key can do.

Runs: the assistant's in-progress reply

chat.start and chat.send return a run: the assistant’s reply as it is being produced. Iterate it with for await for live progress events, or just await run.text() for the final answer. A run’s stream is single-use. See The run handle.

Capabilities: what the agent can use

Web search, document search, MCP connections, skills, media generation, and memory are capabilities. They follow the agent’s setup by default. Change them for a whole thread with threadCapabilities (chat.start only), or for one message with messageScope. Both are plain objects. See Capabilities and the reference.

sourceIds, documentIds, disabledTools, and memoryNamespace still work but are deprecated. Use messageScope and threadCapabilities.memory instead.

Configuration

Setting	Option	Env var	Default
API key	`apiToken`	`COMINTY_API_KEY`	required
End user	`userId`	`COMINTY_USER_ID`	required
Base URL	`baseUrl`	`COMINTY_BASE_URL`	`https://ds.cominty.com`
Timeout	`timeout`	-	`60000` (milliseconds). Streams are exempt.
Fetch	`fetch`	-	the global `fetch`
Browser	`dangerouslyAllowBrowser`	-	`false`

Resolution order is explicit option → environment variable → default. The SDK does not load .env files. Export the variables, or run node --env-file=.env app.mjs.

const client = new Cominty({ apiToken: 'sk-cmt-...', userId: 'user_...', timeout: 10_000 })

apiToken and COMINTY_API_KEY hold the key string exactly as the platform gave it to you, sk-cmt-... included. A missing key or user id, or a malformed user id, throws a plain Error when you build the client. A wrong or archived key comes back as a 403 and throws PermissionError. For the detail text of each case, see Authentication errors.

Quickstart

Guides

Use cases

Reference

GitHub

API reference

​Install

​Authenticate

​Your first call

​Core concepts

​Configuration

Install

Authenticate

Your first call

Core concepts

Configuration