Typed from the Amigo OpenAPI schemas, shipped as ESM and CommonJS, and used by existing org-scoped integrations on the original Amigo backend at api.amigo.ai plus new workspace-scoped integrations on api.platform.amigo.ai.

Backend Context

The root package export targets the original org-scoped Classic API. Existing deployments still use this surface for conversations, services, organizations, users, agents, context graphs, webhooks, and streaming events.

The @amigo-ai/sdk/platform subpath targets the Platform API. It includes a raw OpenAPI-typed fetch client, workspace-scoped resources, SSE helpers for streaming turns and workspace events, and WebSocket helpers for public text sessions.

Product Status

@amigo-ai/sdk remains the supported TypeScript client for the Classic API and now also ships the Platform API client from the @amigo-ai/sdk/platform subpath.

The Platform API is where new workspace-scoped capabilities land first, but the Classic API is not being switched off abruptly. The root export continues to target the current org-scoped API, while new Platform integrations can use the platform subpath from the same package.

Choose The Right SDK

| If you need | Start here | | ------------------------------------------------------------ | ------------------------- | | Existing org-scoped integrations on api.amigo.ai | @amigo-ai/sdk | | New workspace-scoped integrations on api.platform.amigo.ai | @amigo-ai/sdk/platform |

Documentation

| Need | Best entry point | | --------------------------------------- | ------------------------------------------------------------------------------------------- | | Product overview and deployment context | docs.amigo.ai | | Integration guidance and developer docs | Developer Guide | | Generated API reference | amigo-ai.github.io/amigo-typescript-sdk | | Runnable examples | examples/ | | Release history | CHANGELOG.md |

The docs site remains the primary reference. The repo-local examples stay close to the shipped package surface and are validated in CI.

Installation

npm install @amigo-ai/sdk

Classic Quick Start

import { AmigoClient } from '@amigo-ai/sdk'

const client = new AmigoClient({
  apiKey: 'your-api-key',
  apiKeyId: 'your-api-key-id',
  userId: 'user-id',
  orgId: 'your-organization-id',
})

const conversations = await client.conversations.getConversations({
  limit: 10,
  sort_by: ['-created_at'],
})

console.log(conversations.conversations.map(conversation => conversation.id))

Platform Quick Start

import { PlatformClient } from '@amigo-ai/sdk/platform'

const platform = new PlatformClient({
  apiKey: 'your-platform-api-key',
  workspaceId: 'your-workspace-id',
})

const agents = await platform.agents.list({ query: { limit: 10 } })
console.log(agents.items.map(agent => agent.id))

Configuration

| Option | Type | Required | Description | | ---------- | -------------- | -------- | ------------------------------------------------------------- | | apiKey | string | Yes | API key from the Amigo dashboard | | apiKeyId | string | Yes | API key ID paired with apiKey | | userId | string | Yes | User ID on whose behalf the request is made | | orgId | string | Yes | Organization ID for the Classic API | | baseUrl | string | No | Override the API base URL. Defaults to https://api.amigo.ai | | retry | RetryOptions | No | Retry policy overrides for transient HTTP failures |

Runtime Requirements

The SDK supports Node 18+ and is tested on active Node releases in CI. It relies on web-standard primitives such as fetch, AbortController, URL, and TextEncoder.

Generated Types

The package re-exports the generated OpenAPI types so application code can type directly against the API contract:

import type { components, operations, paths } from '@amigo-ai/sdk'

type Conversation = components['schemas']['ConversationInstance']
type GetConversationsQuery = operations['get-conversations']['parameters']['query']

Public Classic builds are generated from the committed specs/openapi-baseline.json snapshot in this repo so type output stays deterministic across machines and CI runs. When you need to refresh that snapshot, run:

npm run openapi:sync

Platform OpenAPI types are exported from the platform subpath:

import type { components, operations, paths } from '@amigo-ai/sdk/platform'

type PlatformAgent = components['schemas']['AgentResponse']
type ListAgentsQuery = operations['list-agents']['parameters']['query']

Retries

The HTTP client retries transient failures with sensible defaults:

• Max attempts: 3
• Backoff base: 250ms with full jitter
• Max delay per attempt: 30s
• Statuses: 408, 429, 500, 502, 503, 504
• Methods: GET, plus POST on 429 when Retry-After is present

Error Handling

import { AmigoClient, AuthenticationError, NetworkError } from '@amigo-ai/sdk'

try {
  const client = new AmigoClient({
    apiKey: 'your-api-key',
    apiKeyId: 'your-api-key-id',
    userId: 'user-id',
    orgId: 'your-organization-id',
  })

  await client.organizations.getOrganization()
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message)
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message)
  } else {
    console.error('Unexpected error:', error)
  }
}

Support

Use the issue tracker for bugs and feature requests. For responsible disclosure, see SECURITY.md.