> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cominty.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK

> Fully-typed TypeScript and JavaScript client for the Cominty chat API, with zero dependencies

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](https://docs.cominty.ai/guides/memory-namespaces.md).

It is written in TypeScript and works from plain JavaScript too. It tracks the
same API as the [Python SDK](https://docs.cominty.ai/sdk/overview.md).

> [card] [Quickstart](https://docs.cominty.ai/js-sdk/quickstart.md)
>
> Task-by-task examples, most with a runnable script on GitHub.

> [card] [Guides](https://docs.cominty.ai/guides/capabilities.md)
>
> Concepts behind capabilities, memory namespaces, and tool-round caps.

> [card] [Use cases](https://docs.cominty.ai/guides/capabilities-use-cases.md)
>
> Recipes that show what a capability changes.

> [card] [Reference](https://docs.cominty.ai/js-sdk/reference.md)
>
> Every resource, type, event, and error.

> [card] [GitHub](https://github.com/cominty/js-sdk)
>
> Source, issues, and the full `examples/` directory.

> [card] [API reference](https://docs.cominty.ai/api-reference.md)
>
> The HTTP endpoints the SDK calls, with a live playground.

> [!NOTE]
>
> **Package** `@cominty-ai/sdk` ([![npm](https://img.shields.io/npm/v/@cominty-ai/sdk.svg)](https://www.npmjs.com/package/@cominty-ai/sdk)) ·
> **runtime** Node 20+, Bun, Deno, edge workers · **module** ESM only, types
> included · **dependencies** none (native `fetch` and `ReadableStream`).

## Install

```bash theme={null}
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')`.

> [!WARNING]
>
> **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](https://docs.cominty.ai/js-sdk/reference.md#relay-progress-to-a-browser).

## Authenticate

You need two credentials, both from [platform.cominty.ai](https://platform.cominty.ai):

**1. 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.

**2. Get your user id**

Open your avatar → **Profile**. It looks like
`user_31HPTBuBvX20xlQNAbvxjOxPbKB`.

**3. Export both**

```bash theme={null}
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](https://platform.cominty.ai/agents)
(for example `__cominty_agents::agent.chat`). See
[Built-in agents](https://docs.cominty.ai/guides/agents.md) for what Chat, Hive, and Planner can do.

## Your first call

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

```ts theme={null}
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

> [accordion] 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](https://docs.cominty.ai/js-sdk/reference.md#client) for all settings.

> [accordion] 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](https://docs.cominty.ai/guides/memory-namespaces.md) and
> [Resources](https://docs.cominty.ai/js-sdk/reference.md#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](https://docs.cominty.ai/guides/custom-agents.md),
> [Skills](https://docs.cominty.ai/guides/skills.md), and [Sources](https://docs.cominty.ai/guides/sources.md).

> [accordion] 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](https://docs.cominty.ai/guides/custom-agents.md#what-an-api-key-can-do).

> [accordion] 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](https://docs.cominty.ai/js-sdk/reference.md#the-run-handle).

> [accordion] 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](https://docs.cominty.ai/guides/capabilities.md) and the
> [reference](https://docs.cominty.ai/js-sdk/reference.md#capabilities).
>
> > [!NOTE]
> >
> > `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`.

```ts theme={null}
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](https://docs.cominty.ai/api-reference.md#authentication-errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.