Data & World Model

Query and manage workspace entities, enrichment, provenance, confidence-gated writes, migration metadata, data sources, and synchronization status.

The Platform API exposes workspace-scoped entity projections, event timelines, enrichment, data-source configuration, and synchronization status. Event-producing paths write source-attributed world events, and asynchronous data pipelines materialize the supported entity and timeline read models. Other platform resources, including service-owned configuration and lifecycle records, remain transactional and can emit world events separately.

Conceptual overview. For the design rationale behind the world model - why event sourcing, how confidence-based truth works, and how agents read and write during conversations - see the World Model conceptual documentation. This page covers the API surface.

Different from Classic API data access. The Classic API provides SQL access to organization-scoped relational tables. The Platform API exposes typed operational APIs and asynchronously maintained world-model read projections.

Storage and Projection Boundaries

The API surface combines several storage patterns. Keep these boundaries in mind:

• Event-backed entity reads are projections. Supported world-event families are materialized asynchronously into entity and timeline read models, so a successful emit does not imply immediate read-after-write visibility.
• The world-event ledger is append-oriented. A replacement can point to a prior record through supersedes; downstream projections derive the effective current record. This does not make every service-owned table append-only.
• Projection behavior is type-specific. Supported entity/event families have explicit projection logic. Arbitrary labels are not guaranteed to produce a typed entity projection or relationship edge.
• Confidence is policy input, not a universal decision rule. Specific projections, review flows, and connector sinks use confidence alongside source allowlists, sink support, and other policy checks.
• Transactional resources have their own contracts. Surfaces, connector configuration, and similar resources commit through their service APIs and may emit lifecycle events asynchronously after the transaction.

Event Sourcing Model

World-event-producing paths emit append-oriented records with source and confidence metadata. Not every platform datum is a world event; service-owned resources expose their own CRUD and lifecycle contracts.

Field	Description
entity_type	Optional entity classification used by supported projections and queries
event_type	Event identifier defined by the producing service and downstream pipeline
data	Event payload (structured data, FHIR resources, agent observations, etc.)
confidence	Source-class score (0.0-1.0) available to projections and delivery policies that use it
source	Origin system (voice_agent, connector_runner, ehr_sync, transcript_extraction, etc.)
is_current	Current marker on read/projection records; append-ledger supersession is represented by supersedes
effective_at	When the fact was true in the real world
review_status	Review state (e.g. auto_approved, approved, rejected, flagged)

Confidence as Trust Architecture

World events carry a confidence score. The labels below are the common source classes; passing a confidence threshold alone never guarantees projection or outbound delivery.

Level	Confidence	Meaning	Source Examples
Authoritative	1.0	Authoritative source or manual correction	EHR API, manual entry, human correction
Human-approved	0.95	Confirmed by a human reviewer	Human review approval
High	0.9	Operator-verified or high-quality adapter data	Operator verification, trusted adapter
EHR-trusted	0.8	Trusted EHR clinical data	EHR clinical records
Verified	0.7	Verified or EHR-ingested data	Verification pass, EHR ingestion
Self-report	0.5	Patient-submitted or partially corroborated data	Patient-submitted form data
Agent-raw	0.3	Unverified agent inference	Raw voice-agent write
Rejected	0.0	Discarded or explicitly rejected	Invalid or rejected observation

Some projections, including governed enrichment winners, rank by confidence class and use recency as a tiebreaker. Other projections can apply different type-specific logic.

Clients can filter and report on confidence, and configured outbound connectors apply a confidence gate in addition to their source allowlist, supported entity/event mappings, review policy, and destination rules. See Connector Runner for that delivery contract.

See Voice Agent, Confidence-Gated Writes for how voice agent writes progress through the confidence pipeline.

Supersedes Chain

Where a producer supplies or derives a supersession link, the new event references the prior event through supersedes. The append ledger does not mutate the prior record; downstream projections asynchronously derive which record is effectively current. Event families without a supersession key do not automatically gain this chain.

How Agents Read and Write

Agents interact with the world model through three channels:

• Ambient (pushed): data the agent should always have - caller identity, patient state, related entities, location context - is injected into the system prompt and refreshed as the conversation evolves.
• Queried (pulled): data whose search space is too large to push - slot search, patient lookup, entity search - is retrieved through tool calls that return human-readable results.
• Extracted (captured): supported voice runtimes can attach structured observations from conversation at source-appropriate confidence. Explicit write tools remain the controlled path for high-stakes mutations.

The World Model conceptual documentation covers the design rationale for this split and how it evolves as models improve.

Entity Types

The entity APIs accept string type filters, but typed projections are implemented for a defined set of entity families. The current shared projection set is person, place, call, appointment, outbound_task, and organization. Other labels can appear in domain event timelines, but a new label does not automatically gain typed projection behavior.

