TRtriggerdotdev
sessions

Create a session

Changed on

Create a Session and trigger its first run in one atomic call. A Session is the durable identity for a bi-directional stream of records (the .in and .out channels) that survives across the runs processing it.

Idempotent on externalId within an environment. Calling create again with an externalId that already maps to an open session returns the existing session with isCached: true and 201 becomes 200. Reusing an externalId whose session is already closed or expired returns 409.

Authorize with a secret key, or a public token carrying write:sessions for the session you are creating.

post/api/v1/sessions

Request

Request body

typestring required

Free-form discriminator for the session, e.g. chat.agent. Not validated against an enum.

taskIdentifierstring required

The task this session triggers runs against.

externalIdstring

Your stable identity for the session, unique per environment. Cannot start with the reserved session_ prefix. Reusing an externalId makes create idempotent; reusing one whose session is closed or expired returns 409.

tagsstring[]

Up to 10 tags on the session row, for dashboard filtering.

metadataobject

Arbitrary JSON metadata.

expiresAtstring date-time

Absolute expiry timestamp for retention.

Example request

{
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "triggerConfig": {
    "machine": "small-1x",
    "lockToVersion": "20240523.1"
  },
  "externalId": "chat_1234"
}

Response

An open session already existed for this externalId. The existing session is returned with isCached: true.

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
runIdstring required

Friendly ID of the first run triggered alongside the session.

publicAccessTokenstring required

Session-scoped public access token carrying read:sessions:{key} and write:sessions:{key}. Default TTL is 1 hour. Safe to pass to frontend clients.

isCachedboolean required

true if an open session already existed for this externalId (idempotent upsert), false if newly created.

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"
  ],
  "runId": "run_def456"
}

Changes