SDK Overview

SDK is in preview. The server endpoints targeted by client.workspace.*, client.skills.*, and client.mcp.* are not yet implemented. Only client.chat() maps to a live endpoint. The SDK API shown here reflects the planned surface; do not use these methods in production until the endpoints ship.

The Cosmo SDK (@cosmohq/sdk) is a lightweight TypeScript client for the Cosmo REST API. Use it to integrate Cosmo into your own scripts, automations, or applications — chat with AI, manage workspaces, run skills, and call MCP tools programmatically.

What the SDK covers (planned)

Namespace	What you can do
`client.chat()`	Send messages to the AI engine
`client.workspace.*`	Read, write, and list workspace files
`client.skills.*`	List and run built-in or org skills
`client.mcp.*`	List connected MCP servers and call their tools

What the SDK does not cover

The SDK is a public API surface — it does not expose every server endpoint. For direct API access (billing, metering, admin, org management, workspace ordering), use the REST API directly.

The SDK also does not implement streaming chat. Chat responses are returned as a single resolved value, not a stream. For streaming, call the POST /chat endpoint directly and consume the SSE response — see Streaming API.

Installation

npm install @cosmohq/sdk

Quick start

import { CosmoClient } from '@cosmohq/sdk'

const client = new CosmoClient({
  apiKey: process.env.COSMO_API_KEY!,
  org: 'your-org-slug',
})

const response = await client.chat('What tasks are due this week?')
console.log(response)

Error handling

All SDK methods throw CosmoAPIError on non-2xx responses:

import { CosmoClient, CosmoAPIError } from '@cosmohq/sdk'

try {
  const files = await client.workspace.list()
} catch (err) {
  if (err instanceof CosmoAPIError) {
    console.error(`API error ${err.status}: ${err.message}`)
  }
}

Next steps

Installation — install and configure the SDK
Authentication — API keys and org slugs
Examples — common usage patterns