Typed from the committed Classic OpenAPI snapshot, shipped as ESM and CommonJS, and used by existing org-scoped integrations on the original Amigo backend at api.amigo.ai.

Classic Backend Context

@amigo-ai/sdk targets the original org-scoped Amigo backend. Existing deployments still use this surface for conversations, services, organizations, users, agents, context graphs, webhooks, and streaming events.

Product Status

@amigo-ai/sdk remains the supported TypeScript client for the Classic API.

The Platform API is where new workspace-scoped capabilities land first, but the Classic API is not being switched off abruptly. Amigo will publish a migration path, compatibility notes, and upgrade guidance before asking customers to move production workloads.

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/platform-sdk |

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

Before making requests, obtain Classic organization credentials and a user authorized to read the target resources. Keep API keys in server-side environment variables or a secret manager. The examples below read conversation data; they require access to an existing organization.

For the 2.0.0 generated-model changes, review the current SDK upgrade guidance and recheck the package registry when choosing a version.

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))

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 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

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.