---
title: "POST /wm/reads"
method: POST
path: "/wm/reads"
tags: ["World Model"]
---

# POST /wm/reads

`POST /wm/reads`

## Request

- Base URL: `https://api.team0.ai/v1`
- URL: `https://api.team0.ai/v1/wm/reads`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://clerk.team0.ai/oauth/authorize`, token URL `https://clerk.team0.ai/oauth/token`)
  - HTTP bearer

## Headers

- `Idempotency-Key` string, required

## Request body

- WMReadCreate
  - `query` string, required
  - `purpose` 'brief' | 'answer' | 'compare' | 'structured', required
  - `as_of` string, date-time
  - `latency_budget_ms` integer
  - `live` boolean: Set true only when the user asks for current data right now ("check my inbox now") or the answer's last-synced times are too old for the question. Team0 then also reads the connected calendar and Gmail live for what the request names.
  - `output` object
    - `include` string[]
    - `max_facts` integer
    - `max_items_per_component` integer: Keeps only the query-ranked prefix of each requested list component other than facts.

## Response `201`

Frozen authorized World Model read.

- WMRead
  - `id` string, required
  - `object` 'wm.read', required
  - `version` integer, required
  - `created_at` string, date-time, required
  - `usable_until` string, date-time, required
  - `retained_until` string, date-time, required
  - `as_of` string, date-time, required
  - `scope` 'owner' | 'public' | 'c2c', required
  - `read_version` string, required
  - `content_digest` string, required
  - `status` 'complete' | 'partial' | 'degraded', required
  - `projection` object, required
    - `maintained` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `situations` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `priorities` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `facts` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `candidates` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `storylines` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `episodes` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `open_work` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `live_context` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `contradictions` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
    - `coverage` ProjectionStatus, required
      - `status` 'complete' | 'partial' | 'not_requested' | 'unavailable' | 'withheld', required
      - `reason` string
  - `understanding` object, required
    - `maintained` MaintainedUnderstanding, required
      - `state` 'ready' | 'unavailable' | 'withheld' | 'not_requested', required
      - `evidence_version` string, nullable, required
      - `reference_time` string, date-time, required
      - `synthesized_at` string, date-time, required
      - `degraded_sources` string[], required
      - `items` MaintainedMatter[], required
        - `id` string, required
        - `object` 'wm.maintained_matter', required
        - `version` string, required
        - `title` string, required
        - `current_read` string, required
        - `why_it_matters` string, required
        - `why_now` string, required
        - `significance` string, required
        - `recommended_posture` string, required
        - `rationale` string, required
        - `known_unknowns` string[], required
        - `next_review_at` string, date-time, required
        - `fact_ids` OpaqueId[], required
        - `support` 'in_read' | 'query_expansion_available', required
    - `situations` Situation[], required
      - `id` string, required
      - `object` 'wm.situation', required
      - `title` string, required
      - `summary` string
      - `status` 'active' | 'stable' | 'uncertain' | 'resolved', required
      - `fact_ids` OpaqueId[], required
    - `priorities` Priority[], required
      - `id` string, required
      - `object` 'wm.priority', required
      - `title` string, required
      - `horizon` 'now' | 'today' | 'current_week' | 'thirty_to_sixty_days' | 'long_term', required
      - `objective_type` 'task' | 'goal' | 'strategy' | 'constraint' | 'risk' | 'deadline', required
      - `status` 'current' | 'waiting' | 'completed' | 'cancelled' | 'unknown', required
      - `authority` 'owner_explicit' | 'owner_confirmed' | 'provider_authoritative' | 'system_structural', required
      - `displacement_rule` 'never' | 'same_horizon' | 'explicit_owner_override', required
      - `observed_at` string, date-time, required
      - `source` SourceAttribution, required
        - `id` string
        - `kind` string, required
        - `name` string
      - `fact_ids` OpaqueId[], required
    - `open_work` OpenWork[], required
      - `id` string, required
      - `object` 'wm.open_work', required
      - `title` string, required
      - `status` string, required
      - `owner_id` string
      - `due_at` string, date-time
      - `fact_ids` OpaqueId[]
    - `live_context` LiveContext[], required
      - `id` string, required
      - `object` 'wm.live_context', required
      - `kind` string, required
      - `text` string, required
      - `as_of` string, date-time
      - `fact_ids` OpaqueId[]
  - `world` object, required
    - `facts` Fact[], required
      - `id` string, required
      - `object` 'wm.fact', required
      - `predicate` string, required
      - `text` string, required
      - `source_type` string, required
      - `source` SourceAttribution, required
        - `id` string
        - `kind` string, required
        - `name` string
      - `fact_when` string, nullable, required
      - `learned_at` string, date-time, required
      - `epistemic_status` 'trusted' | 'contradicted' | 'uncertain', required
      - `evidence` EvidenceRef[], required
        - `id` string, required
        - `object` 'evidence_ref', required
      - `about_query_subject` boolean: Present when the read resolved the request. True when the fact is about a record the request names.
      - `admitted_for_query` boolean: Present when the read resolved the request. True when the shared projection admitted the fact for this request.
      - `about_other_person` boolean: Present when the read resolved the request. True when the fact is about a person other than the owner and the records the request names.
      - `query_similarity` number: Present when the read resolved the request and the fact has a stored vector. Cosine similarity between the fact and the request.
      - `rank_score` number: Present when the read resolved the request. The hybrid search score that ranked this fact (meaning
      - `disputed_by` string: Owner scope only. Another fact in this read that makes a different claim about the same matter; nothing yet settles which is current.
      - `progress` object[]: Owner scope only. Parts of this still-open item that later evidence already settled. The item itself stays open.
        - `part` string, required
        - `status` 'done' | 'declined' | 'rescheduled' | 'open' | 'unclear', required
    - `candidates` Candidate[], required
      - `id` string, required
      - `object` 'wm.candidate', required
      - `kind` string, required
      - `text` string, required
      - `status` 'unresolved' | 'supported' | 'rejected' | 'superseded', required
      - `evidence` EvidenceRef[], required
        - `id` string, required
        - `object` 'evidence_ref', required
    - `storylines` Storyline[], required
      - `id` string, required
      - `object` 'wm.storyline', required
      - `title` string, required
      - `kind` string, required
      - `fact_count` integer, required
      - `last_activity_at` string, date-time
    - `episodes` Episode[], required
      - `id` string, required
      - `object` 'wm.episode', required
      - `title` string, required
      - `kind` string, required
      - `started_at` string, date-time
      - `summary` string
      - `origin` 'semantic' | 'recall_window', required
    - `contradictions` Contradiction[], required
      - `id` string, required
      - `object` 'wm.contradiction', required
      - `entity_id` string
      - `attribute_key` string, required
      - `status` 'unresolved_current_conflict', required
      - `competing_fact_ids` OpaqueId[], required
  - `coverage` Coverage[], required
    - `source` string, required
    - `status` 'complete' | 'partial' | 'stale' | 'unavailable' | 'not_connected' | 'not_requested' | 'unknown', required
    - `as_of` string, date-time
    - `detail` string, nullable
    - `window_start` string, date-time
    - `window_end` string, date-time
    - `enumerated` boolean, required
  - `staleness` Staleness, required
    - `status` 'fresh' | 'mixed' | 'stale' | 'unknown', required
    - `evaluated_at` string, date-time, required
    - `oldest_source_at` string, date-time
  - `truncation` object, required
  - `query_resolution` QueryResolution: What the request names and the period it asks about, resolved deterministically before the read. Present only when enabled for the tenant and scope is owner.
    - `subjects` object[], required
      - `id` string, required
      - `name` string, required
      - `importance` string: Nightly deterministic tier: inner, active, periphery or dormant.
      - `relationship` string: Stated relationship to the owner.
    - `unconfirmed` object[]: Recent heard-but-unconfirmed (candidate) facts about the named records, owner scope only. Never evidence of an outcome.
      - `predicate` string
      - `text` string, required
      - `source` string
      - `when` string
      - `learned` string
      - `progress` string: Parts later evidence already settled, e.g. 'send the deck: done, intro to Dana: declined'. The item itself stays open.
    - `people_now` object[]: Present when the request names nothing. The inner and active circle by importance, with each person's relationship to the owner.
      - `name` string, required
      - `importance` string
      - `relationship` string
    - `ambiguous` object[], required: A mention several records share; never resolved by popularity.
      - `mention` string, required
      - `candidates` object[], required
        - `id` string, required
        - `name` string, required
    - `sources` object[]: Each connected source Team0 keeps current and when it last synced (UTC). Team0 keeps what they mean, not their raw contents.
      - `source` string, required
      - `synced_at` string, required
    - `live_emails` object[]: Emails read live from Gmail for this request (with the named people, or the latest primary-inbox emails when the request names nothing). Owner scope only.
      - `account` string, required
      - `from` string, required
      - `to` string, required
      - `date` string, required
      - `subject` string, required
      - `snippet` string, required
    - `live_read_at` string: When the live Gmail/Calendar read ran (UTC).
    - `activity` object[]: The named people's recent emails, meetings and calendar events from Team0's activity record, newest first. Owner scope only.
      - `person` string, required
      - `kind` 'email' | 'meeting' | 'calendar', required
      - `when` string, required
      - `title` string, required
      - `direction` string
    - `recent_emails` object[]: When the request names nothing, the newest emails in Team0's hourly email copy with Team0's category. Owner scope only.
      - `account` string, required
      - `from` string, required
      - `to` string, required
      - `date` string, required
      - `subject` string, required
      - `snippet` string, required
      - `category` string, required
    - `recent_emails_as_of` string: When the email copy behind recent_emails last synced (UTC).
    - `unmatched` string[], required: Names no record holds when nothing else in the request resolved.
    - `terms` string[], required: Capitalized terms that matched no record; facts mentioning them may still exist.
    - `window` object, nullable, required
      - `label` string, required
      - `start` string, date, required
      - `end` string, date, required
      - `timezone` string, required
      - `calendar_as_of` string: When the calendar last synced; an event added since is not listed.
      - `calendar_live` boolean: True when the period's events were read live from every connected calendar at calendar_as_of.
      - `items` object[], required

## Other responses

- `default`: RFC 9457 problem response. Cross-tenant identity is non-enumerating.

---

[API](https://skmtc.dev/team0/apis/team0-external-api.md) · [All operations](https://skmtc.dev/team0/apis/team0-external-api/llms.txt) · [OpenAPI document](https://skmtc.dev/team0/apis/team0-external-api/revisions/9b838d20a98f?raw)