---
title: "Create Conversation"
method: POST
path: "/api/v1alpha1/assistant/{assistant_kind}/conversations"
tags: ["v1alpha1"]
---

# Create Conversation

`POST /api/v1alpha1/assistant/{assistant_kind}/conversations`

## Headers

- `is-in-staff-group` string, nullable
- `authorization` string, nullable

## Request body

- CreateConversationBody — Request body for POST /conversations. Accepts camelCase or snake_case keys.
  - `title` string, nullable
  - `referrer` union
    - DirectReferrer — Domain DirectReferrer with camelCase wire aliases.
      - `sourceType` 'direct'
    - HomepageReferrer — Domain HomepageReferrer with camelCase wire aliases.
      - `sourceType` 'homepage'
      - `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[]
          - `key` string, required
          - `value` TypedValue, required — A discriminated-union value carrier for TVA parameters. Exactly one of the four value fields must be non-``None``. An all-``None`` instance is semantically invalid — it represents a parameter with no value.
            - `strValue` string, nullable
            - `numValue` union
              - …
            - `boolValue` boolean, nullable
            - `arrValue` TypedValue[], nullable
        - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
          - `title` string, required
          - `summary` string, nullable
          - `imageUrl` string, nullable
    - PropertyHomepageReferrer — Domain PropertyHomepageReferrer with camelCase wire aliases.
      - `sourceType` 'property_homepage'
    - SearchFormReferrer — Domain SearchFormReferrer with camelCase wire aliases.
      - `sourceType` 'search_form'
      - `tva` TemplatedViewAddress — 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[]
          - `key` string, required
          - `value` TypedValue, required — A discriminated-union value carrier for TVA parameters. Exactly one of the four value fields must be non-``None``. An all-``None`` instance is semantically invalid — it represents a parameter with no value.
            - `strValue` string, nullable
            - `numValue` union
              - …
            - `boolValue` boolean, nullable
            - `arrValue` TypedValue[], nullable
        - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
          - `title` string, required
          - `summary` string, nullable
          - `imageUrl` string, nullable
    - SearchResultsReferrer — Domain SearchResultsReferrer with camelCase wire aliases.
      - `sourceType` 'search_results'
      - `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[]
          - `key` string, required
          - `value` TypedValue, required — A discriminated-union value carrier for TVA parameters. Exactly one of the four value fields must be non-``None``. An all-``None`` instance is semantically invalid — it represents a parameter with no value.
            - `strValue` string, nullable
            - `numValue` union
              - …
            - `boolValue` boolean, nullable
            - `arrValue` TypedValue[], nullable
        - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
          - `title` string, required
          - `summary` string, nullable
          - `imageUrl` string, nullable
    - ListingReferrer — Domain ListingReferrer with camelCase wire aliases.
      - `sourceType` 'listing'
      - `listingId` string, required
      - `listingSummary` ListingSummary — Domain ListingSummary with camelCase wire aliases.
        - `title` string, nullable
        - `priceDisplay` string, nullable
        - `address` string, nullable
        - `suburb` string, nullable
        - `propertyType` string, nullable
        - `bedrooms` integer, nullable
        - `bathrooms` integer, nullable
        - `parking` integer, nullable
        - `floorArea` string, nullable
        - `landArea` string, nullable
        - `tva` TemplatedViewAddress — 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[]
            - `key` string, required
            - `value` TypedValue, required — A discriminated-union value carrier for TVA parameters. Exactly one of the four value fields must be non-``None``. An all-``None`` instance is semantically invalid — it represents a parameter with no value.
              - …
          - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
            - `title` string, required
            - `summary` string, nullable
            - `imageUrl` string, nullable
  - `invitees` string[]
  - `capabilities` string[], nullable

## Response `201`

Successful Response

