Typed from the committed openapi.json snapshot, validated on active LTS Node releases (20, 22, and 24), and tested as packaged ESM and CommonJS tarballs before release.

Platform context

The SDK is the typed client boundary between your runtime and the workspace-scoped Platform API. The API then fronts the platform systems that power agents, actions, calls, analytics, world state, connectors, and webhooks.

Documentation

| Need | Best entry point | | ------------------------------------------- | ---------------------------------------------------------------------------------- | | Product architecture and deployment context | docs.amigo.ai | | Tutorials and integration guidance | Developer Guide | | Endpoint-by-endpoint REST reference | API Reference | | Repo-local SDK examples | examples/README.md | | Generated package surface | api.md | | Published release history | CHANGELOG.md |

Guides

| Guide | Description | | ------------------------------------------------------------ | --------------------------------------------------------------- | | Build a Custom Patient Form | Create, deliver, and render patient intake forms using surfaces |

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

Installation

npm install @amigo-ai/platform-sdk

Quick start

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

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

// List agents
const { items: agents } = await client.agents.list({ limit: 10 })
console.log(agents.map((agent) => agent.name))

// Search entities in the world model
const entityResults = await client.world.listEntities({
  q: 'Jane Doe',
  entity_type: ['patient'],
  limit: 5,
})
console.log(entityResults.entities[0]?.display_name)

// Get call analytics for the last 30 days
const stats = await client.analytics.getCalls({ days: 30 })
console.log(stats.total_calls, stats.avg_duration_seconds)

Authentication

API key (server-to-server)

Pass apiKey and workspaceId to AmigoClient. Best for backend services and scripts.

Device code flow (CLI and desktop apps)

For interactive apps where users sign in via the browser, use loginWithDeviceCode:

import {
  loginWithDeviceCode,
  openBrowser,
  formatDeviceCodeInstructions,
  TokenManager,
  FileTokenStorage,
} from '@amigo-ai/platform-sdk'

const result = await loginWithDeviceCode({
  onCode: async (issuance) => {
    console.log(formatDeviceCodeInstructions(issuance))
    await openBrowser(issuance.verification_uri_complete)
  },
  onWorkspaceRequired: async (workspaces) => {
    // Prompt user to pick a workspace
    return workspaces[0].workspace_id
  },
})

// Persist credentials across runs
const tokens = new TokenManager({ storage: new FileTokenStorage() })
await tokens.store(result)

// Use the token
const client = new AmigoClient({ apiKey: result.accessToken, workspaceId: result.workspaceId })

See examples/auth/device-code-login.ts for a complete working example.

Configuration

