World

World model dashboard composite

get

Composite world health dashboard — entity counts by type, event velocity (24h/7d), average confidence, and source breakdown. All computation server-side.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

events_24hinteger · nullableOptional

Event count from the Lakebase read model; null when the projection is empty or unavailable.

events_7dinteger · nullableOptional

Event count from the Lakebase read model; null when the projection is empty or unavailable.

avg_confidencenumber · max: 1 · nullableOptional

event_read_model_statusstring · enumOptional

ready = Lakebase projection returned a row; empty = no summary row; unavailable = read failed.

Default: emptyPossible values:

event_read_model_synced_atstring · date-time · nullableOptional

platform.event_velocity_summary synced_at for this workspace.

get/v1/{workspace_id}/world/dashboard

GET /v1/{workspace_id}/world/dashboard HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "entity_counts": {
    "total_entities": 1,
    "total_events": 1,
    "sync_pending": 1,
    "sync_synced": 1,
    "sync_failed": 1,
    "by_event_type": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "event_type_window_days": 1
  },
  "events_24h": 1,
  "events_7d": 1,
  "avg_confidence": 1,
  "event_read_model_status": "empty",
  "event_read_model_synced_at": "2026-07-10T23:40:20.111Z",
  "sources": [
    {
      "source_system": "text",
      "entity_type": "text",
      "count": 1
    }
  ]
}

List entity types

get

Returns distinct entity types in the workspace with counts and projection availability. Powers the World Explorer's auto-discovery of new entity types created by agents (L4 self-extending schema).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

total_entitiesintegerRequired

401

Missing or invalid API key.

get/v1/{workspace_id}/world/entity-types

GET /v1/{workspace_id}/world/entity-types HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "entity_types": [
    {
      "entity_type": "text",
      "count": 1,
      "last_updated": "2026-07-10T23:40:20.111Z",
      "has_projection": true
    }
  ],
  "total_entities": 1
}

List event types

get

Returns distinct event types in the workspace with counts, domains, and source breakdown. Enables the World Explorer to show what kinds of events flow through the world model.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

total_eventsintegerRequired

401

Missing or invalid API key.

get/v1/{workspace_id}/world/event-types

GET /v1/{workspace_id}/world/event-types HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "event_types": [
    {
      "event_type": "text",
      "count": 1,
      "domains": [
        "text"
      ],
      "sources": [
        "text"
      ]
    }
  ],
  "total_events": 1
}

Entity stats with sync breakdown

get

Aggregate stats for entities including sync status breakdown (pending, synced, failed). Filter by entity_type to get stats for a specific type (e.g. appointment, patient). Generic — works for any entity type in the Liquid World Model.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

entity_typestring · nullableOptional

Filter by entity type

Responses

200

Successful Response

application/json

total_entitiesintegerRequired

total_eventsintegerRequired

sync_pendingintegerRequired

sync_syncedintegerRequired

sync_failedintegerRequired

event_type_window_daysinteger · nullableOptional

Window applied to by_event_type counts when an entity_type filter is supplied.

401

Missing or invalid API key.

422

Validation Error

application/json

get/v1/{workspace_id}/world/entity-stats

GET /v1/{workspace_id}/world/entity-stats HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "total_entities": 1,
  "total_events": 1,
  "sync_pending": 1,
  "sync_synced": 1,
  "sync_failed": 1,
  "by_event_type": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "event_type_window_days": 1
}

Connected data sources overview

get

All active data sources with entity counts by type, sync status, and health. Powers the EHR/FHIR connector cards in the frontend. Each item includes connector_type (charmhealth, fhir_store) and a breakdown of entities by type (patient, practitioner, etc.).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

total_entitiesintegerRequired

get/v1/{workspace_id}/world/connectors

GET /v1/{workspace_id}/world/connectors HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "connectors": [
    {
      "data_source_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "display_name": "text",
      "source_type": "text",
      "connector_type": "text",
      "entity_count": 1,
      "entities_by_type": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "last_sync_at": "2026-07-10T23:40:20.111Z",
      "last_sync_status": "success",
      "last_sync_event_count": 0,
      "health_status": "unknown",
      "is_active": true
    }
  ],
  "total_entities": 1
}

List entities from a data source

get

Paginated entity list from a specific connected data source. Filter by entity_type and search by display name. Uses EXISTS subquery on events.data_source_id for accurate scoping.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