Entity Type	What It Represents	Common Roles / Key State Fields
person	Any individual in the system	Patient (demographics, conditions, medications, insurance), practitioner (profile, NPI, specialty), operator (availability, performance). A single person entity can hold multiple roles; the projection detects roles from event data.
organization	A company or healthcare organization	Practice, payer, employer. Name, contacts, identifiers
place	A physical site	Clinic, hospital, office. Address, phone, hours, status
appointment	A scheduled visit	Status, participants, times, cancellation, confirmation
call	A voice conversation	Context, escalation history, safety state, human segments, audit
outbound_task	A scheduled outreach task	Lifecycle, retry state, scheduling, dispatch history

FHIR resource types on events (Patient, Practitioner, Location, etc.) stay unchanged. The ontological type applies at the entity level, while FHIR types describe the data format of individual events.

Entity Reads

Entity reads promote common attributes from projected state into typed top-level fields. Fields that do not apply to an entity type return null.

List Entities

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-01-01T00:00:00.000Z",
      "appointment_end": "2026-01-01T00:00:00.000Z",
      "appointment_type": "text",
      "domain": "text",
      "industry": "text",
      "call_sid": "text",
      "direction": "text",
      "duration_seconds": 1,
      "status": "text",
      "source": "text",
      "first_seen_at": "2026-01-01T00:00:00.000Z",
      "last_event_at": "2026-01-01T00:00:00.000Z",
      "event_count": 0,
      "confidence": 1,
      "tags": [
        "text"
      ],
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "total": 1,
  "has_more": true,
  "next_offset": 1
}

