# 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](https://docs.amigo.ai/developer-guide/classic-api/sdks/sdk-installation#python) or [TypeScript](https://docs.amigo.ai/developer-guide/classic-api/sdks/sdk-installation#typescript).
3. **Configure authentication** using the [Authentication Guide](https://docs.amigo.ai/developer-guide/getting-started/authentication).
4. **Set your regional endpoint** per [Regions & Endpoints](https://docs.amigo.ai/developer-guide/getting-started/regions-and-endpoints).
5. **Run the Hello World example** from the [tutorial](https://docs.amigo.ai/developer-guide/classic-api/sdks/sdk-hello-world).

```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 conversation = await client.conversations.createConversation({
  service_id: 'your-service-id',
  service_version_set_name: 'release'
});

const response = await client.conversations.interactWithConversation(
  conversation.conversation_id,
  "Hello, Amigo!"
);
```

### 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](https://docs.amigo.ai/developer-guide/platform-api/platform-api/authentication).

```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](https://docs.amigo.ai/developer-guide/platform-api/platform-api) 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/diagram content="%%{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<br/>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<br/>Phone Calls · Emotion Detection]
    PO[Operators & Escalation]
    PW[World Model<br/>Event-Sourced Patient Data]
    PC[Connector Runner<br/>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**](https://docs.amigo.ai/developer-guide/getting-started)        | Both       | Core concepts, authentication, and regional configuration |
| [**Classic API**](https://docs.amigo.ai/developer-guide/classic-api/core-api)       | Classic    | Conversations, users, tools, simulations, metrics         |
| [**Platform API**](https://docs.amigo.ai/developer-guide/platform-api/platform-api) | Platform   | Workspaces, agents, skills, voice, EHR, operators, FHIR   |
| [**SDKs**](https://docs.amigo.ai/developer-guide/classic-api/sdks)                  | Classic    | Official Python and TypeScript/JavaScript SDKs            |
| [**Data Access**](https://docs.amigo.ai/developer-guide/classic-api/data-access)    | Classic    | SQL API, Delta Sharing, organization table schemas        |
| [**Webhooks**](https://docs.amigo.ai/developer-guide/classic-api/webhooks)          | Classic    | Real-time event delivery and management                   |
| [**Permissions**](https://docs.amigo.ai/developer-guide/classic-api/permissions)    | Classic    | Role-based access control and security                    |
| [**Best Practices**](https://docs.amigo.ai/developer-guide/operations/devops)       | Classic    | Version sets, multi-org tenancy, PHI isolation            |
| [**Reference**](https://docs.amigo.ai/developer-guide/operations/reference)         | 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) |