A software engineer building a dependable healthcare integration.

Amigo API · v1

Construisez avec les signaux et opérations Amigo.

Une API organisationnelle versionnée pour provisionner les Amigos, suivre le bien-être et la cognition, et intégrer vos opérations de soin.

Gérer les clés API OpenAPI 3.1 JSON

Authentification

Envoyez une clé opaque dans le header Authorization. Une clé est affichée une seule fois, peut expirer, être révoquée immédiatement et être limitée par IP.

Example

Authorization: Bearer $AMIGO_API_KEY

Ne placez jamais une clé live dans du code navigateur, une URL, un dépôt Git ou un outil analytics.

Scopes

Chaque endpoint exige exactement le scope affiché. Les accès sont refusés par défaut.

organization:readorganization:writeresidents:readresidents:writemood:readwellbeing:readcognitive:readprofiles:readamigos:readamigos:writecalls:readcalls:writealerts:readalerts:writereports:readfamilies:readteam:readbilling:read

Erreurs, limites et retries

Toutes les réponses contiennent request_id. Les limites sont renvoyées dans X-RateLimit-*. Les POST à effets externes exigent Idempotency-Key.

Example

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the mood:read scope.",
    "request_id": "5af48ee6-6e5d-4c12-9ec4-bf488920ea9f"
  }
}

401

Invalid key

403

Missing scope

404

Not found / other tenant

429

Rate limited

Organization

Retrieve the organization

Returns the organization profile and enabled product features.

GET/organization

Scope requis: organization:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/organization" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Update the organization

Updates approved contact fields and product feature flags.

PATCH/organization

Scope requis: organization:write

Example

curl -X PATCH "https://app.tryamigo.io/api/public/v1/organization" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_email": "care@example.org",
  "features": {
    "cognitive_monitoring_enabled": true
  }
}'

Retrieve portfolio analytics

Returns tenant-safe portfolio call and resident aggregates.

GET/organization/analytics

Scope requis: organization:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/organization/analytics" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Residents

List residents

Lists residents without credentials or provider identifiers.

GET/residents

Scope requis: residents:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/residents" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Retrieve a resident

Returns a resident only when it belongs to the key organization.

GET/residents/{resident_id}

Scope requis: residents:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/residents/8c9f8c7e-91db-4dc9-883c-4c91b87538a8" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Update a resident

Updates a safe allowlist of resident identity and preference fields.

PATCH/residents/{resident_id}

Scope requis: residents:write

Example

curl -X PATCH "https://app.tryamigo.io/api/public/v1/residents/8c9f8c7e-91db-4dc9-883c-4c91b87538a8" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "preferred_language": "fr",
  "timezone": "Europe/Paris",
  "call_retry_enabled": true
}'

Mood tracker

Retrieve mood history

Returns wellbeing-oriented mood history and period statistics.

GET/residents/{resident_id}/mood

Scope requis: mood:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/residents/8c9f8c7e-91db-4dc9-883c-4c91b87538a8/mood" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Retrieve mood dimensions

Returns seven conversation-derived concern dimensions on a 0–10 scale.

GET/residents/{resident_id}/mood/dimensions

Scope requis: mood:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/residents/8c9f8c7e-91db-4dc9-883c-4c91b87538a8/mood/dimensions" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Wellbeing index

Retrieve the wellbeing index

Returns wellbeing and depression-adjacent conversational signals. It is not a diagnosis.

GET/residents/{resident_id}/wellbeing-index

Scope requis: wellbeing:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/residents/8c9f8c7e-91db-4dc9-883c-4c91b87538a8/wellbeing-index" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Cognitive tracker

Retrieve cognitive tracking

Returns baseline status, snapshots, composite score, and trend.

GET/residents/{resident_id}/cognitive

Scope requis: cognitive:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/residents/8c9f8c7e-91db-4dc9-883c-4c91b87538a8/cognitive" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Profiles

Retrieve a longitudinal profile

Returns the structured profile and longitudinal memory categories.

GET/residents/{resident_id}/profile

Scope requis: profiles:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/residents/8c9f8c7e-91db-4dc9-883c-4c91b87538a8/profile" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Amigos

List Amigos

Lists AI companions and their linked residents.

GET/amigos

Scope requis: amigos:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/amigos" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Provision an Amigo

Creates the resident, provider assistant, seat assignment, and dedicated phone lifecycle.

POST/amigos

Scope requis: amigos:write

Idempotency-Key · requis, rétention 24 h

Example

