Docs/SDKs

Official SDKs

Integrate Klarora into your applications with our official JavaScript/TypeScript, Python, and Go SDKs. Each SDK provides a type-safe, idiomatic interface for your preferred language and authenticates with an API key.

Quick Start

Choose your language and install the SDK:

JavaScript / TypeScript

npm install @kairos-connect/sdk

Python

pip install kairos-sdk

go get github.com/moemollaei-org/kairos-connect-sdks/go

Choose Your SDK

JavaScript / TypeScript

Official JavaScript/TypeScript SDK for Node.js and browser environments with full TypeScript support. Works with npm, yarn, pnpm, and Bun.

TypeScript definitionsPromise-based APIZero dependenciesBrowser & Node.js

@kairos-connect/sdk

Python

Official Python SDK with an async client, a synchronous client, and Pydantic models for modern Python applications.

Type hintsAsync and sync clientsPydantic modelsPython 3.9+

kairos-sdk

Go

Official Go SDK: an idiomatic client built on the standard library, with strongly-typed interfaces and context support.

Context supportStrongly typedZero dependenciesGo 1.21+

github.com/moemollaei-org/kairos-connect-sdks/go

Authentication

All three SDKs authenticate with an API key (keys look like kairos_sk_...). Pass the key to the client, or leave it out (in Go, pass an empty string) and set the KAIROS_API_KEY environment variable. The default base URL is https://gateway.thekairos.app/v1.

Common Interface

All SDKs expose the same six resources and use each language's naming conventions (shown here in TypeScript):

// Initialize the client
const kairos = new Kairos({ apiKey: 'YOUR_API_KEY' });

// Resources available
kairos.tasks       // Tasks API (plus labels and comments)
kairos.goals       // Goals API (plus tasks and comments)
kairos.team        // Team API: get() and listMembers(teamId)
kairos.documents   // Documents API
kairos.whiteboards // Whiteboards API
kairos.forms       // Forms API (plus submissions)

// Validate your API key and see its scopes
kairos.me()

// Common methods on tasks, goals, documents, whiteboards and forms
kairos.tasks.list(options?)     // Paginated list
kairos.tasks.get(id)            // Get single resource
kairos.tasks.create(data)       // Create resource
kairos.tasks.update(id, data)   // Update resource
kairos.tasks.delete(id)         // Delete resource

Pagination

List methods return a page of results together with pagination details (page, limit, total, and has_more). The JavaScript and Go SDKs page with limit and offset; the Python SDK pages with page and limit.

// JavaScript / TypeScript
const result = await kairos.tasks.list({ limit: 50, offset: 0 });

console.log(result.data);                // Array of tasks
console.log(result.pagination.page);     // Current page
console.log(result.pagination.total);    // Total count
console.log(result.pagination.has_more); // More pages?

if (result.pagination.has_more) {
  const nextPage = await kairos.tasks.list({ limit: 50, offset: 50 });
}

# Python
result = await kairos.tasks.list(page=1, limit=50)

print(result.pagination.total)
if result.pagination.has_more:
    next_page = await kairos.tasks.list(page=result.pagination.page + 1, limit=50)

