TRtriggerdotdev
sessions

Update a session

Changed on

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.

patch/api/v1/sessions/{session}

Request

Request body

tagsstring[]

Replaces the tags on the session row.

metadataobject nullable

Replaces the metadata. Pass null to clear it.

externalIdstring nullable

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.

Response

Session updated successfully

idstring required

The session's friendly ID, prefixed with session_.

externalIdstring nullable

Your stable identity for the session, if one was set.

typestring required

The session type discriminator.

taskIdentifierstring required

The task this session triggers runs against.

currentRunIdstring nullable

Friendly ID of the live run for this session, if any. Prefixed with run_. Omitted on list rows.

tagsstring[] required

Tags on the session row.

metadataobject nullable

Arbitrary JSON metadata, or null if unset.

closedAtstring date-time nullable

When the session was closed, or null if open.

closedReasonstring nullable

The optional reason recorded when the session was closed.

expiresAtstring date-time nullable

The session's retention deadline, or null if none.

createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "id": "session_abc123",
  "externalId": "chat_1234",
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "triggerConfig": {
    "machine": "small-1x",
    "lockToVersion": "20240523.1"
  },
  "currentRunId": "run_def456",
  "tags": [
    "chat:1234"
  ]
}

Changes