data_source_idstring · uuidRequired

Query parameters

entity_typestring · nullableOptional

Filter by entity type

qstring · nullableOptional

Search by display name

sort_bystring · enum · nullableOptional

Sort order: +display_name (default) or -display_name for alphabetical, +last_event_at for oldest activity first, -last_event_at for most recent first. All sort orders use entity id as a final tiebreaker for stable pagination.

Possible values:

limitinteger · min: 1 · max: 100OptionalDefault: 20

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

totalintegerRequired

has_morebooleanRequired

next_offsetinteger · nullableOptional

400

Invalid data source ID format.

422

Validation Error

application/json

get/v1/{workspace_id}/world/connectors/{data_source_id}/entities

GET /v1/{workspace_id}/world/connectors/{data_source_id}/entities HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "entities": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_type": "text",
      "display_name": "text",
      "canonical_id": "text",
      "external_ids": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "has_projection": false,
      "name": "text",
      "phone": "text",
      "email": "text",
      "birth_date": "text",
      "gender": "text",
      "mrn": "text",
      "appointment_status": "text",
      "appointment_start": "2026-07-10T23:40:20.111Z",
      "appointment_end": "2026-07-10T23:40:20.111Z",
      "appointment_type": "text",
      "domain": "text",
      "industry": "text",
      "call_sid": "text",
      "direction": "text",
      "duration_seconds": 1,
      "status": "text",
      "source": "text",
      "first_seen_at": "2026-07-10T23:40:20.111Z",
      "last_event_at": "2026-07-10T23:40:20.111Z",
      "event_count": 0,
      "confidence": 1,
      "tags": [
        "text"
      ],
      "created_at": "2026-07-10T23:40:20.111Z",
      "updated_at": "2026-07-10T23:40:20.111Z"
    }
  ],
  "total": 1,
  "has_more": true,
  "next_offset": 1
}

Search FHIR resources from a data source

get

FHIR resource search scoped to a specific data source. Returns raw FHIR resource data (Condition, MedicationRequest, Coverage, etc.) from the specified connector. Powers the per-connector clinical resource tables (FHIR Store tab, EHR tab).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

data_source_idstring · uuidRequired

Query parameters

resource_typestringRequired

FHIR resource type (e.g. Patient, Condition, MedicationRequest)

_countinteger · min: 1 · max: 100OptionalDefault: 20

_offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

FHIR resources from a specific connected data source.

resource_typestring · max: 256Required

FHIR resource type (e.g. Patient, Condition, MedicationRequest)

data_source_idstring · uuidRequired

UUID of the connected data source

totalintegerRequired

Total number of matching resources

400

Invalid data source ID or resource type.

422

Validation Error

application/json

get/v1/{workspace_id}/world/connectors/{data_source_id}/resources

GET /v1/{workspace_id}/world/connectors/{data_source_id}/resources?resource_type=text HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "resource_type": "text",
  "data_source_id": "123e4567-e89b-12d3-a456-426614174000",
  "total": 1,
  "entries": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ]
}

Entity counts by source system

get

Breakdown of entity counts by source system (e.g. charmhealth, gcp_fhir, voice_agent). Powers the EHR/FHIR view in the frontend. Filter by entity_type (e.g. person, place) for focused views.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

entity_typestring · nullableOptional

Filter by entity type

Responses

200

Successful Response

application/json

totalintegerRequired

422

Validation Error

application/json

get/v1/{workspace_id}/world/source-breakdown

GET /v1/{workspace_id}/world/source-breakdown HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "breakdown": [
    {
      "source_system": "text",
      "entity_type": "text",
      "count": 1
    }
  ],
  "total": 1
}

Outbound sync status per data source

get

Multi-sink outbound sync progress. Shows total/synced/failed/pending counts per data source for workspaces with multiple outbound sinks.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

get/v1/{workspace_id}/world/sync/by-sink

GET /v1/{workspace_id}/world/sync/by-sink HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "sinks": [
    {
      "data_source_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "source_type": "text",
      "total": 1,
      "synced": 1,
      "failed": 1,
      "pending": 1
    }
  ]
}

Set an enrichment value on an entity

put

Writes a single per-key entity.enriched event for the given entity. Validates against the workspace's enrichment_keys registry — unknown key, wrong value type, enum violation, or confidence below the key's floor all return 400. SDP picks winners by confidence class.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

entity_idstring · uuidRequired

