# Update a session (/en/api-reference/api-ref/conversational-ai/platform/update-session)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI API.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-api-v2.txt).


Changes the RTC token or the model context of a running session.

- OpenAPI: /openapi/conversational-ai/rest-api-platform.en.yaml
- Operation ID: update-session
- Method: PATCH
- Path: /v1/projects/{appid}/sessions/{agent_session_id}
- Endpoint: https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/sessions/{agent_session_id}

## Servers

- https://preview.ai.agora.io/conversational-ai

Use this endpoint to renew the agent's RTC token, or to replace the conversation messages or LLM parameters of a running session. Each field you pass replaces its current value as a whole, so include every LLM parameter that must stay. `messages` also replaces the agent's `instructions`, so pass the instructions as the first `system` message to keep them. You can't change other session or transport fields after the session starts.

Support for runtime changes depends on the provider. If the provider can't apply a change, the request fails with `NotImplemented` and the session doesn't change.


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of your project.
- `agent_session_id` (path, required, string) - The ID of the session, returned in `agent_session_id` when you start the session.

## Request body

- `transport` (object) - Changes to the transport. Only the RTC token can change.
  - `transport.token` (string, required) - A new RTC token for the agent. Applies only to sessions that started with a token.
    - Min length: `1`
- `agent` (object) - Changes to the running agent.
  - `agent.overrides` (object) - Values that replace the running agent's current values.
    - `agent.overrides.messages` (array) - Messages that start the conversation history. They follow `instructions`.
      - `agent.overrides.messages.items` (object)
        - `agent.overrides.messages.items.role` (string, required) - The author of the message:

- `system`: An instruction to the model.
- `user`: A message from the user.
- `assistant`: A message from the agent.
          - Allowed: `system` | `user` | `assistant`
        - `agent.overrides.messages.items.content` (string, required) - The text of the message.
    - `agent.overrides.pipeline` (object) - Runtime model parameters.
      - `agent.overrides.pipeline.llm` (object)
        - `agent.overrides.pipeline.llm.params` (object) - Provider-specific LLM parameters. They replace the current `params` object as a whole, so include every parameter that must stay.

### Request body example

```json
{
  "transport": {
    "token": "<your_new_rtc_token>"
  },
  "agent": {
    "overrides": {
      "messages": [
        {
          "role": "system",
          "content": "You are helping the customer with a billing question."
        }
      ],
      "pipeline": {
        "llm": {
          "params": {
            "temperature": 0.2
          }
        }
      }
    }
  }
}
```

## Responses

### 200

The session was updated.

- `agent_session_id` (string, required) - The ID of the session.
- `create_ts` (integer, required) - The time the session was created, as a Unix timestamp in seconds.
- `status` (string, required) - The status of the session:

- `IDLE`: The session is idle.
- `STARTING`: The session is starting.
- `RUNNING`: The session is running.
- `STOPPING`: The session is stopping.
- `STOPPED`: The session has ended.
- `FAILED`: The session failed.
  - Allowed: `IDLE` | `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `FAILED`
### 400

The update was rejected and the session didn't change. For example, `InvalidModuleParameter` when a parameter is invalid for the provider, or `NotImplemented` when the provider doesn't support this runtime change.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 401

Authentication is missing or invalid. The reason is `InvalidPermission`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 404

The resource in the path doesn't exist. The reason is `ResourceNotFound`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 409

`TaskNotRunning`: The session has ended or isn't running yet. `TaskConflict`: Another operation on the session is in progress.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### default

The request failed. The response body contains the `reason` and `detail` of the failure. For possible reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

## Response examples

### 200

```json
{
  "agent_session_id": "a42ac95tp25py49fc37hp94vm67ht52h",
  "create_ts": 1737111452,
  "status": "RUNNING"
}
```