# 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`.

An example shape:

```json
{
  "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)

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/user/{requested\_user\_id}" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% hint style="warning" %}
**Deprecated Endpoint** The old endpoint `POST /v1/{organization}/user/{requested_user_id}/user` is deprecated. Use `POST /v1/{organization}/user/{requested_user_id}` instead.
{% endhint %}

Send new facts as concise sentences in `additional_context`.

```python
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 (an admin-scope service account is recommended)
* Payload: `{ "additional_context": string[] }`

### Handling 429 (Rate Limits)

```python
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 and avoid ambiguous pronouns.
* Include units and dates where helpful.

## Common Dimensions

Typical dimensions include:

1. Demographics & Background
2. Medical History
3. Medication Management
4. Vital Signs
5. Emotional Well-being
6. Behavioral Patterns
7. Treatment Goals
8. Social Determinants
9. Communication Preferences
10. Health Monitoring

## Retrieve User Model

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/user/{user\_id}/user\_model" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}