| Option | Type | Required | Description | | ------------- | -------------- | -------- | -------------------------------------------------------------------- | | apiKey | string | Yes | API key or JWT from device code flow (Bearer auth) | | workspaceId | string | Yes | Your workspace ID — all resource operations are scoped to this | | baseUrl | string | No | Override the API base URL (default: https://api.platform.amigo.ai) | | retry | RetryOptions | No | Retry configuration for transient failures | | maxRetries | number | No | Convenience alias for retry count | | timeout | number | No | Default request timeout in milliseconds | | headers | HeadersInit | No | Default headers added to every request | | hooks | ClientHooks | No | Request/response lifecycle hooks for tracing or logging | | fetch | typeof fetch | No | Custom fetch for BFF proxy, cookie forwarding, or test mocking |

Retry options

const client = new AmigoClient({
  apiKey: 'your-key',
  workspaceId: 'your-workspace-id',
  retry: {
    maxAttempts: 3, // Total attempts including first. Default: 3
    baseDelayMs: 250, // Base delay for exponential backoff. Default: 250
    maxDelayMs: 30000, // Cap on delay. Default: 30_000
  },
})

GET requests are retried on 408, 429, 500, 502, 503, 504. POST requests are only retried on 429 with a Retry-After header. Backoff uses full jitter.

Runtime requirements

The SDK is built around web-standard primitives. Use it in runtimes that provide:

• fetch, Request, Response, Headers, URL
• AbortController
• TextEncoder / TextDecoder
• crypto.subtle for webhook signature verification

CI currently validates active LTS Node releases. Standards-based edge/server runtimes with the same APIs work well with the low-level request wrappers.

Generated Types

The SDK ships with generated OpenAPI types and re-exports them for direct use:

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

type Agent = components['schemas']['AgentResponse']
type ListAgentsQuery = operations['list_agents_v1__workspace_id__agents_get']['parameters']['query']

Public builds are generated from the committed openapi.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

For a repo-local overview of the exported client surface, see the generated api.md.

Advanced request control

The normal resource surface supports scoped request overrides, so you can keep the ergonomic API while adding timeout, retry, and header controls:

const agents = await client
  .withOptions({
    timeout: 5_000,
    maxRetries: 1,
    headers: { 'X-Debug-Trace': 'true' },
  })
  .agents.list({ limit: 10 })

console.log(agents._request_id)
console.log(agents.lastResponse.statusCode)
console.log(agents.items)

You can scope options to a single resource as well:

const agent = await client.agents.withOptions({ timeout: 2_000 }).get('agent-id')

For lower-level control, use the built-in typed HTTP helpers. Workspace-scoped routes automatically receive your configured workspaceId, and the configured value wins if workspace_id is provided manually.

const result = await client.GET('/v1/{workspace_id}/agents', {
  params: { query: { limit: 10 } },
  timeout: 5_000,
  maxRetries: 1,
  headers: { 'X-Debug-Trace': 'true' },
})

console.log(result.requestId)
console.log(result.data.items)
console.log(result.rateLimit.remaining)

Available helpers:

• client.GET(...)
• client.POST(...)
• client.PUT(...)
• client.PATCH(...)
• client.DELETE(...)
• client.HEAD(...)
• client.OPTIONS(...)
• client.withOptions(...)
• client.<resource>.withOptions(...)

Response metadata

Object responses from resource methods include non-enumerable request metadata:

const agent = await client.agents.get('agent-id')

console.log(agent._request_id)
console.log(agent.lastResponse.statusCode)
console.log(agent.lastResponse.rateLimit.remaining)

Low-level request helpers return the raw Response alongside parsed data:

const { data, response, requestId } = await client.GET('/v1/{workspace_id}/agents')

console.log(requestId)
console.log(response.headers.get('content-type'))
console.log(data.items)

Request hooks

Use hooks for logging, tracing, and metrics without wrapping fetch yourself:

const client = new AmigoClient({
  apiKey: 'your-api-key',
  workspaceId: 'your-workspace-id',
  hooks: {
    onRequest({ request, schemaPath }) {
      console.log('request', request.method, schemaPath)
    },
    onResponse({ response, requestId }) {
      console.log('response', response.status, requestId)
    },
  },
})

Resources

Agents

// Create an agent
const agent = await client.agents.create({
  name: 'Patient Intake Agent',
  description: 'Handles inbound scheduling calls',
})

// Create a version (the versioned config object)
const version = await client.agents.createVersion(agent.id, {
  name: 'v1',
  identity: {
    name: 'Alex',
    role: 'Scheduling Coordinator',
    developed_by: 'Acme Health',
    default_spoken_language: 'en',
    relationship_to_developer: {
      ownership: 'Acme Health',
      type: 'assistant',
      conversation_visibility: 'public',
      thought_visibility: 'private',
    },
  },
})

// Get the latest version
const latest = await client.agents.getVersion(agent.id, 'latest')

const { items: agents } = await client.agents.list({ search: 'intake' })

Actions

Actions are reusable agent capabilities (formerly "skills").

const action = await client.actions.create({
  slug: 'schedule-appointment',
  name: 'Schedule Appointment',
  description: 'Books appointments in the scheduling system',
  input_schema: {
    type: 'object',
    properties: {
      patient_id: { type: 'string' },
      appointment_type: { type: 'string' },
    },
    required: ['patient_id', 'appointment_type'],
  },
  execution_tier: 'orchestrated',
})

// Test with a sample input
const result = await client.actions.test(action.id, {
  input: { patient_id: 'ID-001', appointment_type: 'follow-up' },
})
console.log(result.result, result.duration_ms)

Services

Services wire together an agent + context graph + phone channel.

const { items: services } = await client.services.list()
const service = await client.services.get('service-id')
console.log(service.agent_name, service.channel_type, service.version_sets)

World Model

The world model tracks entities (patients, contacts, appointments) and the events that flow through them.

// Filter entities with simple list queries
const patients = await client.world.listEntities({
  q: 'Jane Doe',
  entity_type: ['patient'],
  limit: 10,
})
console.log(patients.entities.length)

// Get a single entity
const patient = await client.world.getEntity('entity-id')
console.log(patient.display_name, patient.entity_type)

// Query timeline
const timeline = await client.world.getTimeline('entity-id', { limit: 20 })

// Semantic search over the world model
const results = await client.world.search({
  q: 'Jane Doe',
  entity_type: 'patient',
  limit: 5,
})

// View sync status from connectors
const syncStatus = await client.world.getSyncStatusBySink()

Calls

Calls are read-only — they are created by the voice pipeline.

const { items: calls } = await client.calls.list({
  direction: 'inbound',
  service_id: 'service-id',
})

// Get full detail with transcript and intelligence
const detail = await client.calls.get(calls[0].call_sid)
console.log(detail.intelligence?.summary)
console.log(detail.transcript)

// Analytics benchmarks
const benchmarks = await client.calls.getBenchmarks({ days: 30 })

Text conversations

Use client.conversations.sendMessage() for user-first synchronous text turns. Omit conversation_id to start a new durable conversation; pass the returned ID to resume it.

const firstTurn = await client.conversations.sendMessage({
  service_id: 'service-id',
  message: 'Hello, I need help scheduling',
  entity_id: 'entity-id',
})

const nextTurn = await client.conversations.sendMessage({
  service_id: 'service-id',
  conversation_id: firstTurn.conversation_id,
  message: 'Tuesday morning works',
})

console.log(nextTurn.messages.map((message) => message.text))

For real-time browser clients, build the text-stream URL and use WebSocket subprotocol auth so the token is not placed in the URL:

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

const apiKey = process.env.AMIGO_API_KEY!
const url = client.conversations.textStreamUrl({ serviceId: 'service-id' })
const socket = new WebSocket(url, textStreamAuthProtocols(apiKey))

socket.addEventListener('open', () => {
  socket.send(JSON.stringify({ type: 'message', text: 'Hello' }))
})

If a browser rejects your API key as a WebSocket subprotocol value, use the query-token fallback only in trusted contexts. URL tokens can appear in browser history, server access logs, HTTP proxy logs, and referrer headers:

// WARNING: query tokens can be captured by URL logs and browser history.
const url = client.conversations.textStreamUrl({ serviceId: 'service-id', token: apiKey })
const socket = new WebSocket(url)

Real-time event streams

For workspace-wide events (calls, surfaces, pipeline, operators, channels), use the typed SSE consumer:

const handle = client.events.subscribeToWorkspace({
  onEvent: (event) => {
    switch (event.event_type) {
      case 'call.started':
        console.log('call started:', event.call_sid)
        break
      case 'pipeline.error':
        console.error('pipeline error:', event)
        break
    }
  },
  onError: (err) => console.error('terminal:', err),
  onReconnect: (attempt) => console.warn(`reconnect #${attempt}`),
})

// Later: handle.unsubscribe(); await handle.done

The helper handles automatic reconnect (exp backoff with jitter, server-sent retry: honored), gapless replay via Last-Event-ID, and discriminated-union dispatch. Server emits a structured error frame with a stable code on terminal failures — narrow with the typed error guard:

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

onError: (err) => {
  if (isWorkspaceEventStreamError(err)) {
    if (err.code === 'too_many_streams') {
      // workspace has too many open streams; close another tab
    } else if (err.retryable) {
      // SDK already retried up to maxReconnects; safe to try again later
    }
  }
}

For per-call voice observation (agent_transcript_delta, latency, session_*, participant_*, etc.), use the WebSocket-based observer helper:

const observerHandle = client.observers.subscribe({
  callSid: 'CAxxx',
  token: bearerToken,
  onEvent: (event) => {
    switch (event.type) {
      case 'agent_transcript_delta':
        renderAgentDelta(event.delta)
        break
      case 'session_end':
        showSummary(event)
        break
    }
  },
  onError: (err) => console.error('observer terminal:', err.reason, err.closeCode),
})

Both helpers are built on the shared ReconnectingWebSocket primitive, which maps platform-specific WebSocket close codes (4001 client error, 4029 rate limit, 4403 auth, 4100 token expired) to a typed reason taxonomy and applies an idle watchdog (default 45s) so a half-dead socket forces a reconnect rather than hanging indefinitely. Compose it directly via createReconnectingWebSocket when you need a managed WebSocket outside these resources.

Analytics

// Dashboard KPIs with period-over-period deltas
const dashboard = await client.analytics.getDashboard({ days: 7 })
console.log(dashboard.call_volume.value, dashboard.call_volume.delta_pct)
console.log(dashboard.avg_quality.value)

// Call volume time series
const calls = await client.analytics.getCalls({ days: 30, interval: '1d' })
console.log(calls.total_calls, calls.calls_by_date)

// Per-agent performance
const { agents } = await client.analytics.getAgents({ period: '7d' })

// Compare two periods
const comparison = await client.analytics.compareCallPeriods({
  current_from: '2026-04-01',
  current_to: '2026-04-15',
  previous_from: '2026-03-15',
  previous_to: '2026-03-31',
})

Agent Memory

Agent Memory tracks structured long-term facts about entities across conversations.

// Get all dimension scores for an entity
const dims = await client.memory.getEntityDimensions('entity-id')
console.log(dims.dimensions) // preferences, health_history, etc.

// Get individual facts for a dimension
const facts = await client.memory.getEntityFacts('entity-id', { dimension: 'preferences' })

// Workspace-level memory health
const analytics = await client.memory.getAnalytics()
console.log(analytics.coverage_rate, analytics.total_facts)

Integrations

const { items: integrations } = await client.integrations.list({ enabled: true })

// Test a specific endpoint
const result = await client.integrations.testEndpoint('integration-id', 'geocode', {
  textQuery: '123 Main St, Springfield',
})

Data Sources

const { items: sources } = await client.dataSources.list()
const source = await client.dataSources.get('source-id')
console.log(source.source_type, source.health_status, source.last_sync_at)

Settings

// Voice
const voice = await client.settings.voice.get()
await client.settings.voice.update({ voice_id: 'new-voice-id', speed: 1.1 })

// Retention
const retention = await client.settings.retention.get()
await client.settings.retention.update({ call_recordings_days: 90 })

// Memory dimensions
const memory = await client.settings.memory.get()
console.log(memory.dimensions) // list of configured memory dimensions

Surfaces (Patient Forms)

Surfaces are workspace-scoped form specs for collecting patient data. Create a form, deliver it via SMS or email, and track completion. See the full guide: Build a Custom Patient Form.

// Create a patient intake form
const surface = await client.POST('/v1/{workspace_id}/surfaces', {
  body: {
    entity_id: patientId,
    title: 'New Patient Intake',
    channel: 'sms',
    fields: [
      { key: 'full_name', label: 'Full Name', field_type: 'text', required: true },
      { key: 'date_of_birth', label: 'Date of Birth', field_type: 'date', required: true },
      {
        key: 'allergies',
        label: 'Allergies',
        field_type: 'multiselect',
        options: ['Penicillin', 'Sulfa', 'None'],
      },
    ],
  },
})
console.log(surface.data.url) // Patient-facing token URL

// Deliver via SMS
await client.POST('/v1/{workspace_id}/surfaces/{surface_id}/deliver', {
  params: { path: { surface_id: surface.data.id } },
  body: { channel_address: '+15551234567' },
})

// Track completion
const { data: rates } = await client.GET(
  '/v1/{workspace_id}/analytics/surfaces/completion-rates',
  {},
)

Public token routes (/s/{token}/spec, /s/{token}/submit, etc.) require no API key -- use openapi-fetch with the SDK's paths type for full type safety on unauthenticated endpoints.

Billing

const dashboard = await client.billing.getDashboard()
const usage = await client.billing.getUsage()
const { items: invoices } = await client.billing.listInvoices()
const pdf = await client.billing.getInvoicePdf('invoice-id')

Operators

const { items: operators } = await client.operators.list()
const dashboard = await client.operators.getDashboard()
const queue = await client.operators.getQueue()
const escalations = await client.operators.getActiveEscalations()

// Join/leave calls, switch mode, send guidance
await client.operators.joinCall('operator-id', { call_sid: 'call-sid' })
await client.operators.sendGuidance('operator-id', { text: 'Ask about allergies' })
await client.operators.wrapUp('operator-id', { outcome: 'resolved' })

Triggers (Automations)

const trigger = await client.triggers.create({
  name: 'Daily outreach',
  schedule: '0 9 * * 1-5',
  timezone: 'America/New_York',
  action_id: 'skill-id',
  event_type: 'trigger.scheduled',
  input_template: { campaign: 'follow-up' },
})

await client.triggers.fire(trigger.id)
await client.triggers.pause(trigger.id)
await client.triggers.resume(trigger.id)
const runs = await client.triggers.listRuns(trigger.id)

Review Queue

const stats = await client.reviewQueue.getStats()
const dashboard = await client.reviewQueue.getDashboard()
const { items } = await client.reviewQueue.list({ status: 'pending' })

// Claim, approve, reject, correct
await client.reviewQueue.claim('item-id')
await client.reviewQueue.approve('item-id', { notes: 'Verified correct' })
await client.reviewQueue.reject('item-id', { reason: 'Data mismatch' })
await client.reviewQueue.batchApprove({ item_ids: ['id1', 'id2'] })

Personas

const persona = await client.personas.create({
  name: 'Friendly Scheduler',
  voice_style: 'warm and professional',
})
const { items: personas } = await client.personas.list()

Compliance & Safety

const hipaa = await client.compliance.getHipaa()
const safetyConfig = await client.safety.getConfig()
const templates = await client.safety.listTemplates()

Audit

const { items: events } = await client.audit.list({ limit: 50 })
const summary = await client.audit.getSummary()
await client.audit.createExport({ start_date: '2026-01-01', end_date: '2026-03-31' })

Recordings

const urls = await client.recordings.getUrls('call-sid')
const metadata = await client.recordings.getMetadata('call-sid')

Functions (UC Functions)

const catalog = await client.functions.getCatalog()
const { items: functions } = await client.functions.list()
const result = await client.functions.test('my-function', { input: { query: 'test' } })

Webhook Destinations

const dest = await client.webhookDestinations.create({
  name: 'My Webhook',
  url: 'https://example.com/webhook',
  events: ['call.completed'],
})
const deliveries = await client.webhookDestinations.listDeliveries(dest.id)

Webhook Verification

Use the raw request body when verifying webhook deliveries. Timestamped signatures are replay-protected by default.

import { parseWebhookEvent, WebhookVerificationError } from '@amigo-ai/platform-sdk'

const body = await request.text()

try {
  const event = await parseWebhookEvent({
    payload: body,
    signature: request.headers.get('x-amigo-signature') ?? '',
    timestamp: request.headers.get('x-amigo-timestamp') ?? undefined,
    secret: process.env.AMIGO_WEBHOOK_SECRET!,
  })

  console.log(event.type, event.data)
} catch (error) {
  if (error instanceof WebhookVerificationError) {
    console.error('Rejected webhook:', error.message)
  } else {
    throw error
  }
}

If your delivery channel only provides a legacy HMAC without a timestamp, the original helper signature still works:

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

const event = await parseWebhookEvent(rawBody, signature, secret)

BFF Proxy (Next.js)

For frontend apps that use a Backend-for-Frontend proxy:

const client = new AmigoClient({
  apiKey: 'bff-proxy',
  workspaceId: 'ws-id',
  baseUrl: '/api/platform',
  fetch: customFetchWithCookies,
})

Pagination

The SDK now exposes first-class async auto-pagination helpers on collection resources:

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

for await (const agent of client.agents.listAutoPaging({ limit: 100 })) {
  console.log(agent.name)
}

for await (const entity of client.world.listEntitiesAutoPaging({ limit: 100 })) {
  console.log(entity.display_name)
}

For custom pagination flows, the lower-level paginate(...) utility remains available.

Error handling

All SDK errors extend AmigoError. Use type guards for specific handling:

import {
  AmigoClient,
  AmigoError,
  isNotFoundError,
  isRateLimitError,
  isAuthenticationError,
} from '@amigo-ai/platform-sdk'

try {
  await client.agents.get('agent-id')
} catch (err) {
  if (isNotFoundError(err)) {
    console.log('Agent not found')
  } else if (isRateLimitError(err)) {
    console.log('Rate limited, retry after:', err.retryAfter, 'seconds')
  } else if (isAuthenticationError(err)) {
    console.log('Invalid API key')
  } else if (err instanceof AmigoError) {
    console.log('API error:', err.message, err.errorCode, err.requestId)
  }
}

Webhook verification errors are separate from API transport errors and throw WebhookVerificationError.

Error classes

| Class | HTTP Status | Description | | --------------------- | ----------- | --------------------------------------- | | BadRequestError | 400 | Malformed request | | AuthenticationError | 401 | Invalid or expired API key | | PermissionError | 403 | Insufficient permissions | | NotFoundError | 404 | Resource does not exist | | ConflictError | 409 | Duplicate slug or version conflict | | ValidationError | 422 | Request body validation failure | | RateLimitError | 429 | Too many requests — check .retryAfter | | ServerError | 5xx | Server-side error | | ConfigurationError | — | SDK misconfiguration at init time | | NetworkError | — | Fetch/network failure | | RequestTimeoutError | — | Request exceeded the configured timeout |

CommonJS (CJS) usage

const { AmigoClient } = require('@amigo-ai/platform-sdk')

License

MIT