// Go
tasks, pagination, err := client.Tasks.List(ctx, &kairos.ListTasksOptions{
    ListOptions: kairos.ListOptions{Limit: 50},
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(len(tasks), pagination.Total)
if pagination.HasMore {
    nextTasks, _, err := client.Tasks.List(ctx, &kairos.ListTasksOptions{
        ListOptions: kairos.ListOptions{Limit: 50, Offset: 50},
    })
    _, _ = nextTasks, err
}

Error Handling

The JavaScript and Python SDKs throw typed errors that you can catch and handle. Both export KairosError as the base class, with AuthError, ForbiddenError, NotFoundError, ValidationError, RateLimitError, and InternalError as subclasses. The Go SDK returns a *kairos.KairosError with helper functions such as kairos.IsNotFoundError(err).

// JavaScript / TypeScript
import {
  NotFoundError,
  ValidationError,
  RateLimitError,
  AuthError,
} from '@kairos-connect/sdk';

try {
  const task = await kairos.tasks.get('invalid-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Task not found');
  } else if (error instanceof ValidationError) {
    console.log('Invalid request:', error.message);
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof AuthError) {
    console.log('Invalid API key');
  }
}

# Python
from kairos import NotFoundError, RateLimitError

try:
    task = await kairos.tasks.get("invalid-id")
except NotFoundError:
    print("Task not found")
except RateLimitError as e:
    print(f"Rate limited, retry after: {e.retry_after} seconds")

// Go
task, err := client.Tasks.Get(ctx, "invalid-id")
if kairos.IsNotFoundError(err) {
    fmt.Println("Task not found")
} else if kairos.IsRateLimitError(err) {
    fmt.Println("Rate limited")
} else if kairos.IsAuthError(err) {
    fmt.Println("Invalid API key")
}
_ = task

Documents API JavaScript SDK

Docs/SDKs

Official SDKs

Quick Start

Choose your language and install the SDK:

JavaScript / TypeScript

npm install @kairos-connect/sdk

Python

pip install kairos-sdk

go get github.com/moemollaei-org/kairos-connect-sdks/go

Choose Your SDK

JavaScript / TypeScript

Official JavaScript/TypeScript SDK for Node.js and browser environments with full TypeScript support. Works with npm, yarn, pnpm, and Bun.

TypeScript definitionsPromise-based APIZero dependenciesBrowser & Node.js

@kairos-connect/sdk

Python

Official Python SDK with an async client, a synchronous client, and Pydantic models for modern Python applications.

Type hintsAsync and sync clientsPydantic modelsPython 3.9+

kairos-sdk

Go

Official Go SDK: an idiomatic client built on the standard library, with strongly-typed interfaces and context support.

Context supportStrongly typedZero dependenciesGo 1.21+

github.com/moemollaei-org/kairos-connect-sdks/go

Authentication

Common Interface

All SDKs expose the same six resources and use each language's naming conventions (shown here in TypeScript):

// Initialize the client
const kairos = new Kairos({ apiKey: 'YOUR_API_KEY' });

// Resources available
kairos.tasks       // Tasks API (plus labels and comments)
kairos.goals       // Goals API (plus tasks and comments)
kairos.team        // Team API: get() and listMembers(teamId)
kairos.documents   // Documents API
kairos.whiteboards // Whiteboards API
kairos.forms       // Forms API (plus submissions)

// Validate your API key and see its scopes
kairos.me()

// Common methods on tasks, goals, documents, whiteboards and forms
kairos.tasks.list(options?)     // Paginated list
kairos.tasks.get(id)            // Get single resource
kairos.tasks.create(data)       // Create resource
kairos.tasks.update(id, data)   // Update resource
kairos.tasks.delete(id)         // Delete resource

Pagination

// JavaScript / TypeScript
const result = await kairos.tasks.list({ limit: 50, offset: 0 });

console.log(result.data);                // Array of tasks
console.log(result.pagination.page);     // Current page
console.log(result.pagination.total);    // Total count
console.log(result.pagination.has_more); // More pages?

if (result.pagination.has_more) {
  const nextPage = await kairos.tasks.list({ limit: 50, offset: 50 });
}

# Python
result = await kairos.tasks.list(page=1, limit=50)

print(result.pagination.total)
if result.pagination.has_more:
    next_page = await kairos.tasks.list(page=result.pagination.page + 1, limit=50)

// Go
tasks, pagination, err := client.Tasks.List(ctx, &kairos.ListTasksOptions{
    ListOptions: kairos.ListOptions{Limit: 50},
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(len(tasks), pagination.Total)
if pagination.HasMore {
    nextTasks, _, err := client.Tasks.List(ctx, &kairos.ListTasksOptions{
        ListOptions: kairos.ListOptions{Limit: 50, Offset: 50},
    })
    _, _ = nextTasks, err
}

Error Handling

// JavaScript / TypeScript
import {
  NotFoundError,
  ValidationError,
  RateLimitError,
  AuthError,
} from '@kairos-connect/sdk';

try {
  const task = await kairos.tasks.get('invalid-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Task not found');
  } else if (error instanceof ValidationError) {
    console.log('Invalid request:', error.message);
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof AuthError) {
    console.log('Invalid API key');
  }
}

# Python
from kairos import NotFoundError, RateLimitError

try:
    task = await kairos.tasks.get("invalid-id")
except NotFoundError:
    print("Task not found")
except RateLimitError as e:
    print(f"Rate limited, retry after: {e.retry_after} seconds")

// Go
task, err := client.Tasks.Get(ctx, "invalid-id")
if kairos.IsNotFoundError(err) {
    fmt.Println("Task not found")
} else if kairos.IsRateLimitError(err) {
    fmt.Println("Rate limited")
} else if kairos.IsAuthError(err) {
    fmt.Println("Invalid API key")
}
_ = task

Documents API JavaScript SDK