- ConversationSummary — Domain ConversationSummary with camelCase wire aliases.
  - `id` string, required
  - `title` string, nullable
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `lastMessageAt` string, date-time, nullable
  - `isShared` boolean, required
  - `participants` union[], required
    - union
      - MemberParticipant — Domain MemberParticipant with camelCase wire aliases.
        - `participantType` 'member'
        - `memberId` string, required
        - `displayName` string, nullable
        - `role` 'owner' | 'member' | 'invited'
      - AssistantParticipant — Domain AssistantParticipant with camelCase wire aliases.
        - `participantType` 'assistant'
        - `assistantId` string, required
        - `displayName` string, nullable
  - `assistantStatus` 'idle' | 'running' | 'error'
  - `messageCount` integer
  - `referrer` union
    - DirectReferrer — Domain DirectReferrer with camelCase wire aliases.
      - `sourceType` 'direct'
    - HomepageReferrer — Domain HomepageReferrer with camelCase wire aliases.
      - `sourceType` 'homepage'
      - `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[]
          - `key` string, required
          - `value` TypedValue, required — A discriminated-union value carrier for TVA parameters. Exactly one of the four value fields must be non-``None``. An all-``None`` instance is semantically invalid — it represents a parameter with no value.
            - `strValue` string, nullable
            - `numValue` union
              - …
            - `boolValue` boolean, nullable
            - `arrValue` TypedValue[], nullable
        - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
          - `title` string, required
          - `summary` string, nullable
          - `imageUrl` string, nullable
    - PropertyHomepageReferrer — Domain PropertyHomepageReferrer with camelCase wire aliases.
      - `sourceType` 'property_homepage'
    - SearchFormReferrer — Domain SearchFormReferrer with camelCase wire aliases.
      - `sourceType` 'search_form'
      - `tva` TemplatedViewAddress — 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[]
          - `key` string, required
          - `value` TypedValue, required — A discriminated-union value carrier for TVA parameters. Exactly one of the four value fields must be non-``None``. An all-``None`` instance is semantically invalid — it represents a parameter with no value.
            - `strValue` string, nullable
            - `numValue` union
              - …
            - `boolValue` boolean, nullable
            - `arrValue` TypedValue[], nullable
        - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
          - `title` string, required
          - `summary` string, nullable
          - `imageUrl` string, nullable
    - SearchResultsReferrer — Domain SearchResultsReferrer with camelCase wire aliases.
      - `sourceType` 'search_results'
      - `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[]
          - `key` string, required
          - `value` TypedValue, required — A discriminated-union value carrier for TVA parameters. Exactly one of the four value fields must be non-``None``. An all-``None`` instance is semantically invalid — it represents a parameter with no value.
            - `strValue` string, nullable
            - `numValue` union
              - …
            - `boolValue` boolean, nullable
            - `arrValue` TypedValue[], nullable
        - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
          - `title` string, required
          - `summary` string, nullable
          - `imageUrl` string, nullable
    - ListingReferrer — Domain ListingReferrer with camelCase wire aliases.
      - `sourceType` 'listing'
      - `listingId` string, required
      - `listingSummary` ListingSummary — Domain ListingSummary with camelCase wire aliases.
        - `title` string, nullable
        - `priceDisplay` string, nullable
        - `address` string, nullable
        - `suburb` string, nullable
        - `propertyType` string, nullable
        - `bedrooms` integer, nullable
        - `bathrooms` integer, nullable
        - `parking` integer, nullable
        - `floorArea` string, nullable
        - `landArea` string, nullable
        - `tva` TemplatedViewAddress — 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[]
            - `key` string, required
            - `value` TypedValue, required — A discriminated-union value carrier for TVA parameters. Exactly one of the four value fields must be non-``None``. An all-``None`` instance is semantically invalid — it represents a parameter with no value.
              - …
          - `annotation` LinkAnnotation — Optional human-readable annotation attached to a TVA link.
            - `title` string, required
            - `summary` string, nullable
            - `imageUrl` string, nullable
  - `capabilities` string[], nullable
  - `experimentMetadata` ExperimentMetadata — Domain ExperimentMetadata with camelCase wire aliases (AIS-1065). Without this, the nested keys (is_in_staff_group / served_model) would appear snake_case in the OpenAPI schema — every other nested model on ConversationSummary (referrer, participants) has the same gateway override.
    - `isInStaffGroup` boolean
    - `servedModel` string, nullable
  - `kind` string

## 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/versions/93e6dba49eec/schema)