Reference

import { Cominty, type Message, type MessageParams } from '@cominty-ai/sdk'

​

Client

new Cominty({
    userId,                  // required (option or COMINTY_USER_ID), validated locally
    apiToken,                // required (option or COMINTY_API_KEY)
    baseUrl,                 // default https://ds.cominty.com (or COMINTY_BASE_URL)
    timeout,                 // milliseconds, default 60000; streams are exempt
    fetch,                   // default: the global fetch
    dangerouslyAllowBrowser, // default false
})

• userId is mandatory, validated at construction (^user_[A-Za-z0-9]{20,}$). Chat and thread requests send it. Memory requests do not. Resource methods never take userId.
• A missing key or user id, a malformed user id, or a browser without dangerouslyAllowBrowser throws a plain Error, not a ComintyError. These are configuration mistakes to fix.
• The client holds no persistent connection. client.close() aborts every request and stream in flight. await using client = new Cominty() calls it when the client goes out of scope. A closed client stays closed: every later call throws APIConnectionError (client closed). Create a new client to continue.
• Properties: client.userId, client.baseUrl.
• Resources: client.chat, client.threads, client.memory, client.mcp, client.agents, client.skills, client.sources, client.documents. The last five do not send userId either.

​

Resources

​

client.chat

• message is at most 30,000 characters. fileIds holds at most 5 ids.
• start returns a StartedChat, a run whose .thread is always set. threadCapabilities is optional and only accepted here. Passing it to send throws InvalidParams. messageScope is accepted by both. See Capabilities.
• maxSteps caps the tool rounds of one message. See maxSteps below and Limiting agent steps.
• send returns an AssistantRun whose .thread is undefined. You hold the threadId, and threads.get fetches the rest. Use it to answer the agent’s questions. Read the previous message to the end, or cancel it, before you call send: see One message at a time.
• Invalid arguments throw InvalidParams before any request is sent, naming every bad argument at once.
• signal cancels the request and the run’s stream. It only closes your connection: the agent keeps running on the server. To stop the agent, call cancel.

​

Stop a message

​

Export a message: export

​

Upload and download files

• filename is 1 to 255 characters and cannot contain /.
• mimetype is optional. Left out, it is the Blob’s type, then a guess from the file name, then application/octet-stream.
• A file is at most 500 MiB (UPLOAD_MAX_BYTES). A bigger one throws InvalidParams before anything is sent.
• The client’s timeout applies to each of the three requests of an upload.

​

maxSteps

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

try {
    await client.chat.start({ agentId: AGENT_ID, message: 'hi', maxSteps: 0 })
} catch (error) {
    if (!(error instanceof InvalidParams)) throw error
    console.log(error.message)
}

​

client.threads

​

client.memory

• list() with no filter returns every file visible to the API key. Pass namespace to keep one namespace. Without it, the same path can appear once per namespace, so key a file by both.
• create throws ConflictError if the path already exists in the namespace.
• purpose is 1 to 100 characters once trimmed, and content is at most 1 MiB. The API checks these and answers with an APIError.
• Thread, ThreadSummary, and Message do not expose the thread’s namespace.

​

client.mcp

• enabled: true (the default) keeps the servers that are turned on. enabled: false keeps the ones that are off. enabled: null returns every server, in API order. The API returns all of them, and the SDK filters on is_enabled.
• name is the value to store in mcp.connections, in threadCapabilities, messageScope, or an agent’s capabilities.
• origin is 'builtin' or 'remote', and scope is 'organization' or 'user', today. Both are plain strings, and other values may appear.
• requires_oauth_connect is true when someone must connect the integration with OAuth on the platform first. connection_status (for example 'connected') is present when known.
• If the manifest cannot be loaded, the API answers 500 and the SDK throws ServerError.

​

client.agents

• scope is 'private' (the default, the key owner only) or 'organization' (every member). The type is Scope.
• update is partial: only the fields you pass are sent. A capabilities object is merged capability by capability: each one you pass replaces the stored one, the others stay.
• An agent’s capabilities come back in the camelCase shape you pass, so a read can go straight back into update. A capability this SDK version does not know is left out of the read, and the API keeps it on update.
• create({ modelIds }) sets the model chain. Leave it out for the organization’s default chain. The chain is a failover order.
• On a built-in agent (managed is true), setModels changes the chain of the whole organization for that agent. update and delete throw NotFoundError.
• list() returns the built-in agents, the organization agents, and the key owner’s private agents. It returns AgentSummary: no instructions, no models. Call get for the full AgentDetail.
• Use capabilities (capabilities.memory sets the namespace), not the legacy execution_options and memory_namespace fields of a read.
• delete is permanent. The API answers 204, and the SDK resolves with undefined.

​

client.skills

• a zip archive (Blob, File, ArrayBuffer, Uint8Array), sent as it is;
• a SkillFiles object: the skill’s files by /-separated path, with SKILL.md at the root. Values are strings (written as UTF-8) or bytes. The SDK zips them in memory and leaves out entries with a path part starting with ..

const skill = await client.skills.create(
    { 'SKILL.md': '---\nname: haiku-replies\ndescription: Answer as a haiku.\n---\n' },
    { displayName: 'Haiku replies' },
)

​

client.sources

