---
title: "Read a task envelope"
method: GET
path: "/api/assistant/tasks/{id}"
tags: ["Mailzero Assistant"]
---

# Read a task envelope

`GET /api/assistant/tasks/{id}`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/assistant/tasks/{id}`
- Auth: HTTP bearer

The matter handed over, as the assignee needs it: the brief with the evidence, the facts, the delegation (assignee, rule, level, the effect kinds allowed, the effective grants), the plans open and recent, the lease. An agent token reads the matters handed to it and those of the mailboxes it operates; the owner reads their own. Requires `assistant:read`. A matter made from authentication mail before such mail was kept out of the assistant is shown with its title, summary, ask and plan effects withheld from a reader without `email:auth_secrets`.

## Path parameters

- `id` string, required

## Response `200`

The envelope

- AssistantTask: The envelope of a matter handed over: the brief and the facts, the delegation with its level and grants, the plans, the lease
  - `id` string, required: The work item id
  - `version` integer, required
  - `status` string, required
  - `deadline` string, date-time, nullable
  - `you` object, required
    - `role` 'owner' | 'assignee', required
    - `holder` string
  - `delegation` object, required
    - `assignee` object, nullable
      - `type` 'agent' | 'member'
      - `ref` string
    - `rule` object, nullable
      - `id` string
      - `name` string
      - `enabled` boolean
      - `level` string
    - `reason` string, nullable
    - `level` 'observe' | 'triage' | 'draft' | 'guarded_send' | 'operate', required
    - `allowed_kinds` string[], required
    - `grants` AssistantGrants, required: Caps on the effects of a level: who an outward effect may reach, how many effects a day, when, how much model spend, which risk classes without an approver, and a required approver. On a rule and on an assignee, the stricter wins
      - `recipients` object
        - `mode` 'correspondents' | 'domains' | 'anyone', required: The matter's correspondents (the default), listed domains, or anyone
        - `domains` string[]
      - `volume` object
        - `effects_per_day` integer, required
      - `schedule` object
        - `hours` integer[]: Start (inclusive) and end (exclusive) hour
        - `days` integer[]: Sunday is zero
        - `timezone` string: An IANA zone; UTC when absent
      - `spend` object
        - `usd_per_day` number
        - `usd_per_matter` number
      - `risk` object
        - `allow` string[]: Risk classes the assignee may act on; none by default
        - `financial_threshold_usd` number: Amounts below this do not make a matter financial
      - `approver` object
        - `member_id` string, required
    - `suspended` boolean, required
  - `lease` AssistantTaskLease
    - `holder` string, required: agent:<slug>, member:<id> or user:<id>
    - `expires_at` string, date-time, required
  - `brief` object, nullable: The matter's brief, as GET /api/assistant/work-items/{id}/brief answers it
  - `facts` object, nullable: The matter's facts, as GET /api/assistant/work-items/{id}/facts answers them
  - `plans` object, required
    - `open` AssistantPlan[], required
      - `id` string, required
      - `status` 'proposed' | 'approved' | 'executing' | 'executed' | 'failed' | 'escalated' | 'rejected' | 'stale' | 'expired', required
      - `requires_approval` boolean, required
      - `requested_by` string, required: assistant, user:<id>, agent:<slug> or member:<id>
      - `level` 'observe' | 'triage' | 'draft' | 'guarded_send' | 'operate', required
      - `rule_id` string, nullable
      - `grant_check` AssistantGrantCheck: The verdict of the validation order for one request: the level, the recipients, the volume, the schedule, the spend, the risk classes of the matter, the required approver
        - `outcome` 'allowed' | 'escalate' | 'approval' | 'rejected', required
        - `effects` object[], required
          - `kind` string, required
          - `check` object, required
            - `outcome` 'allowed' | 'escalate' | 'approval' | 'rejected', required
            - `checks` object[], required
              - …
            - `risk_classes` string[], required
        - `usage` object, required
          - `effects_today` integer, required
          - `spend_today_usd` number, required
      - `effects` AssistantEffect[], required
        - `kind` 'reply' | 'forward' | 'label' | 'snooze' | 'resolve' | 'note' | 'request', required
        - `mailbox_id` string: reply, forward, label: the mailbox of the message
        - `reply_to_message_id` string: reply: the message answered
        - `message_id` string: forward: the message forwarded
        - `message_ids` string[]: label: the messages; the matter's source message by default
        - `to` string[]: reply, forward: the recipients
        - `cc` string[]
        - `body` string: reply: the text
        - `expected_reply` object, nullable: reply: what the matter then waits for
          - `description` string
          - `due_at` string, date-time, nullable
        - `note` string, nullable: forward: a line above the forwarded mail
        - `add` string[]: label: labels added
        - `remove` string[]: label: labels removed
        - `set` string[]: label: the whole new set
        - `until` string, date-time: snooze: until when
        - `reason` string, nullable: resolve: why
        - `text` string: note: the line added to the matter's story
        - `url` string: request: the endpoint called with the matter's envelope
        - `payload` object: request: what travels with the envelope
      - `hash` string
      - `source_revision` integer
      - `receipt_id` string, nullable
      - `expires_at` string, date-time, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `recent` AssistantPlan[], required
      - `id` string, required
      - `status` 'proposed' | 'approved' | 'executing' | 'executed' | 'failed' | 'escalated' | 'rejected' | 'stale' | 'expired', required
      - `requires_approval` boolean, required
      - `requested_by` string, required: assistant, user:<id>, agent:<slug> or member:<id>
      - `level` 'observe' | 'triage' | 'draft' | 'guarded_send' | 'operate', required
      - `rule_id` string, nullable
      - `grant_check` AssistantGrantCheck: The verdict of the validation order for one request: the level, the recipients, the volume, the schedule, the spend, the risk classes of the matter, the required approver
        - `outcome` 'allowed' | 'escalate' | 'approval' | 'rejected', required
        - `effects` object[], required
          - `kind` string, required
          - `check` object, required
            - `outcome` 'allowed' | 'escalate' | 'approval' | 'rejected', required
            - `checks` object[], required
              - …
            - `risk_classes` string[], required
        - `usage` object, required
          - `effects_today` integer, required
          - `spend_today_usd` number, required
      - `effects` AssistantEffect[], required
        - `kind` 'reply' | 'forward' | 'label' | 'snooze' | 'resolve' | 'note' | 'request', required
        - `mailbox_id` string: reply, forward, label: the mailbox of the message
        - `reply_to_message_id` string: reply: the message answered
        - `message_id` string: forward: the message forwarded
        - `message_ids` string[]: label: the messages; the matter's source message by default
        - `to` string[]: reply, forward: the recipients
        - `cc` string[]
        - `body` string: reply: the text
        - `expected_reply` object, nullable: reply: what the matter then waits for
          - `description` string
          - `due_at` string, date-time, nullable
        - `note` string, nullable: forward: a line above the forwarded mail
        - `add` string[]: label: labels added
        - `remove` string[]: label: labels removed
        - `set` string[]: label: the whole new set
        - `until` string, date-time: snooze: until when
        - `reason` string, nullable: resolve: why
        - `text` string: note: the line added to the matter's story
        - `url` string: request: the endpoint called with the matter's envelope
        - `payload` object: request: what travels with the envelope
      - `hash` string
      - `source_revision` integer
      - `receipt_id` string, nullable
      - `expires_at` string, date-time, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
  - `escalations` object[], required: The questions asked on the task, newest first, with their answers
    - `id` string
    - `status` 'open' | 'answered' | 'withdrawn'
    - `asked_by` string
    - `question` string
    - `options` object[]
    - `evidence_refs` string[]
    - `decision_id` string, nullable
    - `plan_id` string, nullable
    - `answer` object, nullable
    - `answered_by` string, nullable
    - `answered_at` string, date-time, nullable
    - `created_at` string, date-time

## Other responses

- `401`: Missing or invalid API key
- `404`: No such task in the caller's scope
- `429`: Rate limit exceeded - wait and retry

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)