> ## 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.

# Create or replace a conversation route

> Create a conversation route from its flat parameters — an UPSERT, so this is the
create path AND the edit path for a route of that name.

``execution_key`` is the api-key identity the turn runs AS; the caller must be allowed
to delegate it and it must be usable by a tokenless fire, both decided BEFORE the write
so a refusal leaves any existing row untouched. ``agent_name`` must merely EXIST — the
key's live grants bound the turn at fire. A ``channel`` row's ``our_identity`` is stored
canonicalized and must not already be routed on that channel. An ``api`` row's
``callback_secret`` is minted here and returned ONCE. Returns ``{"created",
"route_name", "route", "callback_secret"}``.



## OpenAPI

````yaml /openapi.json post /api/conversations/{route_name}
openapi: 3.1.0
info:
  description: The operator HTTP surface served under /api/*.
  title: tai42-skeleton API
  version: 0.1.1
servers: []
security: []
paths:
  /api/conversations/{route_name}:
    post:
      tags:
        - conversations
      summary: Create or replace a conversation route
      description: >-
        Create a conversation route from its flat parameters — an UPSERT, so
        this is the

        create path AND the edit path for a route of that name.


        ``execution_key`` is the api-key identity the turn runs AS; the caller
        must be allowed

        to delegate it and it must be usable by a tokenless fire, both decided
        BEFORE the write

        so a refusal leaves any existing row untouched. ``agent_name`` must
        merely EXIST — the

        key's live grants bound the turn at fire. A ``channel`` row's
        ``our_identity`` is stored

        canonicalized and must not already be routed on that channel. An ``api``
        row's

        ``callback_secret`` is minted here and returned ONCE. Returns
        ``{"created",

        "route_name", "route", "callback_secret"}``.
      operationId: post_api_conversations_route_name
      parameters:
        - in: path
          name: route_name
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationRouteCreate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data: {}
                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.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden.
        '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:
    ConversationRouteCreate:
      description: >-
        The client-facing create/edit body for a conversation route: the fields
        a caller

        supplies.


        Binds an ``agent_name`` to an ``execution_key`` the turn runs AS (bound
        with

        pass-role at create). ``api`` rows carry an https ``callback_url``;
        ``channel`` rows

        carry the registry ``channel`` plus the ``our_identity`` the medium is
        texted at (N

        rows may share a channel, each its own identity). The server-derived

        ``callback_secret`` and ``execution_key_fingerprint`` are deliberately
        absent;

        :class:`ConversationRoute` is this shape plus those. Frozen.
      properties:
        agent_name:
          minLength: 1
          title: Agent Name
          type: string
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Callback Url
        channel:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Channel
        door:
          enum:
            - api
            - channel
          title: Door
          type: string
        execution_key:
          description: >-
            The api-key ``user_id`` the turn runs AS; its live stored grants
            authorize the agent run and every tool call the turn makes.
          minLength: 1
          title: Execution Key
          type: string
        our_identity:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Our Identity
        route_name:
          title: Route Name
          type: string
      required:
        - route_name
        - door
        - agent_name
        - execution_key
      title: ConversationRouteCreate
      type: object
    Error:
      properties:
        error:
          type: string
      required:
        - error
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````