---
title: "List Messages"
method: GET
path: "/api/v1alpha1/assistant/trademe/conversations/{conversation_id}/messages"
tags: ["v1alpha1"]
---

# List Messages

`GET /api/v1alpha1/assistant/trademe/conversations/{conversation_id}/messages`

List messages for a conversation with block downgrade for client capabilities.

Why Accept-Nodes is a required header (not optional, not a query param):
- Required: forces clients to declare capabilities; no silent degraded experiences.
- Header: content negotiation is a header concern (HTTP Accept-* convention); no
  URL encoding issues; FastAPI parses comma-separated values natively.
- Same semantics as POST /rpc initialize acceptNodes — different encoding per call site.

Blocks are returned already hydrated — the streaming markdown parser populates
all snapshot fields at parse time.  The REST endpoint applies only the block
downgrade step (no artifact fetching).

## Path parameters

- `conversation_id` string, required

## Query parameters

- `after_seq` integer, nullable
- `before_seq` integer, nullable
- `limit` integer
- `order` 'asc' | 'desc'

## Headers

- `accept-nodes` string[], required — Required. Comma-separated list of supported node types and versions in type:version format. e.g. 'plain_text:1, map:1'. Mirrors the capabilities declaration sent on POST /rpc initialize. Server downgrades nodes to the highest mutually supported version; nodes with no fallback are omitted. Using a required header follows HTTP content negotiation conventions (Accept, Accept-Language) — this is what Accept-* headers exist for.
- `authorization` string, nullable

## Response `200`

Successful Response

