> ## Documentation Index > Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update session > Update a session's `tags` or `metadata`. Pass `metadata: null` to clear it. Requires a secret key — a session public token cannot update a session. `externalId` is read-only after create: it cannot be changed or cleared. Sending a value different from the current one (including `null` when one is set) returns `422`; sending the same value is accepted as a no-op. ## OpenAPI ````yaml v3-openapi PATCH /api/v1/sessions/{session} openapi: 3.1.0 info: title: Trigger.dev v3 REST API description: >- The REST API lets you trigger and manage runs on Trigger.dev. You can trigger a run, get the status of a run, and get the results of a run. version: 2024-04 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.trigger.dev description: Trigger.dev API security: [] paths: /api/v1/sessions/{session}: parameters: - $ref: '#/components/parameters/session' patch: tags: - sessions summary: Update a session description: >- Update a session's `tags` or `metadata`. Pass `metadata: null` to clear it. Requires a secret key — a session public token cannot update a session. `externalId` is read-only after create: it cannot be changed or cleared. Sending a value different from the current one (including `null` when one is set) returns `422`; sending the same value is accepted as a no-op. operationId: update_session_v1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSessionRequestBody' responses: '200': description: Session updated successfully content: application/json: schema: $ref: '#/components/schemas/SessionObject' '401': description: Unauthorized request '404': description: Session not found '422': description: >- Validation failed — for example an attempt to change `externalId` to a different value, or a body exceeding 32KB. content: application/json: schema: $ref: '#/components/schemas/ErrorWithDetailsResponse' security: - secretKey: [] x-codeSamples: - lang: typescript label: Update a session source: |- import { sessions } from "@trigger.dev/sdk"; const session = await sessions.update(chatId, { tags: ["priority"], metadata: { lastSeenBy: "support" }, }); components: parameters: session: in: path name: session required: true schema: type: string description: >- The session's friendly ID (`session_…`) or your `externalId`. The server disambiguates by the `session_` prefix. example: session_abc123 schemas: UpdateSessionRequestBody: type: object description: >- Body for `PATCH /api/v1/sessions/{session}`. The whole body must be 32KB or smaller. Every field is optional; omitted fields are left unchanged. properties: tags: type: array maxItems: 10 items: type: string maxLength: 128 description: Replaces the tags on the session row. metadata: type: object additionalProperties: true nullable: true description: Replaces the metadata. Pass `null` to clear it. externalId: type: string nullable: true minLength: 1 maxLength: 256 description: >- Read-only after create: cannot be changed or cleared. Sending a value different from the current one (including `null` when one is set) returns `422`; sending the same value is idempotent. SessionObject: type: object description: A session row. required: - id - type - taskIdentifier - tags - createdAt - updatedAt properties: id: type: string description: The session's friendly ID, prefixed with `session_`. example: session_abc123 externalId: type: string nullable: true description: Your stable identity for the session, if one was set. example: chat_1234 type: type: string description: The session type discriminator. example: chat.agent taskIdentifier: type: string description: The task this session triggers runs against. example: my-chat triggerConfig: $ref: '#/components/schemas/SessionTriggerConfig' currentRunId: type: string nullable: true description: >- Friendly ID of the live run for this session, if any. Prefixed with `run_`. Omitted on list rows. example: run_def456 tags: type: array items: type: string description: Tags on the session row. example: - chat:1234 metadata: type: object additionalProperties: true nullable: true description: Arbitrary JSON metadata, or `null` if unset. closedAt: type: string format: date-time nullable: true description: When the session was closed, or `null` if open. closedReason: type: string nullable: true description: The optional reason recorded when the session was closed. expiresAt: type: string format: date-time nullable: true description: The session's retention deadline, or `null` if none. createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorWithDetailsResponse: type: object properties: error: type: string example: Query Error details: type: array items: type: object required: - code - message properties: code: type: string description: The error code example: custom message: type: string description: The error message example: 'Invalid status values: FOOBAR' path: type: array items: type: string description: The relevant path in the request example: - filter[status] required: - error SessionTriggerConfig: type: object description: >- Trigger options applied to every run a session schedules. `basePayload` is the wire payload merged into each run; the remaining fields map onto the standard trigger options. required: - basePayload properties: basePayload: type: object additionalProperties: true description: >- Base payload passed to every run this session triggers. For `chat.agent` this carries `{ chatId, ...clientData }`. machine: type: string description: Machine preset for each run, e.g. `small-1x`. example: small-1x queue: type: string maxLength: 128 description: Queue to schedule runs on. tags: type: array maxItems: 5 items: type: string maxLength: 128 description: Tags applied to every run this session triggers. maxAttempts: type: integer minimum: 1 maximum: 10 description: Maximum retry attempts per run. maxDuration: type: integer minimum: 1 description: Per-run wall-clock cap in seconds. lockToVersion: type: string description: Pin every run to a specific worker version. example: '20240523.1' region: type: string description: Region to schedule runs in. idleTimeoutInSeconds: type: integer minimum: 1 maximum: 3600 description: Idle timeout surfaced to `chat.agent` via the wire payload. securitySchemes: secretKey: type: http scheme: bearer description: > Use your project-specific Secret API key. Will start with `tr_dev_`, `tr_prod`, `tr_stg`, etc. You can find your Secret API key in the API Keys section of your Trigger.dev project dashboard. Our TypeScript SDK will default to using the value of the `TRIGGER_SECRET_KEY` environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the `configure` function. ```typescript import { configure } from "@trigger.dev/sdk"; configure({ accessToken: "tr_dev_1234" }); ``` ````