A software engineer building a dependable healthcare integration.

Amigo API · v1

Build with Amigo signals and operations.

A versioned, organization-scoped API for provisioning Amigos, tracking wellbeing and cognition, and integrating care operations.

Manage API keys OpenAPI 3.1 JSON

Authentication

Send an opaque key in the Authorization header. A key is shown once, can expire, is immediately revocable, and can be restricted by source IP.

Example

Authorization: Bearer $AMIGO_API_KEY

Never place a live key in browser code, a URL, a Git repository, or analytics tooling.

Scopes

Each endpoint requires exactly the scope shown. Access is denied by default.

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

Errors, limits & retries

Every response includes request_id. Limits are returned in X-RateLimit-* headers. POST requests with external side effects require 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

Required scope: 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

Required scope: 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

Required scope: 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

Required scope: 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}

Required scope: 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}

Required scope: 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

Required scope: 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

Required scope: 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

Required scope: 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

Required scope: 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

Required scope: 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

Required scope: 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

Required scope: amigos:write

Idempotency-Key · required, retained for 24 hours

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}

Required scope: 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}

Required scope: 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}

Required scope: 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

Required scope: 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}

Required scope: 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

Required scope: 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

Required scope: calls:write

Idempotency-Key · required, retained for 24 hours

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}

Required scope: 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}

Required scope: 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

Required scope: 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}

Required scope: 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

Required scope: 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}

Required scope: 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

Required scope: 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

Required scope: 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

Required scope: billing:read

Example

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