---
title: "List generated topic results"
method: GET
path: "/mail-topic-generations"
tags: ["Inbox"]
---

# List generated topic results

`GET /mail-topic-generations`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/mail-topic-generations`
- Auth: HTTP bearer

Mailbox-owned automatic membership and complete generated summary/task snapshots. Each resource has an independent version. Human corrections always take precedence in presentation. Sources must belong to this mailbox and exact visible audience. Provider and input digest are client-reported provenance, not model attestation. This endpoint never writes human corrections. Identical latest mutations are retryable; stale versions return mail_topic_generation_conflict. Source mail remains unchanged. Responses are never cached.

## Query parameters

- `mailbox` string, email, required
- `cursor` string
- `limit` integer

## Response `200`

Current generated results

- object
  - `success` true, required
  - `data` MailTopicGenerationsList, required
    - `mailbox` string, email, required
    - `items` object[], required
      - `generation` union, required
        - object
          - `kind` 'membership', required
          - `topic_id` string, nullable, required
          - `sources` object[], required
            - `direction` 'inbound' | 'outbound', required
            - `message_id` string, required
          - `input_digest` string, required
          - `provider` 'apple-on-device', required
          - `message` object, required
            - `direction` 'inbound' | 'outbound', required
            - `message_id` string, required
        - object
          - `kind` 'intelligence', required
          - `topic_id` string, nullable, required
          - `sources` object[], required
            - `direction` 'inbound' | 'outbound', required
            - `message_id` string, required
          - `input_digest` string, required
          - `provider` 'apple-on-device', required
          - `summary` string, nullable, required
          - `summary_source_message_ids` string[], required
          - `tasks` object[], required
            - `id` string, nullable, required
            - `text` string, nullable, required
            - `source_message_ids` string[], required
            - `evidence` string, nullable, required
      - `version` integer, required
      - `mutation_id` string, required
      - `updated_at` string, required
    - `next_cursor` string, nullable, required

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `404`: Resource not found
- `413`: Request exceeds the 1 MiB encoded payload limit
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

## Changes

> 32 revisions in range; 1 not diffed.

- **2026-11-03** `bce409c97acb`: 1 breaking, 155 warning
  - added `subschema #1, subschema #2` to the `allOf[subschema #2]/data/items/items/generation` response property `oneOf` list for the response status `200`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `400`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `401`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `404`
  - …152 more
  - …this revision’s changelog is incomplete
- **2026-10-21** `0360ea8d4f3d`: 65 warning
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `400`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `401`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `404`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `413`
  - …61 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/primitive/apis/primitive-api/changes/mail-topic-generations/get.md)

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) - [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/primitive/apis/primitive-api/revisions/bce409c97acb?raw)