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

# Move a session into another chat, or start a fresh one

> Sets which chat the session's prompts go to. Name a `chatId` from `listChats`
to carry on that conversation — the agent picks it up with its history.
Omit `chatId`, or send `null`, to start a fresh chat; like a new session's
first chat, it is only stored once you send something in it.

A run in the session's previous chat keeps going to the end, and that chat
stays in your list if anything was said in it. Read its messages to follow
the run, or switch back to carry on in it. Closing the session stops every
run it has going.

A chat belongs to one session at a time. If another of your sessions is in
the chat you name, or left a run going there, this session takes it over:
the other session's run in it is stopped, and if it was in that chat it
continues in a fresh one. Its ids are returned in `takenOverFrom`.

Your API chats also appear in the web app, where you can watch a session
work and take a chat over. The session's run there stops, and its prompts
to that chat answer `409 CHAT_TAKEN_OVER` until a session reopens the chat
here. Reopening takes it back from the web app, including when it is the
chat the session is already in. A chat with a run going in the web app
cannot be opened or reopened until that run ends; the switch answers
`409 CHAT_IN_USE` and changes nothing.

Otherwise, naming the chat the session is already in changes nothing.




## OpenAPI

````yaml /openapi/davinci-public.v2.yaml put /api/v2/projects/{projectId}/sessions/{sessionId}/chat
openapi: 3.1.0
info:
  title: Davinci Public API
  version: 2.0.0
  description: >
    Public Routing Server API contract for Davinci integrations and official
    SDKs.


    Most operations live on the canonical `/api/v2/projects` mount and accept a

    personal access token (`dav_ak_live_…` / `dav_ak_test_…`) or browser access

    token. Evaluation-run creation is the deliberate exception: it accepts only
    a

    `purpose=automation` grant issued to a running Code execution.

    Project membership and role are checked on every user call, and an API key
    is

    additionally bounded by the permission ceiling derived from its scopes — a
    key

    can never exceed what its owner can do, and usually does less.


    Collaboration operations (invitations, membership changes, ownership
    transfer)

    are deliberately absent: they require a browser session and are not part of
    the

    programmatic surface.


    ## Two planes


    Most operations are **control plane**: they run on the Routing Server, take

    small requests, and answer quickly. A few are **data plane**, marked

    `x-plane: data`, and go straight to the machine holding your project — the
    only

    practical way to move multi-gigabyte files or hold a connection open for
    half

    an hour.


    Data-plane operations use a different host and a different credential.
    Create a

    session on a project and it returns both: a `dataPlane.url` to send to and a

    short-lived `dataPlane.token` (`dav_gr_…`, a *grant*) to send with. A grant

    reaches exactly one project, carries no more permission than the key that

    minted it, expires in minutes, and dies when its session closes. It is not

    interchangeable with an API key in either direction.


    The data-plane host never names a specific machine, so a project that moves

    between machines mid-session stays reachable at the same URL.
servers:
  - url: https://davinci-app.com
    description: Production (control plane)
  - url: https://davinci-app.com/data
    description: >-
      Production (data plane). Serves the operations marked `x-plane: data`,
      using a session's grant rather than an API key.
security:
  - ApiKeyBearer: []