keystring · min: 1 · max: 128RequiredPattern: ^[a-z0-9][a-z0-9_\-]*$

Body

valueanyRequired

Scalar or JSON-compatible value to store.

value_typestring · enum · nullableOptional

Overrides the registry value_type when set. Rarely needed.

Possible values:

sourcestring · min: 1 · max: 64Optional

Write source — e.g. manual, forms, auto_enrich.

Default: manual

source_systemstring · min: 1 · max: 128 · nullableOptional

Subsystem / connector identifier.

confidencenumber · max: 1Optional

Write confidence. Must be >= registry min_confidence for the key.

Default: 1

effective_atstring · date-time · nullableOptional

When the value became true (UTC). Defaults to ingested_at.

Responses

200

Successful Response

application/json

keystring · min: 1 · max: 128RequiredPattern: ^[a-z0-9][a-z0-9_\-]*$

valueanyRequired

value_typestring · enumRequiredPossible values:

confidencenumberRequired

sourcestringRequired

source_systemstring · nullableOptional

effective_atstring · date-time · nullableOptional

ingested_atstring · date-time · nullableOptional

event_idstring · uuidRequired

400

Registry validation failed.

403

Insufficient permissions.

404

Entity not found.

422

Validation Error

application/json

put/v1/{workspace_id}/world/entities/{entity_id}/enrichment/{key}

PUT /v1/{workspace_id}/world/entities/{entity_id}/enrichment/{key} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "value": null,
  "value_type": "string",
  "source": "manual",
  "source_system": "text",
  "confidence": 1,
  "effective_at": "2026-07-10T23:40:20.111Z"
}

{
  "key": "text",
  "value": null,
  "value_type": "string",
  "confidence": 1,
  "source": "text",
  "source_system": "text",
  "effective_at": "2026-07-10T23:40:20.111Z",
  "ingested_at": "2026-07-10T23:40:20.111Z",
  "event_id": "123e4567-e89b-12d3-a456-426614174000"
}

List current enrichment values for an entity

get

Current winners per (entity, key) from world.entity_enrichment_out_synced (Synced-Table-populated view of SDP's entity_enrichment_out). Each row carries value, value_type, confidence, source, effective_at.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

entity_idstring · uuidRequired

Query parameters

limitinteger · min: 1 · max: 500Optional

Max enrichment rows

Default: 200

offsetintegerOptional

Page offset

Default: 0

Responses

200

Successful Response

application/json

entity_idstring · uuidRequired

404

Entity not found.

422

Validation Error

application/json

get/v1/{workspace_id}/world/entities/{entity_id}/enrichment

GET /v1/{workspace_id}/world/entities/{entity_id}/enrichment HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "values": [
    {
      "key": "text",
      "value": null,
      "value_type": "string",
      "confidence": 1,
      "source": "text",
      "source_system": "text",
      "effective_at": "2026-07-10T23:40:20.111Z",
      "ingested_at": "2026-07-10T23:40:20.111Z",
      "event_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Enrichment supersedes chain for audit

get

Returns every entity.enriched event for (entity, key), newest first, including superseded entries. Each entry carries the full provenance: source, confidence, effective_at, supersedes pointer, is_current flag.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

entity_idstring · uuidRequired

keystring · min: 1 · max: 128RequiredPattern: ^[a-z0-9][a-z0-9_\-]*$

Query parameters

limitinteger · min: 1 · max: 200OptionalDefault: 50

Responses

200

Successful Response

application/json

entity_idstring · uuidRequired

keystring · min: 1 · max: 128RequiredPattern: ^[a-z0-9][a-z0-9_\-]*$

dropped_countintegerOptionalDefault: 0

404

Entity not found.

422

Validation Error

application/json

get/v1/{workspace_id}/world/entities/{entity_id}/enrichment/{key}/history

GET /v1/{workspace_id}/world/entities/{entity_id}/enrichment/{key}/history HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "key": "text",
  "history": [
    {
      "event_id": "123e4567-e89b-12d3-a456-426614174000",
      "value": null,
      "value_type": "string",
      "confidence": 1,
      "source": "text",
      "source_system": "text",
      "effective_at": "2026-07-10T23:40:20.111Z",
      "ingested_at": "2026-07-10T23:40:20.111Z",
      "supersedes": "123e4567-e89b-12d3-a456-426614174000",
      "is_current": true
    }
  ],
  "dropped_count": 0
}

List enrichment keys registered for this workspace

get

Optionally filter by entity_type.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

entity_typestring · nullableOptional

Filter by entity type.

limitinteger · min: 1 · max: 500Optional

Max keys to return

Default: 200

offsetintegerOptional

Page offset

Default: 0

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get/v1/{workspace_id}/world/enrichment-keys

GET /v1/{workspace_id}/world/enrichment-keys HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "keys": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_type": "text",
      "key": "text",
      "value_type": "string",
      "allowed_values": [],
      "source_hint": "text",
      "description": "text",
      "min_confidence": 1,
      "is_pii": true,
      "tags": [
        "text"
      ],
      "created_at": "2026-07-10T23:40:20.111Z",
      "updated_at": "2026-07-10T23:40:20.111Z"
    }
  ]
}