• create makes a drive, uploads each file through a presigned URL, then creates a private drag-and-drop source over it. Files upload one after the other. If a step fails, the source is not created.
• source.pid (a string) goes to every method here. source.id (a number) goes to indexedDocuments.sourceIds in threadCapabilities, messageScope, or an agent’s capabilities.
• list() returns the organization’s sources and the ones the key created, archived ones included.
• get(pid) reads the list and picks, so it costs a list().
• addFiles and removeFile request a sync when the source accepts one (synced, error, out_of_sync, daily_quota_reached). The 50-file cap counts the files already in the source.
• downloadFile fetches a presigned URL valid 5 minutes, then the bytes. The whole file is held in memory.
• waitSynced reads the source every interval (default 5000) milliseconds, for at most timeout (default 600000, 10 minutes) milliseconds. A timeout does not stop the sync: wait again to keep following it.
• archive is terminal. It removes the indexed documents and the files, and the source stays listed with status === 'archived'.
• Only drag-and-drop sources can be created with a key.

​

client.documents

​

The run handle

​

One message at a time

for await (const event of run) {
    if (userClickedStop()) {
        await client.chat.cancel(run.messageId)
        break // closes the stream
    }
}

const thread = await client.threads.get(threadId)
for (const message of thread.messages) {
    if (message.live) {
        await client.chat.stream(message.id).result() // drains it, or cancel it
    }
}

const reply = await client.chat.send(threadId, { agentId: AGENT_ID, message: 'Next question' })

​

Resume a dropped stream

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

let lastEventId: string | undefined
for (let attempt = 1; ; attempt++) {
    const run = client.chat.stream(messageId, { lastEventId })
    try {
        for await (const event of run) console.log(event.name)
        console.log(await run.text())
        break
    } catch (error) {
        if (!(error instanceof APIConnectionError) || attempt >= 5) throw error
        lastEventId = run.lastEventId ?? lastEventId
        await new Promise((resolve) => setTimeout(resolve, 1000 * attempt))
    }
}

​

Relay progress to a browser

// Any runtime with web-standard Request/Response: Next.js, Hono, Bun, Deno...
export async function POST(request: Request): Promise<Response> {
    const { message } = await request.json()
    const run = await client.chat.start({ agentId: AGENT_ID, message, signal: request.signal })

    const encoder = new TextEncoder()
    const send = (event: string, data: unknown) =>
        encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)

    const body = new ReadableStream<Uint8Array>({
        async start(controller) {
            try {
                for await (const event of run) controller.enqueue(send('progress', event))
                controller.enqueue(send('done', await run.result()))
            } catch (error) {
                controller.enqueue(send('error', { message: (error as Error).message }))
            } finally {
                controller.close()
            }
        },
        cancel: () => run.close(),
    })

    return new Response(body, {
        headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' },
    })
}

​

Data types

​

Capabilities

import { ALL, type AgentCapabilities, type MessageScope } from '@cominty-ai/sdk'

const threadCapabilities: AgentCapabilities = {
    web: { activation: 'always' },
    indexedDocuments: { activation: 'always', sourceIds: [101] }, // documentIds: ALL
    mcp: { activation: 'on_request', connections: ALL },
    memory: { activation: 'always', namespace: 'support-bot' },
}
const messageScope: MessageScope = { mcp: { enabled: true, connections: ['linear'] } }

​

AgentCapabilities

​

MessageScope

​

ALL and filters

​

Memory

​

Validation errors

​

Streamed events

• The result event is not the end of the stream. More events can follow it. The stream ends when the final message arrives, which is when your for await loop exits.
• event.data.cost holds total, input_cost, and output_cost as decimal strings, plus token counts. Keep them as strings, or use a decimal library: converting to number loses precision when you add them up.

​

Errors

ComintyError
├── APIError              # HTTP 4xx/5xx. .status, .detail, .body, .headers
│   ├── AuthError         # 401
│   ├── PermissionError   # 403
│   ├── NotFoundError     # 404
│   ├── ConflictError     # 409
│   ├── RateLimitError    # 429
│   └── ServerError       # 5xx
├── APIConnectionError    # network error / timeout (no response). .cause
├── StreamInterrupted     # server shut down mid-stream. .partial: Message
├── SourceSyncFailed      # a source did not reach "synced". .source: Source
├── SourceSyncTimeout     # waitSynced ran out of time. .source: Source | null
├── InvalidParams         # client-side validation failed. .errors: InvalidParam[]
└── SDKError              # unexpected state, or a run consumed twice

• A configuration mistake in new Cominty() throws a plain Error.
• Aborting your own AbortSignal throws the standard AbortError.

​

RateLimitError

• scope → 'organization' | 'user' | 'concurrency' | null
• retryAfter → seconds (from the Retry-After header), or null
• resetAt → a Date (from reset_at / X-RateLimit-Reset), or null

• Organization rate limit reached: your organization’s total request quota is exhausted. Ask an organization admin to raise your plan’s limit.
• User rate limit reached: your user request quota is exhausted. Ask an organization admin to raise your plan’s limit.
• Too many concurrent requests: your plan’s limit on simultaneous chat sessions is reached. Wait for an in-flight request to finish and retry, or raise the limit. Ask an organization admin to raise your plan’s limit.