tags:
  - name: Projects
    description: >-
      Create, inspect, open, close, and delete projects, and manage their
      attached files.
  - name: Content
    description: >
      Read and write the objects a project is made of. These reach the running

      project rather than storage, so they see uncommitted work — and so they
      open

      the project if it is not already open.
  - name: Branches
    description: >
      Branches, commits, and the history of a single object. A commit captures
      the

      running project's state, so these operations need the branch loaded, which
      they

      arrange for the caller.
  - name: Sessions
    description: >
      A session opens a project, holds it open, and issues the grant that
      reaches the

      data plane. It is the programmatic equivalent of having a project open in
      a

      browser tab: while it lives, the project stays loaded.


      It is also where the agent lives. Send it a prompt, read its status from
      the

      session, read the transcript back, and stop a run that is going the wrong
      way.
  - name: Chats
    description: >
      Your persistent conversations with a project's agent. A chat outlives the

      session it was started in: list your chats, read any of them back, move a

      session into one to carry on where it left off, and delete the ones you
      are

      done with.


      A new session starts in a fresh chat, whose id is in the session's
      `chatId`.

      A chat is only stored once something is sent in it, so a session that
      never

      sends a message leaves nothing behind. A run keeps going after its session

      moves to another chat, so one session can have several chats working at

      once. Name a chat's `chatId` on `sendAgentMessage` or `stopAgent` to reach
      it

      without moving the session; `agent.chats` on the session read reports
      every

      chat the session has a run in. A chat belongs to one session at a time;

      moving a session into a chat another session has, or sending in it, takes
      it

      over, and if that other session was in it, it continues in a fresh chat of

      its own.


      These are the chats started through the API — from the SDKs, a terminal,
      or

      an app built on them. Chats started in the Davinci web app are a separate
      set

      and do not appear here. These chats do appear in the web app, though,
      where

      you can watch a session work in one and take it over (see
      `switchSessionChat`).
  - name: AgentModels
    description: >
      Chat models available to your account. The returned keys are the values
      accepted

      by the session message API; availability follows your subscription,
      tenant, and

      any profile assigned to your account.
  - name: Tools
    description: >
      Invoke one of the agent's tools yourself, without the agent. Useful when
      you

      already know the operation you want and do not need a model to choose it —
      and

      when you want a deterministic result rather than an interpreted one.


      A tool is still held to the permissions of the credential invoking it, so
      a

      key cannot reach through a tool to something its scopes exclude.
  - name: Files
    description: >
      Data-plane file transfer. These reach your project's machine directly
      using a

      session's grant, which is what allows request bodies far larger than the

      control plane accepts.
  - name: Usage
    description: >
      What your models cost, broken down by model, project, session, or day.
      These

      read the usage ledger, which records one event per completed provider call
      —

      not your balances and limits, which are `/api/v2/users/me/accounting`.


      Usage is reported on an interval rather than per call, so a run that is
      still

      going may not be fully counted yet. Every response carries `asOf`, the
      moment

      the newest counted event was recorded, so you can see how current a total
      is

      instead of guessing.


      This is separate from `projects:read` on purpose: a key that reads your

      project data is not thereby allowed to see what you spend.
  - name: Evaluations
    description: |
      Lifecycle for the ephemeral target sandbox an evaluation runs against.
      Creation is available only to a `purpose=automation` grant issued to a
      running Code execution, so a sandbox always belongs to code rather than to
      a person's key. It returns a second, `purpose=evaluation` grant bound to
      the new sandbox; it never upgrades or replaces the source credential.
  - name: Tests
    description: >
      Asynchronously run an authored Test. The Test executes its linked Code

      object and applies its native evaluation criteria to derive the verdict.

      This is one way to start Code, not a prerequisite for anything the Code
      can

      do: the same function called directly holds the same authority.
  - name: Organizations
    description: Discover organizations available as containers for team planning.
  - name: Cards
    description: >
      Project-scoped agile cards, their index hierarchy, comments, tags,
      assignees,

      card dependencies, and design-object references, plus the caller's
      assigned

      cards across projects. Project access is checked on every call; an

      inaccessible project is reported as not found.
  - name: Teams
    description: >
      Organization-scoped team boards, linked projects, workflow columns,
      sprints,

      analytics, and card placements. Team visibility is privacy preserving:

      inaccessible organizations, private teams, and cross-organization ids are

      reported as not found rather than revealing that they exist.
