> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/data-world-model.md). # Data & World Model 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. {% hint style="info" %} **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](https://docs.amigo.ai/data/world-model). This page covers the API surface. {% endhint %} {% hint style="info" %} **Different from Classic API data access.** The Classic API provides [SQL access](/developer-guide/classic-api/data-access.md) to organization-scoped relational tables. The Platform API exposes typed operational APIs and asynchronously maintained world-model read projections. {% endhint %} ## 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](/developer-guide/platform-api/data-world-model/connector-runner.md) for that delivery contract. See [Voice Agent, Confidence-Gated Writes](/developer-guide/platform-api/conversations/voice-agent.md#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](https://docs.amigo.ai/data/world-model) 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 | {% hint style="info" %} 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. {% endhint %} ### 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 {% openapi src="" path="/v1/{workspace\_id}/world/entities" method="get" %} {% endopenapi %} #### Get an Entity {% openapi src="" path="/v1/{workspace\_id}/world/entities/{entity\_id}" method="get" %} {% endopenapi %} {% hint style="warning" %} 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. {% endhint %} ## 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](#api-reference) below for the full endpoint contract. ## Entity Graph Entities are connected by directed relationship edges, discovered automatically from data: ```mermaid %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%% flowchart TB P["Person\n(patient role)"] -->|"participant"| A["Appointment"] A -->|"practitioner"| PR["Person\n(practitioner role)"] A -->|"location"| L["Place"] P -->|"primary_care"| PR P -->|"coverage"| INS["Insurance"] C["Call"] -->|"caller"| P C -->|"escalation"| OP["Person\n(operator role)"] OT["Outbound Task"] -->|"patient"| P OT -->|"call"| C D["Deal"] -->|"contact"| P D -->|"organization"| ORG["Organization"] ``` 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](/developer-guide/platform-api/data-world-model/connector-runner.md) 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](/developer-guide/platform-api/integrations/review-queue.md). ## 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 {% openapi src="" path="/v1/{workspace\_id}/entities/{entity\_id}/brief" method="post" %} {% endopenapi %} ### 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`. {% openapi src="" path="/v1/{workspace\_id}/entities/{entity\_id}/brief" method="get" %} {% endopenapi %} 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. {% openapi src="" path="/v1/{workspace\_id}/world/entities/{entity\_id}/graph" method="get" %} {% endopenapi %} ### 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. {% openapi src="" path="/v1/{workspace\_id}/world/entities/{entity\_id}/provenance" method="get" %} {% endopenapi %} ### 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`](#world-sync-status). {% openapi src="" path="/v1/{workspace\_id}/world/entities/{entity\_id}/lineage" method="get" %} {% endopenapi %} ### Suspected Duplicates {% openapi src="" path="/v1/{workspace\_id}/world/entities/duplicates" method="get" %} {% endopenapi %} 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. {% openapi src="" path="/v1/{workspace\_id}/world/search" method="get" %} {% endopenapi %} **Permissions**: `viewer+`. ## World Sync Status Shows outbound sync progress per configured sink. {% openapi src="" path="/v1/{workspace\_id}/world/sync/by-sink" method="get" %} {% endopenapi %} ## Generic Data Query A structured query endpoint provides whitelisted table access with REST-style filtering. {% openapi src="" path="/v1/{workspace\_id}/query/{schema}/{table}" method="get" %} {% endopenapi %} **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. {% openapi src="" path="/v1/{workspace\_id}/world/migration/conversations" method="post" %} {% endopenapi %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/platform-api/data-world-model.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.