Mantic Conversations API

openapi: 3.2.0
info:
  title: Fast Conversations API
  version: 0.1.0
tags:
- name: Conversations
paths:
  /webapp/conversations:
    post:
      tags:
      - Conversations
      summary: Create Conversation Endpoint
      description: Create a new conversation header for the current user.
      operationId: create_conversation_endpoint_webapp_conversations_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Conversations
      summary: List Conversations Endpoint
      operationId: list_conversations_endpoint_webapp_conversations_get
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 30
          title: Limit
      - name: question_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: Question Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/conversations/{conversation_id}:
    get:
      tags:
      - Conversations
      summary: Get Conversation Endpoint
      operationId: get_conversation_endpoint_webapp_conversations__conversation_id__get
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Conversations
      summary: Patch Conversation Endpoint
      operationId: patch_conversation_endpoint_webapp_conversations__conversation_id__patch
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationPatchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Conversations
      summary: Delete Conversation Endpoint
      operationId: delete_conversation_endpoint_webapp_conversations__conversation_id__delete
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/conversations/{conversation_id}/canvas-hidden-rows:
    get:
      tags:
      - Conversations
      summary: List Canvas Hidden Rows Endpoint
      description: List durable Canvas hides for an owned conversation.
      operationId: list_canvas_hidden_rows_endpoint_webapp_conversations__conversation_id__canvas_hidden_rows_get
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CanvasHiddenRowsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/conversations/{conversation_id}/canvas-hidden-rows/{row_id}:
    put:
      tags:
      - Conversations
      summary: Hide Canvas Row Endpoint
      description: Idempotently hide one Canvas row for an owned conversation.
      operationId: hide_canvas_row_endpoint_webapp_conversations__conversation_id__canvas_hidden_rows__row_id__put
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      - name: row_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 512
          title: Row Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Conversations
      summary: Unhide Canvas Row Endpoint
      description: Idempotently clear one Canvas hide for an owned conversation.
      operationId: unhide_canvas_row_endpoint_webapp_conversations__conversation_id__canvas_hidden_rows__row_id__delete
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      - name: row_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 512
          title: Row Id
      - name: surfaced_at
        in: query
        required: true
        schema:
          type: string
          format: date-time
          title: Surfaced At
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/conversations/{conversation_id}/auto-title:
    post:
      tags:
      - Conversations
      summary: Request Auto Title Endpoint
      description: '(Re)attempt auto-title generation for an untitled conversation.


        Enqueues the idempotent title job when the conversation is owned by the

        user, still has a NULL title, and has at least one message; otherwise a

        no-op. Backfills titles for conversations (e.g. started in the floating

        chat) whose first-turn auto-title never landed.'
      operationId: request_auto_title_endpoint_webapp_conversations__conversation_id__auto_title_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTitleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/conversations/{conversation_id}/messages:
    get:
      tags:
      - Conversations
      summary: Get Conversation Messages Endpoint
      operationId: get_conversation_messages_endpoint_webapp_conversations__conversation_id__messages_get
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessagesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Conversations
      summary: Append Conversation Messages Endpoint
      description: 'Persist client-supplied messages to a conversation.


        Used to commit the "New question" ephemeral illustrative pair (a synthetic

        user message + the assistant''s explainer) once the user actually engages —

        i.e. before their first real follow-up turn, or on draft submit. The normal

        streaming path only persists the agent''s own turn, so these client-injected

        messages need an explicit append. Malformed parts are dropped by

        :func:`conversation_store.persist_turn`.


        ``system`` is rejected: those rows carry server-authored markers (a re-anchor,

        for instance), so a client could otherwise author authoritative-looking state.'
      operationId: append_conversation_messages_endpoint_webapp_conversations__conversation_id__messages_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppendMessagesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppendMessagesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/conversations/{conversation_id}/canvas-topics:
    post:
      tags:
      - Conversations
      summary: Canvas Topics Endpoint
      description: Topics grouping the given questions on the canvas; empty when they cannot be named.
      operationId: canvas_topics_endpoint_webapp_conversations__conversation_id__canvas_topics_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CanvasTopicsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CanvasTopicsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/conversations/{conversation_id}/messages/stream:
    post:
      tags:
      - Conversations
      summary: Stream Conversation Message Endpoint
      description: 'Stream a single conversation turn in Vercel AI SDK v6 format.


        Runs the Pydantic AI agent on the stored thread continued by the newest message the

        client sent, and streams the response as SSE. Persists the turn and updates recency

        on completion.'
      operationId: stream_conversation_message_endpoint_webapp_conversations__conversation_id__messages_stream_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/conversations/{conversation_id}/messages/stream/cancel:
    post:
      tags:
      - Conversations
      summary: Cancel Conversation Stream Endpoint
      description: 'Abandon a turn on the user''s behalf (Stop, or Discard on a dead turn).


        Removes the turn entirely, prompt included — the user has taken their words

        back, so they belong in the composer, not the thread. Only deliberate intent

        reaches here; a dropped connection does not.


        ``message_id`` names the turn when the caller knows it, so a second tab cannot

        abandon a turn this one started; without it, every unanswered prompt goes.

        Owner-scoped, and a no-op (still 202) when there is nothing to abandon.

        Async only to set the stream''s asyncio.Event on its own loop; the request-session read runs

        in the threadpool, as in `delete_conversation_endpoint`.'
      operationId: cancel_conversation_stream_endpoint_webapp_conversations__conversation_id__messages_stream_cancel_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: integer
          title: Conversation Id
      - name: message_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Message Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ConversationDetail:
      properties:
        id:
          type: integer
          title: Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        context_kind:
          type: string
          enum:
          - general
          - question
          title: Context Kind
        context_entity_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Context Entity Id
        context_question_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Context Question Title
        summary_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary Text
        schema_version:
          type: integer
          title: Schema Version
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - title
      - context_kind
      - context_entity_id
      - summary_text
      - schema_version
      - created_at
      - updated_at
      title: ConversationDetail
      description: Full conversation header — single ``GET /webapp/conversations/{id}``.
    CreateConversationRequest:
      properties:
        context_kind:
          type: string
          enum:
          - general
          - question
          title: Context Kind
          default: general
        context_entity_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Context Entity Id
      type: object
      title: CreateConversationRequest
      description: Body for ``POST /webapp/conversations``.
    ConversationMessageView:
      properties:
        id:
          type: integer
          title: Id
        conversation_id:
          type: integer
          title: Conversation Id
        role:
          type: string
          enum:
          - user
          - assistant
          - system
          - tool
          title: Role
        parts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Parts
        schema_version:
          type: integer
          title: Schema Version
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - conversation_id
      - role
      - parts
      - schema_version
      - created_at
      title: ConversationMessageView
      description: 'One message row served to the client.


        ``parts`` is the Vercel AI SDK v6 ``UIMessage.parts`` array, untruncated

        on the wire (the stream-side truncation applies only to the SSE frame).'
    CanvasTopicsRequest:
      properties:
        question_ids:
          items:
            type: integer
          type: array
          maxItems: 40
          minItems: 2
          title: Question Ids
      type: object
      required:
      - question_ids
      title: CanvasTopicsRequest
      description: Body for ``POST /{id}/canvas-topics``.
    ConversationPatchRequest:
      properties:
        title:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Title
        context_kind:
          anyOf:
          - type: string
            enum:
            - general
            - question
          - type: 'null'
          title: Context Kind
        context_entity_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Context Entity Id
      type: object
      title: ConversationPatchRequest
      description: 'Body for ``PATCH /webapp/conversations/{id}`` — partial update.


        All fields optional. ``title`` set to empty string clears the title.

        When ``context_kind`` is provided the conversation is re-anchored

        (``general`` requires a null entity; ``question`` requires an entity id).'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ConversationMessagesResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ConversationMessageView'
          type: array
          title: Items
        next_before:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Before
          description: Cursor for the next-older page in `<created_at_iso>_<id>` form. Null when there are no further pages.
        server_time:
          type: string
          format: date-time
          title: Server Time
          description: Server clock at response time. The client measures how long a turn has been unanswered against this, not the browser clock, which can be skewed by minutes.
      type: object
      required:
      - items
      title: ConversationMessagesResponse
      description: Cursor-paginated chunk of message history (newest-first).
    CanvasHiddenRowsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/CanvasHiddenRowView'
          type: array
          title: Items
      type: object
      required:
      - items
      title: CanvasHiddenRowsResponse
      description: Hidden Canvas rows for one owned conversation.
    CanvasTopicsResponse:
      properties:
        topics:
          items:
            $ref: '#/components/schemas/QuestionTopic'
          type: array
          title: Topics
      type: object
      required:
      - topics
      title: CanvasTopicsResponse
    ConversationSummary:
      properties:
        id:
          type: integer
          title: Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        context_kind:
          type: string
          enum:
          - general
          - question
          title: Context Kind
        context_entity_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Context Entity Id
        context_question_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Context Question Title
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - title
      - context_kind
      - context_entity_id
      - created_at
      - updated_at
      title: ConversationSummary
      description: Sidebar item — minimal projection for the conversations list.
    AppendMessagesResponse:
      properties:
        persisted:
          type: integer
          title: Persisted
      type: object
      required:
      - persisted
      title: AppendMessagesResponse
    QuestionTopic:
      properties:
        title:
          type: string
          title: Title
        question_ids:
          items:
            type: integer
          type: array
          title: Question Ids
      type: object
      required:
      - title
      - question_ids
      title: QuestionTopic
      description: A named topic and its questions, in the order given.
    AutoTitleResponse:
      properties:
        enqueued:
          type: boolean
          title: Enqueued
      type: object
      required:
      - enqueued
      title: AutoTitleResponse
      description: Body for ``POST /webapp/conversations/{id}/auto-title``.
    AppendMessagesRequest:
      properties:
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Messages
      type: object
      required:
      - messages
      title: AppendMessagesRequest
      description: Body for ``POST /{id}/messages`` — persist client-supplied v6 UIMessages.
    CanvasHiddenRowView:
      properties:
        row_id:
          type: string
          title: Row Id
        hidden_at:
          type: string
          format: date-time
          title: Hidden At
      type: object
      required:
      - row_id
      - hidden_at
      title: CanvasHiddenRowView
      description: One durable Canvas hide, including its conflict-resolution timestamp.
    ConversationListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ConversationSummary'
          type: array
          title: Items
        total:
          type: integer
          title: Total
      type: object
      required:
      - items
      - total
      title: ConversationListResponse
      description: Paginated list of conversation headers (offset/limit pagination).
  securitySchemes:
    OAuth2AuthorizationCodeBearer:
      type: oauth2
      flows:
        authorizationCode:
          scopes: {}
          authorizationUrl: https://app.mantic.com/auth/oauth2/authorize
          tokenUrl: https://app.mantic.com/auth/oauth2/token