@amigo-ai/sdk

Official TypeScript SDK for the Classic Amigo API.

Product Docs · Developer Guide · API Reference · Examples · Changelog

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
Copy

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

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']
Copy

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
Copy

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

Support

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