- MessageListResponse — Domain MessageListResponse with camelCase wire aliases.
  - `messages` Message[], required
    - `id` string
    - `conversationId` string, required
    - `kind` 'user' | 'response' | 'update', required
    - `state` 'pending' | 'complete' | 'removed'
    - `author` union, required
      - MemberAuthor — Domain MemberAuthor with camelCase wire aliases.
        - `authorType` 'member'
        - `memberId` string, required
        - `displayName` string, nullable
      - AssistantAuthor — Domain AssistantAuthor with camelCase wire aliases.
        - `authorType` 'assistant'
        - `assistantId` string, required
        - `assistantVersion` string, required
        - `parametersVersion` string, required
        - `contextId` string, required
    - `blocks` union[]
      - union
        - PlainTextBlock — Plain unformatted text. The baseline block type all clients must support.
          - `type` 'plain_text'
          - `version` '1'
          - `text` string, required
        - RichTextBlock — Top-level wrapper that groups markdown/richtext blocks as a logical unit. Separates standard markdown content (``heading``, ``paragraph``, ``code``, ``blockquote``, ``list``, ``divider``) from custom interactive components (``choices``, listing summaries, search results) at the top level of a message. This enables independent versioning of the richtext contract without versioning every individual block type. Children are restricted to the same set of block types permitted in ``ChildBlock`` — custom/complex components are not valid children and must appear at the top level alongside ``RichTextBlock``, not inside it. :ivar children: Richtext child blocks (typed as ``ChildBlock`` to enforce the top-level-only constraint on custom components at schema validation time).
          - `children` union[]
            - union
              - …
          - `type` 'rich_text'
          - `version` '1'
        - ListingPhotoBlock — A Trade Me listing photo with structured metadata. Only emitted from listing data (e.g. ``PropertyListingDetails.photos``), never from inline markdown promotion. :ivar photo_id: Trade Me photo identifier (the ``Key`` field). :ivar listing_id: Listing this photo belongs to. :ivar photo_index: Zero-based position in the photo gallery. :ivar urls: Named size map (``Thumbnail``, ``List``, ``Medium``, ``Gallery``, ``Large``, ``FullSize``, ``PlusSize``). :ivar original_width: Pixel width of the original image (must be > 0). :ivar original_height: Pixel height of the original image (must be > 0). :ivar alt: Alternative text description.
          - `type` 'listing_photo'
          - `version` '1'
          - `photoId` string, required
          - `listingId` string, required
          - `photoIndex` integer, required
          - `urls` object, required
          - `originalWidth` integer, required
          - `originalHeight` integer, required
          - `alt` string
        - ImageBlock — A standalone image block for any non-listing-photo image. Used for inline-promoted images (markdown ``![alt](url)``), AI-generated images, user-provided images, and external images. The ``source`` field is server-set provenance — clients use it as a rendering hint (trust indicators, "AI image" labels, caching strategy). :ivar url: Image URL (already sanitised — no query string or fragment). :ivar alt: Alternative text description. :ivar width: Optional pixel width. :ivar height: Optional pixel height. :ivar aspect_ratio: Optional pre-computed aspect ratio. :ivar description: Extended description (AI prompt or richer alt text). :ivar source: Server-set provenance: - ``"trademe"`` — URL on Trade Me infrastructure (CDN, assets). - ``"user_provided"`` — uploaded by the conversation participant. - ``"external"`` — not on Trade Me infrastructure. - ``"ai_generated"`` — AI-generated image.
          - `type` 'image_block'
          - `version` '1'
          - `url` string, required
          - `alt` string, required
          - `width` integer, nullable
          - `height` integer, nullable
          - `aspectRatio` number, nullable
          - `description` string, nullable
          - `source` 'trademe' | 'user_provided' | 'external' | 'ai_generated'
        - ChoicesBlock — A labelled group of selectable chip buttons. Parsed from the inline tag:: <choices label="Favourite colour" type="single" items='["Red","Blue","Green"]' /> The model writes choices inline (no artifact fetch required). Clients that don't support ``choices:1`` receive a markdown fallback rendered by :func:`render_block`. :ivar label: Human-readable question / prompt label shown above the chips. :ivar selection_type: ``"single"`` — auto-fires after a 3 s countdown; ``"multi"`` — accumulates selections, user fires manually. :ivar choices: Ordered list of :class:`ChoiceItem` instances.
          - `type` 'choices'
          - `version` '1'
          - `label` string, required
          - `selectionType` 'single' | 'multi'
          - `choices` ChoiceItem[]
            - `id` string, required
            - `label` string, required
        - CrisisResourceBlock
          - `type` 'crisis_resource'
          - `version` '1'
          - `name` string, required
          - `text` string, required
          - `phone` string, nullable
          - `sms` string, nullable
          - `url` string, nullable
          - `artifactUri` string, nullable
        - ListingSummaryBlock — Configuration-driven listing summary. The server controls which fields appear and in what order via the ``fields`` list.
          - `listingId` string, required
          - `title` string, nullable
          - `tva` TemplatedViewAddress, required — Structured navigation address compatible with Koru's responseAddress shape. :ivar view_name: Koru view name, e.g. ``"ListingDetailsPage"``. :ivar uri: Canonical URL string (same role as the old ``canonical_url``). :ivar parameters: Typed key/value parameters for the view. :ivar annotation: Optional human-readable link metadata. :ivar relative_path: Path portion of ``uri`` with the Trade Me web ``/a/`` prefix stripped, intended for client-side routing. ``None`` when uri is empty or unparseable. Not suitable as input to ``build_listing_url()`` — that function expects the canonical_path form which includes the ``/a/`` segment.
            - `viewName` string, required
            - `uri` string, required
            - `parameters` TVAParameter[]
              - …
            - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
              - …
          - `isOnWatchlist` boolean, nullable
          - `type` 'listing_summary'
          - `version` '1'
          - `images` string[]
          - `imagesEnabled` boolean
          - `fields` union[]
            - union
              - …
        - GeneralListingSummaryWithCoordinatesBlock — A generic listing summary block that includes geographic coordinates. Used as a fallback for vertical-specific blocks that carry coordinates when the client does not support the vertical-specific type but does support ``listing_summary_with_coordinates:1``.
          - `latitude` number, required
          - `longitude` number, required
          - `listingId` string, required
          - `title` string, nullable
          - `tva` TemplatedViewAddress, required — Structured navigation address compatible with Koru's responseAddress shape. :ivar view_name: Koru view name, e.g. ``"ListingDetailsPage"``. :ivar uri: Canonical URL string (same role as the old ``canonical_url``). :ivar parameters: Typed key/value parameters for the view. :ivar annotation: Optional human-readable link metadata. :ivar relative_path: Path portion of ``uri`` with the Trade Me web ``/a/`` prefix stripped, intended for client-side routing. ``None`` when uri is empty or unparseable. Not suitable as input to ``build_listing_url()`` — that function expects the canonical_path form which includes the ``/a/`` segment.
            - `viewName` string, required
            - `uri` string, required
            - `parameters` TVAParameter[]
              - …
            - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
              - …
          - `isOnWatchlist` boolean, nullable
          - `type` 'listing_summary_with_coordinates'
          - `version` '1'
          - `images` string[]
        - PropertyResiForSaleListingSummaryBlock — Vertical-specific listing summary for property residential for-sale listings. Version ``"1"`` of this type — it is a purpose-built new block type, not a revision of an existing one. Clients that do not advertise support for ``(property_resi_for_sale_listing_summary, 1)`` receive a downgraded ``listing_summary:1`` block via the adapter chain.
          - `iconAttributes` IconAttributeField[]
            - `key` string, required
            - `icon` string, required
            - `displayValue` string, required
            - `rawValue` number, nullable
            - `sortValue` number, nullable
          - `listingId` string, required
          - `title` string, nullable
          - `tva` TemplatedViewAddress, required — Structured navigation address compatible with Koru's responseAddress shape. :ivar view_name: Koru view name, e.g. ``"ListingDetailsPage"``. :ivar uri: Canonical URL string (same role as the old ``canonical_url``). :ivar parameters: Typed key/value parameters for the view. :ivar annotation: Optional human-readable link metadata. :ivar relative_path: Path portion of ``uri`` with the Trade Me web ``/a/`` prefix stripped, intended for client-side routing. ``None`` when uri is empty or unparseable. Not suitable as input to ``build_listing_url()`` — that function expects the canonical_path form which includes the ``/a/`` segment.
            - `viewName` string, required
            - `uri` string, required
            - `parameters` TVAParameter[]
              - …
            - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
              - …
          - `isOnWatchlist` boolean, nullable
          - `type` 'property_resi_for_sale_listing_summary'
          - `version` '1'
          - `price` PropertyListingPriceField, required
            - `displayValue` string, required
            - `asOf` string, required
          - `address` ListingAddressField, required
            - `displayValue` string, required
            - `rawValue` ListingAddressValue, required
              - …
          - `propertyType` string, nullable
          - `openHomes` OpenHomesField
            - `items` OpenHomeTime[], required
              - …
            - `asOf` string, required
          - `listingExtras` string[], nullable
          - `premiumPackageCode` string, nullable
          - `isBold` boolean, nullable
          - `isFeatured` boolean, nullable
          - `isHighlighted` boolean, nullable
          - `has3DTour` boolean, nullable
          - `hasEmbeddedVideo` boolean, nullable
          - `startDate` string, nullable
          - `mainPhoto` string, nullable
          - `photoUrls` string[]
          - `canonicalPath` string, nullable
          - `category` string, nullable
          - `agency` AgencyInfo — Agency information for a property listing. Extends VendorInfo with brand colours and agent list. Fields: name, logo_url (from VendorInfo), logo2_url, large_banner_url, brand_color, foreground_color, agents.
            - `name` string, required
            - `logoUrl` string, nullable
            - `logo2Url` string, nullable
            - `largeBannerUrl` string, nullable
            - `brandColor` string, nullable
            - `foregroundColor` string, nullable
            - `agents` PropertyListingAgent[]
              - …
        - PropertyResiForRentListingSummaryBlock — Vertical-specific listing summary for property residential for-rent listings. Version "1". Clients not supporting (property_resi_for_rent_listing_summary, 1) receive a downgraded listing_summary:1 block via the adapter chain. Reuses PropertyListingPriceField (display_value + as_of), ListingAddressField, AgencyInfo, and PropertyIconKey from this module.
          - `iconAttributes` IconAttributeField[]
            - `key` string, required
            - `icon` string, required
            - `displayValue` string, required
            - `rawValue` number, nullable
            - `sortValue` number, nullable
          - `listingId` string, required
          - `title` string, nullable
          - `tva` TemplatedViewAddress, required — Structured navigation address compatible with Koru's responseAddress shape. :ivar view_name: Koru view name, e.g. ``"ListingDetailsPage"``. :ivar uri: Canonical URL string (same role as the old ``canonical_url``). :ivar parameters: Typed key/value parameters for the view. :ivar annotation: Optional human-readable link metadata. :ivar relative_path: Path portion of ``uri`` with the Trade Me web ``/a/`` prefix stripped, intended for client-side routing. ``None`` when uri is empty or unparseable. Not suitable as input to ``build_listing_url()`` — that function expects the canonical_path form which includes the ``/a/`` segment.
            - `viewName` string, required
            - `uri` string, required
            - `parameters` TVAParameter[]
              - …
            - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
              - …
          - `isOnWatchlist` boolean, nullable
          - `type` 'property_resi_for_rent_listing_summary'
          - `version` '1'
          - `images` string[]
          - `weeklyRent` PropertyListingPriceField, required
            - `displayValue` string, required
            - `asOf` string, required
          - `availableFrom` string, nullable
          - `address` ListingAddressField, required
            - `displayValue` string, required
            - `rawValue` ListingAddressValue, required
              - …
          - `propertyType` string, nullable
          - `isBold` boolean, nullable
          - `isFeatured` boolean, nullable
          - `isHighlighted` boolean, nullable
          - `has3DTour` boolean, nullable
          - `hasEmbeddedVideo` boolean, nullable
          - `agency` AgencyInfo — Agency information for a property listing. Extends VendorInfo with brand colours and agent list. Fields: name, logo_url (from VendorInfo), logo2_url, large_banner_url, brand_color, foreground_color, agents.
            - `name` string, required
            - `logoUrl` string, nullable
            - `logo2Url` string, nullable
            - `largeBannerUrl` string, nullable
            - `brandColor` string, nullable
            - `foregroundColor` string, nullable
            - `agents` PropertyListingAgent[]
              - …
        - MotorsVehicleListingSummaryBlock — Vertical-specific listing summary for motors vehicle listings (cars + motorbikes). Version "1". Clients not supporting (motors_vehicle_listing_summary, 1) receive a downgraded listing_summary:1 block via the adapter chain.
          - `iconAttributes` IconAttributeField[]
            - `key` string, required
            - `icon` string, required
            - `displayValue` string, required
            - `rawValue` number, nullable
            - `sortValue` number, nullable
          - `listingId` string, required
          - `title` string, nullable
          - `tva` TemplatedViewAddress, required — Structured navigation address compatible with Koru's responseAddress shape. :ivar view_name: Koru view name, e.g. ``"ListingDetailsPage"``. :ivar uri: Canonical URL string (same role as the old ``canonical_url``). :ivar parameters: Typed key/value parameters for the view. :ivar annotation: Optional human-readable link metadata. :ivar relative_path: Path portion of ``uri`` with the Trade Me web ``/a/`` prefix stripped, intended for client-side routing. ``None`` when uri is empty or unparseable. Not suitable as input to ``build_listing_url()`` — that function expects the canonical_path form which includes the ``/a/`` segment.
            - `viewName` string, required
            - `uri` string, required
            - `parameters` TVAParameter[]
              - …
            - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
              - …
          - `isOnWatchlist` boolean, nullable
          - `type` 'motors_vehicle_listing_summary'
          - `version` '1'
          - `images` string[]
          - `askingPrice` MotorsVehiclePriceField, required
            - `displayValue` string, required
            - `priceNote` string, nullable
            - `asOf` string, required
          - `dealer` MotorsDealerInfo — Dealer information for a motors listing. name + logo_url inherited from VendorInfo.
            - `name` string, required
            - `logoUrl` string, nullable
            - `brandColor` string, nullable
          - `isDealer` boolean, nullable
        - MarketplaceListingSummaryBlock — Vertical-specific listing summary for marketplace listings (books, clothing, general). Version "1". Clients not supporting (marketplace_listing_summary, 1) receive a downgraded listing_summary:1 block via the adapter chain.
          - `listingId` string, required
          - `title` string, nullable
          - `tva` TemplatedViewAddress, required — Structured navigation address compatible with Koru's responseAddress shape. :ivar view_name: Koru view name, e.g. ``"ListingDetailsPage"``. :ivar uri: Canonical URL string (same role as the old ``canonical_url``). :ivar parameters: Typed key/value parameters for the view. :ivar annotation: Optional human-readable link metadata. :ivar relative_path: Path portion of ``uri`` with the Trade Me web ``/a/`` prefix stripped, intended for client-side routing. ``None`` when uri is empty or unparseable. Not suitable as input to ``build_listing_url()`` — that function expects the canonical_path form which includes the ``/a/`` segment.
            - `viewName` string, required
            - `uri` string, required
            - `parameters` TVAParameter[]
              - …
            - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
              - …
          - `isOnWatchlist` boolean, nullable
          - `type` 'marketplace_listing_summary'
          - `version` '1'
          - `images` string[]
          - `region` string, nullable
          - `closesAt` string, nullable
          - `reservePrice` string, nullable
          - `buyNowPrice` string, nullable
          - `isBuyNow` boolean, nullable
          - `condition` string, nullable
          - `shipping` string, nullable
        - SearchResultsBlock — A set of search results where items may or may not have coordinates. Hydrated by the streaming markdown parser from the artifact store when a ``<search_results data="art://..." />`` tag is encountered. The LLM emits a container type, not a layout type — the client decides how to render (list, carousel, map if coordinates are present). ``prefer_type`` is a model hint the client may ignore. :ivar artifact_uri: Artifact URI for analytics attribution (set by parser). :ivar tool_call_id: FK to AssistantToolCall (from ``artifact.metadata``). :ivar prefer_type: Model hint: ``"map"``, ``"list"``, or ``"carousel"``. :ivar items: Typed listing summary blocks (discriminated by ``type``). :ivar search_metadata: Grouped search context (query TVA + total count).
          - `type` 'search_results'
          - `version` '1'
          - `artifactUri` string, nullable
          - `toolCallId` string, nullable
          - `preferType` string, nullable
          - `items` union[]
            - union
              - …
          - `searchMetadata` SearchMetadata — Metadata about a search result set. Groups search-related context that accompanies a SearchResultsBlock: the labelled query TVA for the "view all" CTA, and the total result count.
            - `searchQuery` SearchQuery — A labelled search query expressed as a TVA.
              - …
            - `totalCount` integer, nullable
        - SearchResultsWithCoordinatesBlock — A set of search results where ALL items are guaranteed to have coordinates. Hydrated by the streaming markdown parser from the artifact store when a ``<search_results_with_coordinates data="art://..." />`` tag is encountered. Type-level contract: every item in ``items`` has ``latitude`` and ``longitude``. The client does not need to perform nil-checks at runtime. :ivar artifact_uri: Artifact URI for analytics attribution (set by parser). :ivar tool_call_id: FK to AssistantToolCall (from ``artifact.metadata``). :ivar prefer_type: Model hint: ``"map"``, ``"list"``, or ``"carousel"``. :ivar items: Typed listing summary blocks with coordinates (discriminated by ``type``). :ivar search_metadata: Grouped search context (query TVA + total count).
          - `type` 'search_results_with_coordinates'
          - `version` '1'
          - `artifactUri` string, nullable
          - `toolCallId` string, nullable
          - `preferType` string, nullable
          - `items` GeneralListingSummaryWithCoordinatesBlock[]
            - `latitude` number, required
            - `longitude` number, required
            - `listingId` string, required
            - `title` string, nullable
            - `tva` TemplatedViewAddress, required — Structured navigation address compatible with Koru's responseAddress shape. :ivar view_name: Koru view name, e.g. ``"ListingDetailsPage"``. :ivar uri: Canonical URL string (same role as the old ``canonical_url``). :ivar parameters: Typed key/value parameters for the view. :ivar annotation: Optional human-readable link metadata. :ivar relative_path: Path portion of ``uri`` with the Trade Me web ``/a/`` prefix stripped, intended for client-side routing. ``None`` when uri is empty or unparseable. Not suitable as input to ``build_listing_url()`` — that function expects the canonical_path form which includes the ``/a/`` segment.
              - …
            - `isOnWatchlist` boolean, nullable
            - `type` 'listing_summary_with_coordinates'
            - `version` '1'
            - `images` string[]
          - `searchMetadata` SearchMetadata — Metadata about a search result set. Groups search-related context that accompanies a SearchResultsBlock: the labelled query TVA for the "view all" CTA, and the total result count.
            - `searchQuery` SearchQuery — A labelled search query expressed as a TVA.
              - …
            - `totalCount` integer, nullable
        - UserFileRefBlock — A reference to a member-uploaded file — byte-free, ref only. Files are general; image-oriented presentation fields are optional since images are the only kind AIS-1157 currently accepts. :ivar ref: ``user://files/<file_id>`` — resolved to a signed URL via ``GET /files/{file_id}/content``, never embedded here. :ivar alt: Alternative text description (client-supplied, optional). :ivar width: Optional pixel width, if known at send time (images only). :ivar height: Optional pixel height, if known at send time (images only).
          - `type` 'user_file_ref'
          - `version` '1'
          - `ref` string, required
          - `alt` string
          - `width` integer, nullable
          - `height` integer, nullable
    - `createdAt` string, date-time
    - `finalisedAt` string, date-time, nullable
    - `seq` integer
    - `inputId` string, nullable
  - `hasMore` boolean, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/trademeai/apis/trade-me-ai-platform.md) · [All operations](https://skmtc.net/trademeai/apis/trade-me-ai-platform/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trademeai/trade-me-ai-platform/revisions/02634860dec7/schema)