User Models

Amigo maintains an evolving, structured model of each user. You can augment it with additional context from your systems.

Structure

Content entries contain natural-language facts about the user.
Each entry may include supporting insight_ids and descriptive dimensions.

Example shape:

{
  "user_models": [
    {
      "content": "Tony has hypertension and Type 2 diabetes managed with medication.",
      "insight_ids": [{"$oid": "67fe9cca0e3bf2dbf54e4ef5"}],
      "dimensions": [
        {
          "description": "Medical History & Conditions",
          "tags": ["medical history", "conditions", "chronic disease"]
        }
      ]
    }
  ]
}

Update Additional Context (Quick Start)

Update user info

post

Update information about an user. Only fields that are specified in the request are updated.

Permissions

This endpoint requires the following permissions:

User:UpdateUserInfo for the user to update.

Authorizations

Path parameters

requested_user_idstringRequired

The identifier of the user to update information for.

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

first_nameany ofOptional

The first name of the user to update. If null, the first name is not modified.

string · min: 1Optional

nullOptional

last_nameany ofOptional

The last name of the user to update. If null, the last name is not modified.

string · min: 1Optional

nullOptional

enable_response_recommendationany ofOptional

Whether to automatically recommend responses to the user if the user hasn't replied to the coach for a while. If null, the preference is not modified.

booleanOptional

nullOptional

preferred_languageany ofOptional

The preferred language for the user. The agent will attempt to converse to the user in this language if set. This field must be in the ISO 639-3 format. If null, erase the user's preferred setting, and the specific language used will be the agent's default spoken language. In order to not update this field, leave it out of the request or set it to an empty object (_NotSet).

Default: {}

string · enum · min: 3 · max: 3OptionalPossible values:

object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

nullOptional

timezoneany ofOptional

The user's timezone in the IANA tz database format. If not specified, the organization's timezone is used.

Default: {}

string · enum · min: 1OptionalPossible values:

object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

nullOptional

conversations_visible_to_adminsany ofOptional

Whether conversations are visible to the admins. If null, the preference is not modified.

booleanOptional

nullOptional

user_model_visible_to_adminsany ofOptional

Whether the user's user model is visible to the admins. If null, the preference is not modified.

booleanOptional

nullOptional

additional_contextany ofOptional

A list of additional context to update. If null, the context is not modified.

string[]Optional

nullOptional

Responses

204

Succeeded.

No content

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

409

A related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 50 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

POST /v1/{organization}/user/{requested_user_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 238

{
  "first_name": "text",
  "last_name": "text",
  "enable_response_recommendation": true,
  "preferred_language": "aaa",
  "timezone": "Africa/Abidjan",
  "conversations_visible_to_admins": true,
  "user_model_visible_to_admins": true,
  "additional_context": [
    "text"
  ]
}

No content

Deprecated Endpoint The old endpoint POST /v1/{organization}/user/{requested_user_id}/user is deprecated. Use POST /v1/{organization}/user/{requested_user_id} instead.

Send new facts as concise sentences in additional_context.

import os, requests

ORG_ID = os.environ["AMIGO_ORG_ID"]
API_KEY = os.environ["AMIGO_API_KEY"]  # admin-scope service account
USER_ID = "user_12345"

facts = [
    "Tony's average fasting glucose over the past week is 105 mg/dL.",
    "He reports mild dizziness after his evening dose of Lisinopril 20 mg.",
    "Tony exercises three times a week (mostly swimming).",
]

resp = requests.post(
    f"https://api.amigo.ai/v1/{ORG_ID}/user/{USER_ID}",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"additional_context": facts},
    timeout=15,
)
resp.raise_for_status()
print("✓ user model updated")

Endpoint quick facts

Path: /v1/{organization}/user/{requested_user_id}
Method: POST
Auth: Bearer token (admin-scope service account recommended)
Payload: { "additional_context": string[] }

Handling 429 (Rate Limits)

import requests, time

def post_with_backoff(url: str, headers: dict, json: dict, max_retries: int = 5):
    delay = 1
    for attempt in range(1, max_retries + 1):
        resp = requests.post(url, headers=headers, json=json)
        if resp.status_code != 429:
            resp.raise_for_status()
            return resp
        retry_after = int(resp.headers.get("Retry-After", delay))
        time.sleep(retry_after)
        delay = min(delay * 2, 60)
    raise RuntimeError("Too many consecutive 429 responses – aborting")

Formatting Guidance

Provide an array of human-readable strings; Amigo parses prose, not your schema.
Keep each sentence self-contained; avoid ambiguous pronouns.
Include units and dates where helpful.

Common Dimensions

Typical dimensions include:

Demographics & Background
Medical History
Medication Management
Vital Signs
Emotional Well-being
Behavioral Patterns
Treatment Goals
Social Determinants
Communication Preferences
Health Monitoring

Retrieve User Model

Get user model

get

Retrieve the user models for an user.

Permissions

This endpoint requires the following permissions:

User:GetUserModel for the user to retrieve the user models for.

Authorizations

Path parameters

organizationstringRequired

user_idstringRequired

The ID of the user whose user models to retrieve.

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 60 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

GET /v1/{organization}/user/{user_id}/user_model HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "user_models": [
    {
      "content": "text",
      "insight_ids": [
        "text"
      ],
      "dimensions": [
        {
          "description": "text",
          "tags": [
            "text"
          ]
        }
      ]
    }
  ],
  "additional_context": [
    "text"
  ]
}

PreviousUsers NextServices

Last updated 5 days ago

Was this helpful?