---
title: "Read the situation brief for a correspondent"
method: GET
path: "/api/assistant/brief"
tags: ["Mailzero Assistant"]
---

# Read the situation brief for a correspondent

`GET /api/assistant/brief`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/assistant/brief`
- Auth: HTTP bearer

What to know before answering a person: the brief of their most recent active Work item across the mailboxes you may read (or one mailbox), the other items they are behind, and their last ten mails. `brief` is null when nothing was analysed from them yet.

## Query parameters

- `correspondent` string, required
- `mailbox` string

## Response `200`

The correspondent brief

- object
  - `correspondent` string, required
  - `mailboxes` string[], required
  - `brief` AssistantBrief, required: The situation brief of one Work item: everything an agent needs to act without reading the mail
    - `id` string, required
    - `version` integer, required
    - `generated_at` string, date-time, required
    - `title` string, required
    - `summary` string, required
    - `ask` string, nullable
    - `mailbox` object
      - `id` string
      - `address` string
      - `name` string, nullable
      - `operator` 'human' | 'agent'
    - `delegated_to` string, nullable
    - `situation` object, required
      - `key` string
      - `status` string
      - `attention` object
        - `level` string
        - `reason` string
        - `confidence` string
        - `deadline` string, nullable
      - `occurrences` integer
      - `first_seen_at` string, nullable
      - `last_seen_at` string, nullable
      - `sender` object, nullable
        - `address` string
        - `name` string, nullable
        - `kind` string
    - `story` object[], required: Every mail of the situation, oldest first, with the one-line title the analysis gave it
      - `message_id` string
      - `occurred_at` string
      - `sender` string
      - `title` string
      - `analysed` boolean
    - `facts` object[], required
      - `key` string, nullable
      - `subject` string, nullable
      - `predicate` string, nullable
      - `object` string, nullable
      - `value` object, nullable
        - `type` string
        - `value` string, nullable
        - `currency` string, nullable
      - `basis` string, nullable
      - `confidence` number, nullable
      - `valid_from` string, nullable
      - `valid_until` string, nullable
      - `sensitivity` string
      - `evidence_refs` string[]
      - `seen_at` string
    - `entities` object[], required
      - `kind` string
      - `name` string
      - `aliases` string[]
      - `ref` string
    - `commitments` object[], required: Open promises made by the owner's side
      - `id` string
      - `who` string
      - `owed_to` string, nullable
      - `what` string
      - `due_at` string, nullable
      - `overdue` boolean
      - `status` string
    - `expectations` object[], required: Open things awaited from others
      - `id` string
      - `who` string
      - `what` string
      - `due_at` string, nullable
      - `overdue` boolean
      - `status` string
    - `settled` object[], required: Closed loops and receipts, newest first
      - `kind` 'commitment' | 'expectation' | 'receipt'
      - `who` string
      - `what` string
      - `status` string
      - `at` string
    - `awaiting` object[], required
      - `who` string
      - `what` string
      - `since` string
      - `due_at` string, nullable
      - `overdue` boolean
    - `decision` object, nullable: The current prepared Decision with its options
    - `summary_source` 'model' | 'pipeline': Whether the summary is the model's reading of the evidence or the pipeline's own sentence
    - `suggested_next` object, nullable, required
      - `action` string
      - `reason` string
      - `source` 'decision' | 'rule' | 'model'
      - `links` string[]: The URLs the next action needs, verbatim from the evidence (model source only)
      - `options` string[]: The options on offer when the next action is a choice (model source only)
    - `open_questions` string[]: What only the owner can decide before the next action, at most three questions
    - `synthesis` object, nullable: The model call that wrote the summary and next action, null when the brief is deterministic only
      - `model` string
      - `cached` boolean
      - `generated_at` string, date-time
    - `evidence` object[], required
      - `id` string
      - `subject` string, nullable
      - `from` string
      - `received_at` string
      - `conversation_id` string, nullable
      - `excerpt` string, nullable: The first 500 characters of the message's own words, quoted text and signatures removed
      - `details` object, nullable
        - `links` object[]
          - `url` string
          - `kind` 'signature' | 'calendar' | 'payment' | 'document' | 'other'
        - `amounts` object[]
          - `value` number
          - `currency` string
          - `text` string
        - `dates` string[]
        - `asks` string[]
        - `options` string[]
    - `owner_replies` object[]
      - `id` string
      - `thread_id` string
      - `to` string
      - `subject` string, nullable
      - `sent_at` string, date-time
      - `excerpt` string
    - `evidence_refs` string[]
  - `related` object[], required
    - `id` string
    - `title` string
    - `status` string
    - `attention_level` string
    - `occurrences` integer
    - `last_seen_at` string, date-time
  - `recent_mail` object[], required
    - `id` string
    - `thread_id` string
    - `subject` string, nullable
    - `mailbox` string
    - `received_at` string, date-time
  - `generated_at` string, date-time, required

## Other responses

- `400`: correspondent missing or not an address
- `401`: Missing or invalid API key
- `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)