OpenAPI Specification
openapi: 3.1.0
info:
title: Amigo Account M42 API
version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
Bearer-Authorization-Organization: []
Basic: []
tags:
- name: M42
paths:
/v1/{workspace_id}/m42/patient-topology:
get:
tags:
- M42
summary: List Patient Topology
description: Patient-level UMAP coordinates + predicted risk for the Self-Image scatter. Hand-seeded demo data (no ML training). Paginated.
operationId: list_patient_topology_v1__workspace_id__m42_patient_topology_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: cluster
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 64
- type: 'null'
title: Cluster
- name: risk_tier
in: query
required: false
schema:
anyOf:
- type: integer
maximum: 4
minimum: 0
- type: 'null'
title: Risk Tier
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50000
minimum: 1
default: 10000
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PatientTopologyResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/district-metrics:
get:
tags:
- M42
summary: List District Metrics
description: Per-district t2d observed vs predicted incidence, capacity gap, and unmet-demand score. Hand-seeded demo data.
operationId: list_district_metrics_v1__workspace_id__m42_district_metrics_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DistrictMetricsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/anomaly-alerts:
get:
tags:
- M42
summary: List Anomaly Alerts
description: Emerging health anomalies with inline causal decomposition, recommended actions, and unacted projection. Hand-seeded demo data.
operationId: list_anomaly_alerts_v1__workspace_id__m42_anomaly_alerts_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: severity
in: query
required: false
schema:
anyOf:
- enum:
- high
- medium
- low
type: string
- type: 'null'
title: Severity
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AnomalyAlertResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/forecast-fan:
get:
tags:
- M42
summary: List Forecast Fan
description: Forecast fan points (t, median, lower/upper 95% CI) for a named run + scenario. Used by the Sensorium observational fan and the Sims dual-envelope overlay.
operationId: list_forecast_fan_v1__workspace_id__m42_forecast_fan_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: run_id
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 128
- type: 'null'
title: Run Id
- name: scenario
in: query
required: false
schema:
anyOf:
- enum:
- baseline
- with_policy
- observational
type: string
- type: 'null'
title: Scenario
- name: limit
in: query
required: false
schema:
type: integer
maximum: 5000
minimum: 1
default: 1000
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ForecastFanResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/positive-signals:
get:
tags:
- M42
summary: List Positive Signals
description: Small set of positive-trend headline metrics for the Sensorium hero strip. Hand-seeded demo data.
operationId: list_positive_signals_v1__workspace_id__m42_positive_signals_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PositiveSignalResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/anomalies/ranked:
get:
tags:
- M42
summary: List Anomalies Ranked
description: Ranked anomalies for a single indicator (default ``t2d_risk``). Includes inline decomposition + district centroids for the map. Schema-probes the alerts table so it works pre- and post-multi-indicator pipeline expansion.
operationId: list_anomalies_ranked_v1__workspace_id__m42_anomalies_ranked_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: indicator
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 32
- type: 'null'
title: Indicator
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RankedAnomalyResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/clusters/summary:
get:
tags:
- M42
summary: List Cluster Summary
description: Per-cluster cohort stats — size, mean age/BMI/HbA1c, prediabetes / T2D %, predicted-risk mean. Powers the Patient Profile cluster strip.
operationId: list_cluster_summary_v1__workspace_id__m42_clusters_summary_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterSummaryResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/clusters/forecast:
get:
tags:
- M42
summary: List Cluster Forecast
description: Per-cluster forecast fan points for the Patient Profile multi-line chart. ``focus_area`` defaults to T2D for backward compat.
operationId: list_cluster_forecast_v1__workspace_id__m42_clusters_forecast_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: focus_area
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 32
- type: 'null'
title: Focus Area
- name: limit
in: query
required: false
schema:
type: integer
maximum: 5000
minimum: 1
default: 1000
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterForecastResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/forecast-fan/draws:
get:
tags:
- M42
summary: List Forecast Draws
description: Sampled subset of raw Poisson bootstrap draws (faint spaghetti curves behind the forecast fan).
operationId: list_forecast_draws_v1__workspace_id__m42_forecast_fan_draws_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: run_id
in: query
required: false
schema:
type: string
minLength: 1
maxLength: 128
default: observational-territory-t2d
title: Run Id
- name: scenario
in: query
required: false
schema:
type: string
minLength: 1
maxLength: 32
default: baseline
title: Scenario
- name: sample
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
default: 20
title: Sample
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ForecastDrawsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/model-registry:
get:
tags:
- M42
summary: List Model Registry
description: Fitted GLM coefficients, training-set size, AUROC for each focus-area model. Inline JSON kept as strings — clients parse.
operationId: list_model_registry_v1__workspace_id__m42_model_registry_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ModelRegistryResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/stratified-fits:
get:
tags:
- M42
summary: List Stratified Fits
description: Per-cohort x region GLM fits with pooled fallback. Drives the dashboard's outcome-by-segment comparison view.
operationId: list_stratified_fits_v1__workspace_id__m42_stratified_fits_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: outcome_key
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 64
- type: 'null'
title: Outcome Key
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StratifiedFitsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/patients/{patient_id}/labs:
get:
tags:
- M42
summary: List Patient Labs
description: Patient-level bronze lab rows ordered by observation_date. Drives the mini-trajectory charts in the Patient Profile drawer.
operationId: list_patient_labs_v1__workspace_id__m42_patients__patient_id__labs_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: patient_id
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 64
title: Patient Id
- name: limit
in: query
required: false
schema:
type: integer
maximum: 2000
minimum: 1
default: 500
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PatientLabsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/patients/{patient_id}/note:
get:
tags:
- M42
summary: Get Patient Note
description: Patient's synthetic clinical note + LLM-extracted structured fields. NLP sample is 500 patients — returns 404 outside that set.
operationId: get_patient_note_v1__workspace_id__m42_patients__patient_id__note_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: patient_id
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 64
title: Patient Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PatientNoteResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/notes/rollup:
get:
tags:
- M42
summary: Get Notes Rollup
description: Cohort-wide (or per-cluster / per-district) rollup of NLP extractions joined onto patient-topology risk. Surfaces which narrative signals correlate with higher predicted T2D risk.
operationId: get_notes_rollup_v1__workspace_id__m42_notes_rollup_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: cluster
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 64
- type: 'null'
title: Cluster
- name: district
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
maxLength: 64
- type: 'null'
title: District
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/NoteRollupResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/catalog:
get:
tags:
- M42
summary: List Catalog
description: Per-table layer + description + row count for the Catalog page.
operationId: list_catalog_v1__workspace_id__m42_catalog_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/M42CatalogResponse'
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/m42/catalog/{table}/columns:
get:
tags:
- M42
summary: Describe Table
description: Column metadata (name, type, comment) for one allowlisted m42 table.
operationId: describe_table_v1__workspace_id__m42_catalog__table__columns_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: table
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 64
title: Table
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ColumnsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/catalog/{table}/sample:
get:
tags:
- M42
summary: Sample Table
description: Up to ``limit`` raw rows from one allowlisted m42 table for preview.
operationId: sample_table_v1__workspace_id__m42_catalog__table__sample_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: table
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 64
title: Table
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50
minimum: 1
default: 5
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SampleResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/m42/features:
get:
tags:
- M42
summary: List Features
description: Allowlist of feature columns (continuous or binary) for the Explore UI.
operationId: list_features_v1__workspace_id__m42_features_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FeaturesResponse'
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
/v1/{workspace_id}/m42/features/distribution:
get:
tags:
- M42
summary: Feature Distribution
description: Histogram bins for one allowlisted feature, stratified by ``y_t2d_1yr`` outcome. Continuous features get ``bins`` buckets; binary features collapse to 2.
operationId: feature_distribution_v1__workspace_id__m42_features_distribution_get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: feature
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 64
title: Feature
- name: bins
in: query
required: false
schema:
type: integer
maximum: 40
minimum: 2
default: 20
title: Bins
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureDistributionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ForecastDrawsResponse:
properties:
workspace_id:
type: string
format: uuid
title: Workspace Id
count:
type: integer
title: Count
items:
items:
$ref: '#/components/schemas/ForecastDrawPoint'
type: array
title: Items
type: object
required:
- workspace_id
- count
- items
title: ForecastDrawsResponse
ModelRegistryRow:
properties:
workspace_id:
anyOf:
- type: string
format: uuid
- type: string
const: labs
title: Workspace Id
model_id:
type: string
title: Model Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
focus_area:
anyOf:
- type: string
- type: 'null'
title: Focus Area
algorithm:
anyOf:
- type: string
- type: 'null'
title: Algorithm
version:
anyOf:
- type: string
- type: 'null'
title: Version
trained_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Trained At
training_set_size:
anyOf:
- type: integer
- type: 'null'
title: Training Set Size
coefficients_json:
anyOf:
- type: string
- type: 'null'
title: Coefficients Json
metrics_json:
anyOf:
- type: string
- type: 'null'
title: Metrics Json
status:
anyOf:
- type: string
- type: 'null'
title: Status
type: object
required:
- workspace_id
- model_id
title: ModelRegistryRow
ColumnInfo:
properties:
column_name:
type: string
title: Column Name
data_type:
type: string
title: Data Type
comment:
anyOf:
- type: string
- type: 'null'
title: Comment
type: object
required:
- column_name
- data_type
title: ColumnInfo
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
StratifiedFitsResponse:
properties:
workspace_id:
type: string
format: uuid
title: Workspace Id
count:
type: integer
title: Count
items:
items:
$ref: '#/components/schemas/StratifiedFitRow'
type: array
title: Items
type: object
required:
- workspace_id
- count
- items
title: StratifiedFitsResponse
FeatureDef:
properties:
name:
type: string
title: Name
kind:
type: string
title: Kind
type: object
required:
- name
- kind
title: FeatureDef
DistrictMetricsRow:
properties:
workspace_id:
anyOf:
- type: string
format: uuid
- type: string
const: labs
title: Workspace Id
district_name:
type: string
title: District Name
t2d_incidence_per_1k:
anyOf:
- type: number
- type: 'null'
title: T2D Incidence Per 1K
t2d_predicted_per_1k:
anyOf:
- type: number
- type: 'null'
title: T2D Predicted Per 1K
residual:
anyOf:
- type: number
- type: 'null'
title: Residual
cohort_size:
anyOf:
- type: integer
- type: 'null'
title: Cohort Size
is_anomaly:
anyOf:
- type: boolean
- type: 'null'
title: Is Anomaly
anomaly_narrative:
anyOf:
- type: string
- type: 'null'
title: Anomaly Narrative
pcp_per_1k:
anyOf:
- type: number
- type: 'null'
title: Pcp Per 1K
capacity_gap_pct:
anyOf:
- type: number
- type: 'null'
title: Capacity Gap Pct
access_narrative:
anyOf:
- type: string
- type: 'null'
title: Access Narrative
unmet_demand_score:
anyOf:
- type: number
- type: 'null'
title: Unmet Demand Score
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
type: object
required:
- workspace_id
- district_name
title: DistrictMetricsRow
ClusterSummaryRow:
properties:
cluster_name:
type: string
title: Cluster Name
cohort_size:
type: integer
title: Cohort Size
mean_age:
anyOf:
- type: number
- type: 'null'
title: Mean Age
mean_bmi:
anyOf:
- type: number
- type: 'null'
title: Mean Bmi
mean_hba1c:
anyOf:
- type: number
- type: 'null'
title: Mean Hba1C
pct_male:
anyOf:
- type: number
- type: 'null'
title: Pct Male
pct_prediabetes:
anyOf:
- type: number
- type: 'null'
title: Pct Prediabetes
pct_t2d:
anyOf:
- type: number
- type: 'null'
title: Pct T2D
mean_y_hat:
anyOf:
- type: number
- type: 'null'
title: Mean Y Hat
type: object
required:
- cluster_name
- cohort_size
title: ClusterSummaryRow
ForecastFanPointRow:
properties:
workspace_id:
anyOf:
- type: string
format: uuid
- type: string
const: labs
title: Workspace Id
run_id:
type: string
title: Run Id
scenario:
type: string
enum:
- baseline
- with_policy
- observational
title: Scenario
t:
type: number
title: T
lower_95:
anyOf:
- type: number
- type: 'null'
title: Lower 95
upper_95:
anyOf:
- type: number
- type: 'null'
title: Upper 95
median:
anyOf:
- type: number
- type: 'null'
title: Median
observed:
anyOf:
- type: number
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-m42-api-openapi.yml