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

# POST /wm/compositions

`POST /wm/compositions`

## Request

- Base URL: `https://api.team0.ai/v1`
- URL: `https://api.team0.ai/v1/wm/compositions`
- 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
- `Prefer` 'respond-async'

## Request body

- union
  - object
    - `read_id` string, required
    - `read` 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.
    - `execution` 'auto' | 'async'
    - `purpose` 'answer' | 'brief' | 'summarize' | 'compare' | 'format', required
    - `instructions` string
  - object
    - `read_id` string
    - `read` WMReadCreate, required
      - `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.
    - `execution` 'auto' | 'async'
    - `purpose` 'answer' | 'brief' | 'summarize' | 'compare' | 'format', required
    - `instructions` string

## Response `201`

Composition completed within the synchronous wait budget.

- Composition
  - `id` string, required
  - `object` 'wm.composition', required
  - `operation_id` string, required
  - `usage_charge_id` string, required
  - `read_id` string, required
  - `version` integer, required
  - `created_at` string, date-time, required
  - `status` 'completed', required
  - `content` string, required
  - `grounding` EvidenceRef[], required
    - `id` string, required
    - `object` 'evidence_ref', required
  - `usage` object, required

## Other responses

- `202`: Durable composition operation accepted.
- `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)