Get an Entity

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-01-01T00:00:00.000Z",
  "appointment_end": "2026-01-01T00:00:00.000Z",
  "appointment_type": "text",
  "domain": "text",
  "industry": "text",
  "call_sid": "text",
  "direction": "text",
  "duration_seconds": 1,
  "status": "text",
  "source": "text",
  "first_seen_at": "2026-01-01T00:00:00.000Z",
  "last_event_at": "2026-01-01T00:00:00.000Z",
  "event_count": 0,
  "confidence": 1,
  "tags": [
    "text"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

The state field (object containing the full projected state) is deprecated. Use the typed fields above instead. The state field will continue to be returned for backward compatibility but may be removed in a future version.

Entity Enrichment

Entities can carry governed per-key attributes beyond the typed response fields. Enrichment writes produce source-attributed, confidence-scored entity.enriched events, and the enrichment projection selects the current winner for each registered key.

Registry-Governed Keys

Every workspace maintains a registry of enrichment keys. A key is scoped to a specific (entity_type, key) pair and declares:

• value_type: one of string, number, boolean, date, enum, json.
• allowed_values: required when value_type=enum.
• min_confidence: floor on write confidence; writes below this are rejected.
• is_pii: marks the attribute for downstream PII handling.
• source_hint, description: free-form text for admins.

Writes against an unregistered key are rejected with 400. Agent-extracted values whose key is not registered are silently dropped, so they do not pollute the event stream or compete with governed values. This gives admins full control over which attributes are tracked without blocking agent-side capture.

key and value_type are immutable after registration; create a new key and migrate if those need to change. Deleting a registered key does not delete historical entity.enriched events (the audit trail is preserved); only future writes are rejected.

Winner Selection and Audit

Reads return the current winner per (entity, key), one row with full provenance (value, value type, confidence, source, source system, effective time, ingested time, event ID). The enrichment projection selects winners by confidence class (authoritative > human-approved > AI-verified > uncertain) with recency as the tiebreaker; this rule is specific to that projection contract.

The supersedes chain for any key is queryable for audit and temporal debugging. Each historical entry carries the full provenance plus supersedes (pointer to the event it replaced) and is_current (whether it is still the winner).

Governed Enrichment Write Path

Direct enrichment writes share the registry validation path and are differentiated by source and confidence. Validation errors (unknown key, wrong value type, enum miss, sub-floor confidence) return 400 with a specific message. Connectors, surfaces, and agent runtimes have separate service paths and can emit compatible world events asynchronously.

Direct enrichment writes and registry mutations require the admin role or above (Workspace:Update). See the API Reference below for the full endpoint contract.

Entity Graph

Entities are connected by directed relationship edges, discovered automatically from data:

Projected relationships can come from supported inputs such as:

1. Reference parsing: automatically extracted during entity resolution (e.g., Appointment.participant -> Patient).
2. Explicit events: relationship.established events created by connectors or agents.
3. Agent-produced events: configured agents can emit supported relationship observations.

Relationship endpoints read projected graph edges. Availability and versioning depend on the producer and projection for that relationship type.

Agent-Produced Knowledge

Configured agents can emit derived events such as insights or corrections with provenance fields. Whether those records become typed entity state, timeline entries, or downstream triggers depends on the event family and deployed projection.

Data Sources

External data feeds that push or pull data into the workspace:

Strategy	Behavior	Example
continuous	Polled on a frequent interval	EHR patient updates
scheduled	Polled on a cron schedule	Daily reporting
manual	Only synced via explicit API trigger	One-time imports
webhook	Receives push events (no polling)	Real-time notifications

Data-source endpoints expose configuration and recorded status/history fields. Live health, checkpoints, and recovery detail vary by connector. The connector runner manages supported polling and synchronization paths.

The data sources list endpoint accepts repeatable source_type query parameters for filtering by multiple source types in a single request (e.g., ?source_type=ehr&source_type=smart_fhir).

Self-Service Secret Provisioning

For smart_fhir data sources, the create and update endpoints support inline secret provisioning. Pass private_key_value in the connection_config and the API automatically provisions the key to secure storage, storing only a secure secret-store reference in the data source record. API responses redact all secret fields (*_value, *_pem, *_secret, *_password) and mask the stored secret reference. No manual secret provisioning is needed when connecting SMART-compliant EHR systems.

Raw Records

Supported connectors can retain records they cannot map as source-attributed raw events (commonly with a .raw event type). Retention and replay behavior are connector-specific; the API does not guarantee that every rejected or unmapped source payload is stored.

Data Quality Pipeline

World events expose confidence metadata, and specific consumers apply it according to their own contracts:

• Capture at source-appropriate confidence. Connector-runner writes from authoritative systems land at authoritative confidence; agent-extracted conversation data lands at moderate confidence; raw agent inference lands at agent-raw confidence.
• Verification can emit a higher-confidence record. A review or correction path may create a new event and, where supported, link it through supersedes.
• Outbound sync uses multiple gates. The connector runner checks confidence together with an explicit source allowlist, supported mappings, dependency state, destination policy, and any configured review step. Meeting the verified threshold is necessary on the automatic path but not sufficient to guarantee delivery.

Where the private-preview connector review flow is enabled, configured external mutations can be routed through human review as external write proposals before delivery - see Review Queue.

Entity Narrative Briefs

AI-generated narrative summaries of a patient entity's world model data. The platform reads the last 90 days of events, synthesizes them into a structured narrative, and persists the result as a world model event for fast retrieval.

Generate a Brief

Generate Brief

post

Generate a Self-Image brief for the target entity (patient, cohort, territory, emirate, or district).

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

Target entity UUID

Responses

200

Successful Response

application/json

Wire shape for a Self-Image brief.

event_id is null when no brief has ever been generated for the entity. All other fields are nullable in that case so the UI can render a consistent empty state.

event_idstring · uuid · nullableRequired

target_entity_idstring · uuidRequired

target_entity_typestring · enumRequiredPossible values:

content_mdstring · max: 20000 · nullableOptional

versionstring · max: 64 · nullableOptional

evidence_event_idsstring · uuid[] · max: 500Optional

confidencenumber · max: 1Required

event_countintegerRequired

model_namestring · max: 128 · nullableOptional

truncatedbooleanOptionalDefault: false

generated_atstring · date-time · nullableRequired

422

Validation Error

application/json

post/v1/{workspace_id}/entities/{entity_id}/brief

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

{
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "target_entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "target_entity_type": "patient",
  "content_md": "text",
  "content_json": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "version": "text",
  "evidence_event_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "confidence": 1,
  "event_count": 1,
  "model_name": "text",
  "truncated": false,
  "generated_at": "2026-01-01T00:00:00.000Z"
}

Get the Latest Brief

Cache misses fall through to the event store and repopulate the cache. When no brief has been generated, the operation returns a consistent empty shape rather than 404.

Get Latest Brief

get

Return the latest Self-Image brief for the target entity (null shape if none).

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

Target entity UUID

Responses

200

Successful Response

application/json

Wire shape for a Self-Image brief.

event_id is null when no brief has ever been generated for the entity. All other fields are nullable in that case so the UI can render a consistent empty state.

event_idstring · uuid · nullableRequired

target_entity_idstring · uuidRequired

target_entity_typestring · enumRequiredPossible values:

content_mdstring · max: 20000 · nullableOptional

versionstring · max: 64 · nullableOptional

evidence_event_idsstring · uuid[] · max: 500Optional

confidencenumber · max: 1Required

event_countintegerRequired

model_namestring · max: 128 · nullableOptional

truncatedbooleanOptionalDefault: false

generated_atstring · date-time · nullableRequired

422

Validation Error

application/json

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

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

{
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "target_entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "target_entity_type": "patient",
  "content_md": "text",
  "content_json": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "version": "text",
  "evidence_event_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "confidence": 1,
  "event_count": 1,
  "model_name": "text",
  "truncated": false,
  "generated_at": "2026-01-01T00:00:00.000Z"
}

Briefs are scoped to patient, cohort, territory, emirate, and district entities. Permissions: viewer+.

Entity Intelligence

Read endpoints for exploring individual entities: their relationship graph, data provenance, full lineage, suspected duplicates, and search.

Relationship Graph

Returns center (entity metadata), edges[] (edge type, confidence), and neighbors[] (entity metadata for connected nodes). Responds with 404 if the entity is not found.

Get Entity Graph

get

Entity relationship graph — one level of edges with neighbor metadata. same_as edges are historical merge edges (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

Other propertiesanyOptional

404

Entity not found

422

Validation Error

application/json

429

Rate limit exceeded

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

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

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Provenance

Returns sources[] (contributing data sources), confidence_history[] (score over time), and merge_history[] (entity resolution events). Responds with 404 if the entity is not found.

Get Entity Provenance

get

Data lineage for an entity — sources, confidence history, merge history (historical same_as edges from the pre-SDP resolver — 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

Other propertiesanyOptional

404

Entity not found

422

Validation Error

application/json

429

Rate limit exceeded

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

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

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Lineage

The response contains the same sources, confidence_history, and merge_history sections as the provenance endpoint, plus outbound_sinks and review_history keys that are currently always empty arrays (kept for wire stability). For per-sink outbound sync status, use GET /world/sync/by-sink.

Get Entity Lineage

get

Full data lineage — provenance + outbound sinks + review history.

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

Other propertiesanyOptional

404

Entity not found

422

Validation Error

application/json

429

Rate limit exceeded

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

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

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Suspected Duplicates

Get Entity Duplicates

get

Suspected duplicate entities — historical same_as merge edges sorted by confidence (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

Query parameters

entity_typestring · nullableOptional

Filter by entity type

confidence_maxnumber · max: 1Optional

Max confidence threshold

Default: 1

limitinteger · min: 1 · max: 500Optional

Max edges to return

Default: 100

offsetintegerOptional

Page offset

Default: 0

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

429

Rate limit exceeded

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

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

[
  {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
]

Returns historical same_as merge edges sorted by ascending confidence (lowest means most uncertain). New same_as edges are no longer written; the results reflect previously recorded merges.

Entity Search

Search currently uses case-insensitive display-name substring matching. It is not semantic or embedding search.

Search Entities

get

Enhanced entity search with type, source, and confidence filters.

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

qstringRequired

Search text (matched against display_name)

entity_typestring · nullableOptional

Filter by entity type

sourcestring · nullableOptional

Filter by event source

confidence_minnumber · max: 1 · nullableOptional

Min confidence

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

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

429

Rate limit exceeded

get/v1/{workspace_id}/world/search

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

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Permissions: viewer+.

World Sync Status

Shows outbound sync progress per configured sink.

Generic Data Query

A structured query endpoint provides whitelisted table access with REST-style filtering.

Query Table

get

Query a table with PostgREST-style filtering, sorting, and pagination.

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

schemastringRequired

tablestringRequired

Query parameters

selectstring · nullableOptional

orderstring · nullableOptional

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

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

countintegerRequired

has_morebooleanRequired

422

Validation Error

application/json

get/v1/{workspace_id}/query/{schema}/{table}

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

{
  "items": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "count": 1,
  "has_more": true
}

Security: column whitelist per table, hidden sensitive columns, workspace isolation enforced server-side, maximum 100 rows per request.

Import Classic Conversation Metadata

POST /v1/{workspace_id}/world/migration/conversations imports terminal Classic conversation envelopes for migrated person entities. The operation is admin-only and accepts 1-500 conversations per request.

The operation is idempotent and correctable for a given workspace and source conversation ID. It imports conversation metadata, not transcript turns. The response reports imported, created, and updated counts.

Bulk-import v1 conversation envelopes for migrated patients

post

Writes one terminal world.conversations row per v1 conversation (real dates, provider='v1-migration'), giving the returning-user greeting and the real conversation list. Admin-only, idempotent + correctable per (workspace, v1 conversation id), memory-safe (no world events emitted → the memory extractor never re-derives from these). Transcript content (turns) is a separate follow-up. Batch size <= 500.

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

Responses

200

Successful Response

application/json

importedintegerRequired

createdintegerRequired

updatedintegerRequired

400

Naive/future timestamps, bad window, or non-person entity_id.

403

Insufficient permissions.

422

Validation Error

application/json

post/v1/{workspace_id}/world/migration/conversations

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

{
  "conversations": [
    {
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "source_conversation_id": "text",
      "started_at": "2026-01-01T00:00:00.000Z",
      "ended_at": "2026-01-01T00:00:00.000Z",
      "channel_kind": "web",
      "turn_count": 0
    }
  ]
}

{
  "imported": 1,
  "created": 1,
  "updated": 1
}