Register an enrichment key

post

Registers a new (entity_type, key) in this workspace's enrichment key registry. Future writes against this key will pass validation. value_type governs what values are accepted; enum types require allowed_values. Tag a person key with 'memory_extract' (description required) to make it a workspace-custom memory dimension the conversation extractor infers from transcripts.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

entity_typestring · min: 1 · max: 64Required

keystring · min: 1 · max: 128RequiredPattern: ^[a-z0-9][a-z0-9_\-]*$

value_typestring · enumRequiredPossible values:

source_hintstring · max: 2000 · nullableOptional

descriptionstring · max: 2000 · nullableOptional

min_confidencenumber · max: 1OptionalDefault: 0

is_piibooleanOptionalDefault: false

tagsstring[]Optional

Routing tags. 'memory_extract' opts this key into memory extraction — the conversation extractor will infer it from transcripts as a workspace-custom memory dimension (person keys with a description only).

Responses

201

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

entity_typestring · min: 1 · max: 64Required

keystring · min: 1 · max: 128RequiredPattern: ^[a-z0-9][a-z0-9_\-]*$

value_typestring · enumRequiredPossible values:

source_hintstring · nullableOptional

descriptionstring · nullableOptional

min_confidencenumberRequired

is_piibooleanRequired

tagsstring[]OptionalDefault: []

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

400

Invalid request body.

403

Insufficient permissions.

409

Key already exists for (entity_type, key).

422

Validation Error

application/json

post/v1/{workspace_id}/world/enrichment-keys

POST /v1/{workspace_id}/world/enrichment-keys HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 169

