> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tai42.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set a conversation thread's control mode

> Set the per-thread mode override for ``thread_id`` on ``route_name`` to ``mode`` (one
of ``agent``/``manual``), returning ``{"route_name", "thread_id", "mode", "source"}`` with
``source`` always ``thread`` — a set writes an override.

This is the door an EXTERNAL/programmatic caller names a thread through; an agent flipping
its OWN live conversation uses the ``set_conversation_mode`` builtin instead, which reads
the current thread from the turn context rather than naming it.

Caller authority is the door's grantable ``write`` action. The thread-belongs-to-route
guard is the thread delete's: a route-keyed id off the route is a 400, a person thread off
the named route a 404. An unknown route is a loud 404; a blank ``thread_id`` or a ``mode``
outside the vocabulary is a 400.



## OpenAPI

````yaml /openapi.json put /api/conversations/{route_name}/thread/mode
openapi: 3.1.0
info:
  description: The operator HTTP surface served under /api/*.
  title: tai42-skeleton API
  version: 14.0.2
servers: []
security: []
paths:
  /api/conversations/{route_name}/thread/mode:
    put:
      tags:
        - conversations
      summary: Set a conversation thread's control mode
      description: >-
        Set the per-thread mode override for ``thread_id`` on ``route_name`` to
        ``mode`` (one

        of ``agent``/``manual``), returning ``{"route_name", "thread_id",
        "mode", "source"}`` with

        ``source`` always ``thread`` — a set writes an override.


        This is the door an EXTERNAL/programmatic caller names a thread through;
        an agent flipping

        its OWN live conversation uses the ``set_conversation_mode`` builtin
        instead, which reads

        the current thread from the turn context rather than naming it.


        Caller authority is the door's grantable ``write`` action. The
        thread-belongs-to-route

        guard is the thread delete's: a route-keyed id off the route is a 400, a
        person thread off

        the named route a 404. An unknown route is a loud 404; a blank
        ``thread_id`` or a ``mode``

        outside the vocabulary is a 400.
      operationId: put_api_conversations_route_name_thread_mode
      parameters:
        - in: path
          name: route_name
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThreadModeSet'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ThreadModeSetResult'
                required:
                  - data
                type: object
          description: Success.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Malformed request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid api key.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Resource not found.
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ThreadModeSet:
      description: >-
        The mode-set door's JSON body ``{thread_id, mode}``. ``thread_id`` holds
        at least one

        non-whitespace character and ``mode`` is one of the control-mode
        vocabulary.


        Spec metadata only — the door parses this body at the HTTP edge.
      properties:
        mode:
          description: 'The control mode to set: ``agent`` or ``manual``.'
          enum:
            - agent
            - manual
          title: Mode
          type: string
        thread_id:
          description: The thread whose mode override to set, as the send door returned it.
          minLength: 1
          pattern: \S
          title: Thread Id
          type: string
      required:
        - thread_id
        - mode
      title: ThreadModeSet
      type: object
    ThreadModeSetResult:
      description: A per-thread mode override write; ``source`` is always ``thread``.
      properties:
        mode:
          title: Mode
          type: string
        route_name:
          title: Route Name
          type: string
        source:
          title: Source
          type: string
        thread_id:
          title: Thread Id
          type: string
      required:
        - route_name
        - thread_id
        - mode
        - source
      title: ThreadModeSetResult
      type: object
    Error:
      properties:
        code:
          description: >-
            Stable machine-readable reason a client keys a dedicated error state
            on, present on refusals that opt in (e.g. a 501 not-configured
            refusal). Optional: absent when the error carries only a
            human-readable message.
          type: string
        error:
          type: string
      required:
        - error
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````