Create session

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

Start a session

TypeScript

import { sessions } from "@trigger.dev/sdk";

const { id, runId, publicAccessToken, isCached } = await sessions.start({
  type: "chat.agent",
  externalId: chatId,
  taskIdentifier: "my-chat",
  triggerConfig: {
    basePayload: { chatId },
    tags: [`chat:${chatId}`],
  },
});

console.log(id);       // e.g. "session_abc123"
console.log(runId);    // the first run, e.g. "run_def456"
console.log(isCached); // false on a brand-new session

200

{
  "id": "session_abc123",
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "tags": [
    "chat:1234"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "runId": "run_def456",
  "publicAccessToken": "<string>",
  "isCached": true,
  "externalId": "chat_1234",
  "triggerConfig": {
    "basePayload": {},
    "machine": "small-1x",
    "queue": "<string>",
    "tags": [
      "<string>"
    ],
    "maxAttempts": 5,
    "maxDuration": 2,
    "lockToVersion": "20240523.1",
    "region": "<string>",
    "idleTimeoutInSeconds": 1800
  },
  "currentRunId": "run_def456",
  "metadata": {},
  "closedAt": "2023-11-07T05:31:56Z",
  "closedReason": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

Authorizations

secretKeypublicAccessToken

Authorization · string · header · required

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.

import { configure } from "@trigger.dev/sdk";

configure({ accessToken: "tr_dev_1234" });

Body

application/json

Body for POST /api/v1/sessions. The whole body must be 32KB or smaller.

type · string · required

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

Required string length: 1 - 64

Example:

"chat.agent"

taskIdentifier · string · required

The task this session triggers runs against.

Required string length: 1 - 128

Example:

"my-chat"

triggerConfig · object · required

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.

Show child attributes

externalId · string

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.

Required string length: 1 - 256

Example:

"chat_1234"

tags · string[]

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

Maximum array length: 10

Maximum string length: 128

metadata · object

Arbitrary JSON metadata.

expiresAt · string<date-time>

Absolute expiry timestamp for retention.

Response

200

application/json

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

A session row.

id · string · required

The session's friendly ID, prefixed with session_.

Example:

"session_abc123"

type · string · required

The session type discriminator.

Example:

"chat.agent"

taskIdentifier · string · required

The task this session triggers runs against.

Example:

"my-chat"

tags · string[] · required

Tags on the session row.

Example:

["chat:1234"]

createdAt · string<date-time> · required

updatedAt · string<date-time> · required

runId · string · required

Friendly ID of the first run triggered alongside the session.

Example:

"run_def456"

publicAccessToken · string · 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.

isCached · boolean · required

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

externalId · string | null

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

Example:

"chat_1234"

triggerConfig · object

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.

Show child attributes

currentRunId · string | null

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

Example:

"run_def456"

metadata · object

Arbitrary JSON metadata, or null if unset.

closedAt · string<date-time> | null

When the session was closed, or null if open.

closedReason · string | null

The optional reason recorded when the session was closed.

expiresAt · string<date-time> | null

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