{
  "entity_type": "text",
  "key": "text",
  "value_type": "string",
  "allowed_values": [],
  "source_hint": "text",
  "description": "text",
  "min_confidence": 0,
  "is_pii": false,
  "tags": [
    "text"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_type": "text",
  "key": "text",
  "value_type": "string",
  "allowed_values": [],
  "source_hint": "text",
  "description": "text",
  "min_confidence": 1,
  "is_pii": true,
  "tags": [
    "text"
  ],
  "created_at": "2026-07-10T23:40:20.111Z",
  "updated_at": "2026-07-10T23:40:20.111Z"
}

Delete a registered enrichment key

delete

Existing entity.enriched events are not deleted (append-only); only future writes against this key will be rejected.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

key_idstring · uuidRequired

Responses

204

Successful Response

No content

403

Insufficient permissions.

404

Enrichment key not found.

422

Validation Error

application/json

delete/v1/{workspace_id}/world/enrichment-keys/{key_id}

DELETE /v1/{workspace_id}/world/enrichment-keys/{key_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a registered enrichment key

patch

Update allowed_values, source_hint, description, min_confidence, is_pii, or tags. key and value_type are immutable.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

key_idstring · uuidRequired

Body

source_hintstring · max: 2000 · nullableOptional

descriptionstring · max: 2000 · nullableOptional

min_confidencenumber · max: 1 · nullableOptional

is_piiboolean · nullableOptional

tagsstring[] · nullableOptional

Replaces the full tags list when set. Pass [] to remove all tags.

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

entity_typestring · min: 1 · max: 64Required

keystring · min: 1 · max: 128RequiredPattern: ^[a-z0-9][a-z0-9_\-]*$

value_typestring · enumRequiredPossible values:

source_hintstring · nullableOptional

descriptionstring · nullableOptional

min_confidencenumberRequired

is_piibooleanRequired

tagsstring[]OptionalDefault: []

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

403

Insufficient permissions.

404

Enrichment key not found.

422

Validation Error

application/json

patch/v1/{workspace_id}/world/enrichment-keys/{key_id}

PATCH /v1/{workspace_id}/world/enrichment-keys/{key_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "allowed_values": [],
  "source_hint": "text",
  "description": "text",
  "min_confidence": 1,
  "is_pii": true,
  "tags": [
    "text"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_type": "text",
  "key": "text",
  "value_type": "string",
  "allowed_values": [],
  "source_hint": "text",
  "description": "text",
  "min_confidence": 1,
  "is_pii": true,
  "tags": [
    "text"
  ],
  "created_at": "2026-07-10T23:40:20.111Z",
  "updated_at": "2026-07-10T23:40:20.111Z"
}

List entities

get

List entities filtered by type with optional name search. Works for any entity type — patients, operators, calls, or any type created by T3 agents. Returns full projected state.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

entity_typestring[] · nullableOptional

Filter by entity type (repeatable)

qstring · nullableOptional

Search by name, type, canonical ID, phone, or entity ID

limitinteger · min: 1 · max: 100OptionalDefault: 20

offsetintegerOptionalDefault: 0

orderstring · max: 128 · nullableOptional

Sort order (PostgREST-style, e.g. last_event_at.desc, display_name.asc)

has_projectionboolean · nullableOptional

Filter by has_projection flag

sourcestring · nullableOptional

Filter by event source (e.g. voice_agent, connector_runner)

source_systemstring · nullableOptional

Filter by source system name (e.g. charmhealth, gcp_fhir)

fhir_resource_typestring · max: 64 · nullableOptional

Filter by FHIR resource type (e.g. Patient, Practitioner)

Responses

200

Successful Response

application/json

totalintegerRequired

has_morebooleanRequired

next_offsetinteger · nullableOptional

401

Missing or invalid API key.

422

Validation Error

application/json

get/v1/{workspace_id}/world/entities

GET /v1/{workspace_id}/world/entities HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "entities": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_type": "text",
      "display_name": "text",
      "canonical_id": "text",
      "external_ids": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "has_projection": false,
      "name": "text",
      "phone": "text",
      "email": "text",
      "birth_date": "text",
      "gender": "text",
      "mrn": "text",
      "appointment_status": "text",
      "appointment_start": "2026-07-10T23:40:20.111Z",
      "appointment_end": "2026-07-10T23:40:20.111Z",
      "appointment_type": "text",
      "domain": "text",
      "industry": "text",
      "call_sid": "text",
      "direction": "text",
      "duration_seconds": 1,
      "status": "text",
      "source": "text",
      "first_seen_at": "2026-07-10T23:40:20.111Z",
      "last_event_at": "2026-07-10T23:40:20.111Z",
      "event_count": 0,
      "confidence": 1,
      "tags": [
        "text"
      ],
      "created_at": "2026-07-10T23:40:20.111Z",
      "updated_at": "2026-07-10T23:40:20.111Z"
    }
  ],
  "total": 1,
  "has_more": true,
  "next_offset": 1
}

Resolve entity by identifier

post

Polymorphic identifier → ranked entity candidates. Accepts any subset of {phone, email, canonical_id, external_id, entity_id} plus a required entity_type. Served from the SDP serving surfaces: entity rows from world.entities_synced; canonical_id and external_id resolve through world.canonical_entity_map_synced point reads. Returns matches ranked by confidence + number of identifiers matched. Summary narrowing: external_ids is always {}, tags is always [], and canonical_id is the canonical-map value or the entity's MRN.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

Polymorphic identifier query.

Provide entity_type plus any subset of identifier fields. Each identifier is OR-ed in SQL; matches are ranked by confidence and by the number of identifiers that actually matched the row. Returns at most limit candidates (default 25, max 50).

For latency-sensitive callers (inbound voice, webhook handlers), pass exactly one identifier — the indexed lookup is sub-10ms. Multi-identifier queries are useful for confirming a row matches on more than one signal (phone + email + MRN).

entity_typestring · min: 1 · max: 64Required

Required entity type filter (e.g. 'person'). Narrows the scan to the right index.

Pattern: ^[a-z0-9_]+$

phonestring · min: 2 · max: 16 · nullableOptional

E.164 phone number.

emailstring · email · nullableOptional

Primary email (case-insensitive match).

canonical_idstring · min: 1 · max: 256 · nullableOptional

