# Update a session

Update an OrchaJS session name or metadata with .update() without starting a new run.

Source: https://orcha.sh/docs/sessions/update
Markdown: https://orcha.sh/docs/sessions/update.mdx

Use `.update()` to change the name or application metadata of a session:

```ts
const session = await orcha.supportAgent.update(sessionId, {
  name: "Escalated order ord_1001",
  metadata: {
    priority: "urgent",
    assignedTeam: "fulfillment",
  },
});
```

The returned value is the updated
[`SessionSnapshot`](/docs/sessions/get).

## Update one field

Metadata is merged, so you only need to send fields that changed:

```ts
const session = await orcha.supportAgent.update(sessionId, {
  metadata: {
    priority: "resolved",
  },
});

console.log(session.metadata);
// {
//   customerId: "cus_123",  Existing value remains.
//   priority: "resolved",   Supplied value is updated.
// }
```

Use `null` as an application-level empty value:

```ts
await orcha.supportAgent.update(sessionId, {
  metadata: {
    assignedTeam: null,
  },
});
```

This sets the value to `null`; it does not remove the key.

## API reference

```ts
update(
  sessionId: string,
  update: {
    name?: string;
    metadata?: Record<string, string | number | boolean | null>;
  },
): Promise<SessionSnapshot>
```

- `sessionId` — the existing session to update.
- `name` — replaces the current display name.
- `metadata` — shallowly merges supplied keys into existing metadata.
- At least one of `name` or `metadata` is required.
- Metadata values must be strings, finite numbers, booleans, or `null`.
- The promise resolves with the complete updated snapshot.

Every successful update appends a durable `session.updated` event. Updating
name or metadata does not start a run, send a model request, or alter the
conversation.

Do not store secrets in session metadata.