paths:
  /api/v2/projects/{projectId}/sessions/{sessionId}/chat:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/SessionId'
    put:
      tags:
        - Chats
      summary: Move a session into another chat, or start a fresh one
      description: >
        Sets which chat the session's prompts go to. Name a `chatId` from
        `listChats`

        to carry on that conversation — the agent picks it up with its history.

        Omit `chatId`, or send `null`, to start a fresh chat; like a new
        session's

        first chat, it is only stored once you send something in it.


        A run in the session's previous chat keeps going to the end, and that
        chat

        stays in your list if anything was said in it. Read its messages to
        follow

        the run, or switch back to carry on in it. Closing the session stops
        every

        run it has going.


        A chat belongs to one session at a time. If another of your sessions is
        in

        the chat you name, or left a run going there, this session takes it
        over:

        the other session's run in it is stopped, and if it was in that chat it

        continues in a fresh one. Its ids are returned in `takenOverFrom`.


        Your API chats also appear in the web app, where you can watch a session

        work and take a chat over. The session's run there stops, and its
        prompts

        to that chat answer `409 CHAT_TAKEN_OVER` until a session reopens the
        chat

        here. Reopening takes it back from the web app, including when it is the

        chat the session is already in. A chat with a run going in the web app

        cannot be opened or reopened until that run ends; the switch answers

        `409 CHAT_IN_USE` and changes nothing.


        Otherwise, naming the chat the session is already in changes nothing.
      operationId: switchSessionChat
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchSessionChatRequest'
      responses:
        '200':
          description: The session is in the chat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwitchSessionChatResponse'
        '400':
          description: '`chatId` is not a chat id. Error code is `INVALID_CHAT_ID`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >
            No such session (`SESSION_NOT_FOUND`), or no such chat among yours
            in this

            project (`CHAT_NOT_FOUND`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: >
            Another session moved into the same chat at the same moment

            (`CHAT_SWITCH_CONFLICT`; retry), or the chat has a run going in the
            web

            app (`CHAT_IN_USE`; retry once it ends).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - ApiKeyBearer: []
      x-codeSamples:
        - lang: typescript
          label: TypeScript SDK
          source: |
            import { DavinciClient } from '@celedon/davinci-sdk';

            const client = new DavinciClient({
              apiKey: process.env.DAVINCI_API_KEY!,
            });

            const { chats } = await client.chats.list(projectId);
            const session = await client.sessions.create(projectId);
            await session.switchChat(chats[0].id);
            await session.sendMessage('Where did we leave the bracket?');
        - lang: python
          label: Python SDK
          source: |
            import os
            from davinci_sdk import DavinciClient

            with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
                chats = client.chats.list(project_id).chats
                with client.sessions.create(project_id) as session:
                    session.switch_chat(chats[0].id)
                    session.send_message("Where did we leave the bracket?")
components:
  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
        minLength: 1
      description: Project id. May be compound in the form `{projectId}--{branchName}`.
    SessionId:
      name: sessionId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Session id from `createSession`.
  schemas:
    SwitchSessionChatRequest:
      type: object
      properties:
        chatId:
          type:
            - string
            - 'null'
          format: uuid
          description: >
            The chat to carry on in. Omit it, or send null, to start a fresh
            chat.
      additionalProperties: false
    SwitchSessionChatResponse:
      type: object
      required:
        - sessionId
        - previousChatId
        - chat
      properties:
        sessionId:
          type: string
          format: uuid
        previousChatId:
          type: string
          format: uuid
          description: >-
            The chat the session was in before. The same as `chat.id` when
            nothing changed.
        chat:
          $ref: '#/components/schemas/Chat'
        takenOverFrom:
          type: array
          description: >
            Your other sessions this chat was taken from. Each one's run here
            was

            stopped, and one that was in the chat was moved to a fresh one.
            Absent

            when no session had the chat.
          items:
            type: string
            format: uuid
      additionalProperties: true
    ErrorEnvelope:
      description: >
        The error shape for every failure on this API, whether it was refused by
        the

        credential layer before reaching a domain or by the domain itself.


        Branch on `code`, which is stable. `message` is for a person reading a
        log or

        a dialog and may be reworded. `details` carries fields specific to one

        failure — a project-limit refusal reports its numbers there — and is
        absent

        when there are none.
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
          additionalProperties: true
      additionalProperties: true
    Chat:
      type: object
      required:
        - id
        - title
        - messageCount
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        title:
          type:
            - string
            - 'null'
          description: >
            Named from the conversation's opening unless `renameChat` set it;
            null

            until it has one.
        messageCount:
          type: integer
          minimum: 0
          description: >
            Entries stored in the conversation — prompts, replies, and tool use.
            Zero

            for a fresh chat nothing has been sent in yet.
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Null for a fresh chat, which is not stored until its first message.
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Last activity. Null for a fresh chat.
      additionalProperties: true
  responses:
    Unauthorized:
      description: >
        No credential was supplied, or the supplied credential is malformed,
        expired,

        or revoked. A credential that is present but unusable is never
        downgraded to

        an anonymous request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: >
        Authenticated but not authorized. Either the acting user lacks the
        required

        resource permission, the key's scope ceiling excludes it, or the
        endpoint

        rejects this credential type (`CREDENTIAL_NOT_PERMITTED`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: Request rate exceeded, either globally or for this key.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 1
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: dav_ak_live_... or dav_ak_test_...
      x-default: dav_ak_live_your_token
      description: >
        Personal access token. The scopes granted at issuance determine both
        which

        operations the key may call and the ceiling on the resource permissions
        it

        can exercise. Each scope family is a ladder: `projects:manage` implies

        `projects:write` and `projects:read`; `cards:manage` implies
        `cards:write`

        and `cards:read`; and `teams:manage` implies `teams:write` and
        `teams:read`.

        These are named API capability bundles, not blanket domain roles:

        `manage` exposes only the permissions enumerated for that scope and
        never

        bypasses the acting user's current role-based access.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.