Canonical identifier as carried by the canonical entity map (e.g. 'charm:Patient:42'; a raw MRN resolves only when a producer minted it as the canonical_id).

entity_idstring · uuid · nullableOptional

Direct UUID lookup. Useful for confirming an entity exists / re-fetching summary.

limitinteger · min: 1 · max: 50Optional

Maximum candidates to return.

Default: 25

Responses

200

Successful Response

application/json

totalintegerRequired

Number of candidates returned.

400

No identifier provided or invalid input.

401

Missing or invalid API key.

422

Validation Error

application/json

post/v1/{workspace_id}/world/entities/resolve

POST /v1/{workspace_id}/world/entities/resolve HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 193

{
  "entity_type": "text",
  "phone": "text",
  "email": "name@gmail.com",
  "canonical_id": "text",
  "external_id": {
    "system": "text",
    "value": "text"
  },
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "limit": 25
}

{
  "matches": [
    {
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_type": "text",
      "confidence": 1,
      "matched_on": [
        "entity_id"
      ],
      "summary": {
        "display_name": "text",
        "name": "text",
        "phone": "text",
        "email": "text",
        "birth_date": "text",
        "mrn": "text",
        "canonical_id": "text",
        "external_ids": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "last_event_at": "2026-07-10T23:40:20.111Z",
        "event_count": 0,
        "tags": [
          "text"
        ]
      }
    }
  ],
  "total": 1
}

Get entity

get

Fetch a single entity with its full projected state. The state is a computed projection from all events — never mutated directly. Enhanced entity types (patient, operator, call) have richer projections.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

entity_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

entity_typestringRequired

display_namestring · nullableOptional

canonical_idstring · nullableOptional

has_projectionbooleanOptionalDefault: false

namestring · nullableOptional

Display name (person, organization)

phonestring · nullableOptional

Primary phone number (E.164)

emailstring · nullableOptional

Primary email address

birth_datestring · nullableOptional

Date of birth (YYYY-MM-DD)

genderstring · nullableOptional

Gender

mrnstring · nullableOptional

Medical record number

appointment_statusstring · nullableOptional

Appointment status (booked, confirmed, cancelled)

appointment_startstring · date-time · nullableOptional

Appointment start time (UTC)

appointment_endstring · date-time · nullableOptional

Appointment end time (UTC)

appointment_typestring · nullableOptional

Appointment/visit type

domainstring · nullableOptional

Organization domain

industrystring · nullableOptional

Organization industry

call_sidstring · nullableOptional

Twilio call SID

directionstring · nullableOptional

Call direction (inbound, outbound)

duration_secondsnumber · nullableOptional

Call duration in seconds

statusstring · nullableOptional

Entity status

sourcestring · nullableOptional

Primary data source

first_seen_atstring · date-time · nullableOptional

last_event_atstring · date-time · nullableOptional

event_countintegerOptionalDefault: 0

confidencenumberOptionalDefault: 1

tagsstring[] · nullableOptional

created_atstring · date-time · nullableOptional

When the entity was created

updated_atstring · date-time · nullableOptional

When the entity was last updated

400

Invalid entity ID format.

401

Missing or invalid API key.

404

Entity not found.

422

Validation Error

application/json

get/v1/{workspace_id}/world/entities/{entity_id}

GET /v1/{workspace_id}/world/entities/{entity_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_type": "text",
  "display_name": "text",
  "canonical_id": "text",
  "external_ids": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "has_projection": false,
  "name": "text",
  "phone": "text",
  "email": "text",
  "birth_date": "text",
  "gender": "text",
  "mrn": "text",
  "appointment_status": "text",
  "appointment_start": "2026-07-10T23:40:20.111Z",
  "appointment_end": "2026-07-10T23:40:20.111Z",
  "appointment_type": "text",
  "domain": "text",
  "industry": "text",
  "call_sid": "text",
  "direction": "text",
  "duration_seconds": 1,
  "status": "text",
  "source": "text",
  "first_seen_at": "2026-07-10T23:40:20.111Z",
  "last_event_at": "2026-07-10T23:40:20.111Z",
  "event_count": 0,
  "confidence": 1,
  "tags": [
    "text"
  ],
  "created_at": "2026-07-10T23:40:20.111Z",
  "updated_at": "2026-07-10T23:40:20.111Z"
}

Entity timeline

get

