# Welcome Official developer documentation for the Amigo AI platform. {% hint style="info" %} **New to Amigo?** For a full understanding of Amigo's architecture and design philosophy, see the [Conceptual Documentation](https://docs.amigo.ai). This developer guide focuses on API implementation and SDK usage. {% endhint %} ## Quick Start Amigo exposes **two distinct APIs** for different deployment models. Pick your path. ### Classic API (text-based digital health) A single-actor system for consumer-facing chat agents, async voice notes, and WebSocket streaming. 1. **Obtain API credentials** from your Amigo representative. 2. **Install an SDK**: [Python](/developer-guide/classic-api/sdks/sdk-installation.md#python) or [TypeScript](/developer-guide/classic-api/sdks/sdk-installation.md#typescript). 3. **Configure authentication** using the [Authentication Guide](/developer-guide/getting-started/authentication.md). 4. **Set your regional endpoint** per [Regions & Endpoints](/developer-guide/getting-started/regions-and-endpoints.md). 5. **Run the Hello World example** from the [tutorial](/developer-guide/classic-api/sdks/sdk-hello-world.md). ```typescript import { AmigoClient } from '@amigo-ai/sdk'; const client = new AmigoClient({ apiKey: process.env.AMIGO_API_KEY!, apiKeyId: process.env.AMIGO_API_KEY_ID!, userId: process.env.AMIGO_USER_ID!, orgId: process.env.AMIGO_ORGANIZATION_ID! }); const createEvents = await client.conversations.createConversation({ body: { service_id: 'your-service-id', service_version_set_name: 'release' }, query: { response_format: 'text' }, }); let conversationId; for await (const event of createEvents) { if (event.type === 'conversation-created') conversationId = event.conversation_id; } const interactionEvents = await client.conversations.interactWithConversation({ conversationId, input: 'Hello, Amigo!', query: { request_format: 'text', response_format: 'text' }, }); for await (const event of interactionEvents) { // handle NDJSON events; break on 'interaction-complete' } ``` `createConversation` and `interactWithConversation` return NDJSON event streams (async generators) that you iterate with `for await`, not single response objects. ### Platform API (enterprise voice and healthcare) Multi-system enterprise deployments with phone-based voice agents, EHR integration, operator escalation, and safety monitoring. 1. **Obtain a workspace API key** from your Amigo representative. 2. **Set your base URL** to `https://api.platform.amigo.ai/v1`. 3. **Authenticate** with your API key as a Bearer token. See [Platform API Authentication](/developer-guide/platform-api/platform-api/authentication.md). ```bash # List agents in your workspace curl -s https://api.platform.amigo.ai/v1/{workspace_id}/agents \ -H "Authorization: Bearer $AMIGO_API_KEY" ``` See the [Platform API docs](/developer-guide/platform-api/platform-api.md) for voice agent setup, EHR integration, and operator workflows. {% hint style="info" %} Some deployments span both. A health system might use the Platform API for inbound phone scheduling and the Classic API for a patient-facing chat experience. {% endhint %} ## API Comparison | | **Classic API** | **Platform API** | | ------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | **Built for** | Consumer digital health (text chat, voice notes) | Enterprise healthcare (phone calls, EHR, operators) | | **Base URL** | `https://api.amigo.ai/v1` | `https://api.platform.amigo.ai/v1` | | **Scoping** | Organization-scoped (`/v1/{organization}/...`) | Workspace-scoped (`/v1/{workspace_id}/...`) | | **Authentication** | User JWT (per-user) | Workspace API Key (Bearer token) | | **Conversations** | Text chat, voice notes, WebSocket streaming | Phone-based inbound and outbound calls | | **Tools / Skills** | Versioned code packages (Tools) | LLM-backed micro-agents (Skills) | | **User data** | User models with memory and personalization | Event-sourced world model with EHR sync | | **Testing** | Simulations, personas, scenarios, metrics | Workspace-level workflows | | **Integrations** | Webhooks, SQL data access, Delta Sharing | EHR connectors, FHIR, operator escalation, safety monitoring | | **SDKs** | `amigo-python-sdk`, `@amigo-ai/sdk` | Direct HTTP | | **OpenAPI Spec** | [`api.amigo.ai/v1/openapi.json`](https://api.amigo.ai/v1/openapi.json) | [`api.platform.amigo.ai/v1/openapi.json`](https://api.platform.amigo.ai/v1/openapi.json) | ### System Architecture ```mermaid %%{init: {"flowchart": {"useMaxWidth": true, "nodeSpacing": 40, "rankSpacing": 45}, "theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%% flowchart TB subgraph Classic["Classic API · api.amigo.ai"] direction TB CU[Users & Memory] CC[Conversations
Text · Voice Notes · WebSocket] CT[Tools & Dynamic Behaviors] CS[Simulations & Metrics] end subgraph Platform["Platform API · api.platform.amigo.ai"] direction TB PV[Voice Agent
Phone Calls · Emotion Detection] PO[Operators & Escalation] PW[World Model
Event-Sourced Patient Data] PC[Connector Runner
EHR · FHIR Store · CRM Sync] end subgraph Shared["Shared"] AG[Agents & Context Graphs] SV[Services & Version Sets] end AG --> Classic AG --> Platform SV --> Classic SV --> Platform style Classic fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:2px style Platform fill:#DDE3DB,stroke:#2c3827,color:#100F0F,stroke-width:2px style Shared fill:#F1EAE7,stroke:#D7D2D0,color:#100F0F,stroke-width:2px ``` ## Documentation Structure | Section | Applies to | Description | | ----------------------------------------------------------------- | ---------- | --------------------------------------------------------- | | [**Getting Started**](/developer-guide/getting-started.md) | Both | Core concepts, authentication, and regional configuration | | [**Classic API**](/developer-guide/classic-api/core-api.md) | Classic | Conversations, users, tools, simulations, metrics | | [**Platform API**](/developer-guide/platform-api/platform-api.md) | Platform | Workspaces, agents, skills, voice, EHR, operators, FHIR | | [**SDKs**](/developer-guide/classic-api/sdks.md) | Classic | Official Python and TypeScript/JavaScript SDKs | | [**Data Access**](/developer-guide/classic-api/data-access.md) | Classic | SQL API, Delta Sharing, organization table schemas | | [**Webhooks**](/developer-guide/classic-api/webhooks.md) | Classic | Real-time event delivery and management | | [**Permissions**](/developer-guide/classic-api/permissions.md) | Classic | Role-based access control and security | | [**Best Practices**](/developer-guide/operations/devops.md) | Classic | Version sets, multi-org tenancy, PHI isolation | | [**Reference**](/developer-guide/operations/reference.md) | Both | Rate limits, terminology, common patterns | ## Support and Resources | Resource | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **API Reference** | [Interactive API Documentation](https://docs.amigo.ai/api-reference) | | **Support** | Contact your account executive or agent engineer via Slack | | **SDK Issues** | [Python](https://github.com/amigo-ai/amigo-python-sdk/issues) / [TypeScript](https://github.com/amigo-ai/amigo-typescript-sdk/issues) | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.amigo.ai/developer-guide/readme.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.