curl -X POST "https://app.tryamigo.io/api/public/v1/amigos" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Idempotency-Key: req_20260716_001" \
  -H "Content-Type: application/json" \
  -d '{
  "resident": {
    "first_name": "Marie",
    "last_name": "Martin",
    "gender": "female",
    "preferred_language": "fr",
    "timezone": "Europe/Paris"
  },
  "amigo": {
    "name": "Léa",
    "gender": "female",
    "type": "companion",
    "conversation_style": "empathetic",
    "speaking_pace": "moderate",
    "response_length": "60",
    "interaction_style": "warm and supportive",
    "voice_speed": 1,
    "interests": [
      "gardening"
    ],
    "activities": []
  },
  "seat_type": "small"
}'

Retrieve an Amigo

Returns public configuration fields without provider identifiers.

GET/amigos/{amigo_id}

Scope requis: amigos:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/amigos/34de44c4-8dc2-460a-a77b-742f7ad948bc" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Configure an Amigo

Updates the configuration and synchronizes prompt-bearing fields.

PATCH/amigos/{amigo_id}

Scope requis: amigos:write

Example

curl -X PATCH "https://app.tryamigo.io/api/public/v1/amigos/34de44c4-8dc2-460a-a77b-742f7ad948bc" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Léa",
  "voice_speed": 0.9,
  "special_instructions": "Speak clearly and leave time to answer."
}'

Delete an Amigo

Deletes provider resources and releases the dedicated phone number.

DELETE/amigos/{amigo_id}

Scope requis: amigos:write

Example

curl -X DELETE "https://app.tryamigo.io/api/public/v1/amigos/34de44c4-8dc2-460a-a77b-742f7ad948bc" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Calls

List calls

Lists safe call metadata and derived summaries; transcripts are excluded.

GET/calls

Scope requis: calls:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/calls" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Retrieve a call

Returns one call with a redacted, stable analysis DTO.

GET/calls/{call_id}

Scope requis: calls:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/calls/1193ee6b-a749-42bc-a60d-3f12ade9704f" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Scheduled calls

List scheduled calls

Lists schedules through a mandatory organization join.

GET/scheduled-calls

Scope requis: calls:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/scheduled-calls" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Create a scheduled call

Creates a recurring schedule after resident/Amigo ownership validation.

POST/scheduled-calls

Scope requis: calls:write

Idempotency-Key · requis, rétention 24 h

Example

curl -X POST "https://app.tryamigo.io/api/public/v1/scheduled-calls" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Idempotency-Key: req_20260716_001" \
  -H "Content-Type: application/json" \
  -d '{
  "resident_id": "8c9f8c7e-91db-4dc9-883c-4c91b87538a8",
  "amigo_id": "34de44c4-8dc2-460a-a77b-742f7ad948bc",
  "phone_number": "+33612345678",
  "timezone": "Europe/Paris",
  "call_time": "10:30",
  "days_of_week": [
    1,
    3,
    5
  ]
}'

Update a scheduled call

Updates an organization-owned schedule.

PATCH/scheduled-calls/{schedule_id}

Scope requis: calls:write

Example

curl -X PATCH "https://app.tryamigo.io/api/public/v1/scheduled-calls/c2d82c51-0b21-4572-ae25-c88c2c280a68" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "call_time": "11:00",
  "is_active": true
}'

Delete a scheduled call

Deletes an organization-owned schedule.

DELETE/scheduled-calls/{schedule_id}

Scope requis: calls:write

Example

curl -X DELETE "https://app.tryamigo.io/api/public/v1/scheduled-calls/c2d82c51-0b21-4572-ae25-c88c2c280a68" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Alerts

List alerts

Lists organization alerts with resident context.

GET/alerts

Scope requis: alerts:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/alerts" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Update an alert

Acknowledges, resolves, comments on, or changes family sharing for an organization alert.

PATCH/alerts/{alert_id}

Scope requis: alerts:write

Example

curl -X PATCH "https://app.tryamigo.io/api/public/v1/alerts/42" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "acknowledged",
  "share_with_family": true
}'

Reports

List reports

Lists generated report metadata.

GET/reports

Scope requis: reports:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/reports" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Retrieve a report

Returns an organization-owned generated report.

GET/reports/{report_id}

Scope requis: reports:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/reports/8e122241-78c1-42b4-9774-531177e9bf5e" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Families

List family contacts

Lists family contacts and their resident assignments.

GET/families

Scope requis: families:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/families" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Team

List organization members

Lists active members without authentication secrets.

GET/team

Scope requis: team:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/team" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"

Billing

Retrieve billing overview

Returns read-only seat, credit, subscription, and invoice information.

GET/billing

Scope requis: billing:read

Example

curl -X GET "https://app.tryamigo.io/api/public/v1/billing" \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Accept: application/json"