Quick Start Guide

Quick-Start Guide for Amigo API integrations for our Enterprise customers. It’s structured so your technical teams can onboard quickly, see the big picture, and have copy-paste-ready examples.

---

1. Core Concepts

The Amigo API enables you to integrate AI-powered user interactions into your enterprise systems. At its heart, it provides:

• Authentication → Secure access with org-scoped API keys or user tokens

• User Management → Create, update, and delete users; manage roles and preferences

• Service Management → Configure how Amigo runs within your enterprise environment

• Conversation Management → Start and track conversations with Amigo agents

• Data Integration → Sync and retrieve user models to personalize agent behavior

---

2. Authentication

All API requests require authentication.

How it Works

• Organization API Keys: Typically used by backend services.

• User Tokens: Needed when acting on behalf of specific users.

Flow Diagram

[Enterprise App] --(API Key)--> [Amigo API] -- Issues --> [User Token]

Example: Authenticate with Bearer Token

curl --request GET \
     --url "https://api.amigo.ai/v1/<ORG-ID>/user/" \
     --header "Authorization: Bearer <BEARER-TOKEN>"

📖 See full details: Amigo Authentication Docs

---

3. User Management

Users are the foundation of Amigo. Every conversation, message, and user model ties back to a user profile.

Each Amigo user is assigned a unique Amigo ID. Generally, you will want to map this to your internal user ID in the initial creation request and persist this mapping in your system of record.

Users also have the following identity fields:

• first_name - required

• last_name - required

• email - required and must be unique

If for privacy reasons you do not want Amigo to store any real values for these identity fields, for the name fields you may use placeholder values such as -, or randomly generated values for the email field.

Every user also has a role that determines their permissions.

Key Endpoints

• Create/Invite User → POST /v1/{organization}/user/invite

• List Users → GET /v1/{organization}/user/

• Update User → POST /v1/{organization}/user/{user_id}/user

• Delete User → DELETE /v1/{organization}/user/{user_id}

Quick Examples

Create a user

curl --request POST \
     --url "https://api.amigo.ai/v1/<ORG-ID>/user/invite" \
     --header "Authorization: Bearer <ORG-TOKEN>" \
     --header "Content-Type: application/json" \
     --data '{
       "first_name": "John",
       "last_name": "Doe",
       "email": "[email protected]",
       "role_name": "DefaultUserRole"
     }'

Sequence Diagram

Best Practices

• Save user_id → Map to your internal user table

• Manage tokens → Rotate/expire as needed

---

4. Service Management

Services are the entry points for users to interact with specific versions of Amigo AI agents.

A user may only have a single active conversation with a given service at a time.

Key Endpoints

• Create Service → POST /v1/{organization}/service

• List Services → GET /v1/{organization}/service/

• Update Service → POST /v1/{organization}/service/{service_id}/service

• Delete Service → DELETE /v1/{organization}/service/{service_id}

Quick Examples

Create a service

curl --request POST \
     --url "https://api.amigo.ai/v1/<ORG-ID>/service" \
     --header "Authorization: Bearer <ORG-TOKEN>" \
     --header "Content-Type: application/json" \
     --data '{
       "service_hierarchical_state_machine_id": "<SERVICE-Hierarchical-State-Machine-ID>",
       "agent_id": "<AGENT-ID>",
       "name": "My Service",
       "description": "My Service Description",
       "is_active": true,
       "tags": {
         "tag1": "value1"
       }
     }'

5. Conversation Management

Amigo conversations are specific logical groupings of a user interacting with a given service during a specific time period.

Conversations consist of a sequence of messages between the user and the agent.

Amigo also has the notion of an interaction, which is a single pairing of an (possibly optional) user message and an agent response.

Lifecycle Sequence Diagram

Example: Start a Conversation

curl --request POST \
     --url "https://api.amigo.ai/v1/<ORG-ID>/conversation/?response_format=text" \
     --header "Authorization: Bearer <USER-TOKEN>" \
     --header "Content-Type: application/json" \
     --data '{
       "service_id": "<SERVICE-ID>",
       "service_version_set_name": "release"
     }'

---

6. Data Integration & User Model Management

The Amigo platform supports data integration through several mechanisms:

• User Model → The user model is an Amigo-managed object that constructs rich, structured knowledge about each user's current and historical state. It can be augmented with arbitrary string data from your system that is made available to Amigo agents at the start of the next interaction.

• Amigo Actions → An Amigo Action is a Amigo-hosted serverless function that enables dynamic data fetching from any external source including your EHR, REST API, and allows the invoking of arbitrary side-effects, e.g. creating a new appointment in your EHR.

Suggested patterns for data integration:

• Your internal user IDs are added to the user's user model additional context via the REST API upon user creation to allow the agent to fetch structured medical data such as medical records via Amigo Actions.

---

7. Putting It All Together

Here’s a typical enterprise integration flow:

+-------------------+       +--------------------+       +------------------+
| Enterprise System | <---> |   Amigo API Layer  | <---> | Amigo AI Agents  |
+-------------------+       +--------------------+       +------------------+
         |                         |                              |
         | 1. Auth via API key     |                              |
         | 2. Create user (sync)   |                              |
         | 3. Start conversations  |                              |
         | 4. Sync user models     |                              |

---

7. Next Steps for Enterprise Teams

✅ Generate an API key

✅ Implement user creation + token management

✅ Create a service

✅ Wire up conversation creation

✅ Manage user model data for personalization

---