Get the event timeline for an entity — all current events ordered by effective date. The entity's state is always a projection of these events. Filter by domain (clinical, operational, audit, etc.).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

entity_idstring · uuidRequired

Query parameters

domainstring · nullableOptional

Filter by domain

limitinteger · min: 1 · max: 200OptionalDefault: 50

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

entity_idstring · uuidRequired

totalintegerRequired

has_morebooleanRequired

next_offsetinteger · nullableOptional

400

Invalid entity ID format.

401

Missing or invalid API key.

404

Entity not found.

422

Validation Error

application/json

get/v1/{workspace_id}/world/entities/{entity_id}/timeline

GET /v1/{workspace_id}/world/entities/{entity_id}/timeline HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "events": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "domain": "text",
      "entity_type": "text",
      "event_type": "text",
      "event_subtype": "text",
      "fhir_resource_type": "text",
      "fhir_resource_id": "text",
      "data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "source": "manual",
      "source_system": "text",
      "confidence": 1,
      "produced_by_agent": "text",
      "display_name": "text",
      "status": "text",
      "description": "text",
      "outcome": "text",
      "channel": "text",
      "call_sid": "text",
      "direction": "text",
      "duration_seconds": 1,
      "amount": 1,
      "supersedes": "123e4567-e89b-12d3-a456-426614174000",
      "is_current": true,
      "effective_at": "2026-07-10T23:40:20.111Z",
      "ingested_at": "2026-07-10T23:40:20.111Z",
      "synced_at": "2026-07-10T23:40:20.111Z",
      "sync_error": "text",
      "sync_status": "pending",
      "created_at": "2026-07-10T23:40:20.111Z"
    }
  ],
  "total": 1,
  "has_more": true,
  "next_offset": 1
}

Entity relationships

get

Get relationships for an entity — links to other entities in the knowledge graph. Filter by relationship type.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

entity_idstring · uuidRequired

Query parameters

relationshipstring · nullableOptional

Filter by relationship type

Responses

200

Successful Response

application/json

entity_idstring · uuidRequired

totalintegerRequired

400

Invalid entity ID format.

401

Missing or invalid API key.

404

Entity not found.

422

Validation Error

application/json

get/v1/{workspace_id}/world/entities/{entity_id}/relationships

GET /v1/{workspace_id}/world/entities/{entity_id}/relationships HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "relationships": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "source_entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "source_entity_type": "text",
      "target_entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "target_entity_type": "text",
      "relationship": "text",
      "data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "confidence": 1,
      "discovered_by": "text",
      "is_current": true,
      "created_at": "2026-07-10T23:40:20.111Z"
    }
  ],
  "total": 1
}

Get merged entities (same_as links)

get

Returns entities linked via same_as edges — historical merge edges where different data sources refer to the same real-world entity (written by the pre-SDP resolver; merge detection now lives in the Databricks pipeline — new edges are not produced).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

entity_idstring · uuidRequired

Responses

200

Successful Response

application/json

entity_idstring · uuidRequired

totalintegerRequired

400

Invalid entity ID format.

404

Entity not found.

422

Validation Error

application/json

get/v1/{workspace_id}/world/entities/{entity_id}/merged

GET /v1/{workspace_id}/world/entities/{entity_id}/merged HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "linked_entities": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_type": "text",
      "display_name": "text",
      "canonical_id": "text",
      "external_ids": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "has_projection": false,
      "name": "text",
      "phone": "text",
      "email": "text",
      "birth_date": "text",
      "gender": "text",
      "mrn": "text",
      "appointment_status": "text",
      "appointment_start": "2026-07-10T23:40:20.111Z",
      "appointment_end": "2026-07-10T23:40:20.111Z",
      "appointment_type": "text",
      "domain": "text",
      "industry": "text",
      "call_sid": "text",
      "direction": "text",
      "duration_seconds": 1,
      "status": "text",
      "source": "text",
      "first_seen_at": "2026-07-10T23:40:20.111Z",
      "last_event_at": "2026-07-10T23:40:20.111Z",
      "event_count": 0,
      "confidence": 1,
      "tags": [
        "text"
      ],
      "created_at": "2026-07-10T23:40:20.111Z",
      "updated_at": "2026-07-10T23:40:20.111Z"
    }
  ],
  "total": 1
}

PreviousEntity Intelligence NextData Query

Last updated 2 hours ago

Was this helpful?