> ## 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. # 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. ## OpenAPI ````yaml v3-openapi POST /api/v1/sessions 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: post: tags: - sessions summary: Create a session description: >- 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. operationId: create_session_v1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSessionRequestBody' responses: '200': description: >- An open session already existed for this `externalId`. The existing session is returned with `isCached: true`. content: application/json: schema: $ref: '#/components/schemas/CreatedSessionResponseBody' '201': description: Session created and its first run triggered. content: application/json: schema: $ref: '#/components/schemas/CreatedSessionResponseBody' '401': description: Unauthorized '409': description: >- An `externalId` was reused, but its session is already closed or expired. Closed and expired sessions cannot be reopened. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- Validation failed — for example the request body exceeds 32KB, or `externalId` starts with the reserved `session_` prefix. content: application/json: schema: $ref: '#/components/schemas/ErrorWithDetailsResponse' security: - secretKey: [] - publicAccessToken: [] x-codeSamples: - lang: typescript label: Start a session source: >- 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 components: schemas: CreateSessionRequestBody: type: object description: >- Body for `POST /api/v1/sessions`. The whole body must be 32KB or smaller. required: - type - taskIdentifier - triggerConfig properties: type: type: string minLength: 1 maxLength: 64 description: >- Free-form discriminator for the session, e.g. `chat.agent`. Not validated against an enum. example: chat.agent taskIdentifier: type: string minLength: 1 maxLength: 128 description: The task this session triggers runs against. example: my-chat triggerConfig: $ref: '#/components/schemas/SessionTriggerConfig' externalId: type: string minLength: 1 maxLength: 256 description: >- 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`. example: chat_1234 tags: type: array maxItems: 10 items: type: string maxLength: 128 description: Up to 10 tags on the session row, for dashboard filtering. metadata: type: object additionalProperties: true description: Arbitrary JSON metadata. expiresAt: type: string format: date-time description: Absolute expiry timestamp for retention. CreatedSessionResponseBody: allOf: - $ref: '#/components/schemas/SessionObject' - type: object required: - runId - publicAccessToken - isCached properties: runId: type: string description: Friendly ID of the first run triggered alongside the session. example: run_def456 publicAccessToken: type: string description: >- 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: type: boolean description: >- `true` if an open session already existed for this `externalId` (idempotent upsert), `false` if newly created. ErrorResponse: type: object properties: error: type: string example: Something went wrong required: - error 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. 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 securitySchemes: secretKey: type: http scheme: bearer description: > Use a named environment API key. It starts with `tr_dev_sk_`, `tr_prod_sk_`, `tr_stg_sk_`, etc. Create a named API key in the API Keys section of your Trigger.dev project dashboard. Choose the narrowest access preset that supports your integration. 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_sk_1234" }); ``` publicAccessToken: type: http scheme: bearer description: > A short-lived JWT scoped to specific resources, returned as `publicAccessToken` from APIs such as `wait.createToken()` / `POST /api/v1/waitpoints/tokens` and `sessions.start()` / `POST /api/v1/sessions`, or minted directly with `auth.createPublicToken()`. This token is safe to embed in frontend clients — it can only act on the resources its scopes grant (e.g. `read:sessions:{id}`, `write:sessions:{id}`) and cannot be used for any other API operations. For session tokens see the [session scopes](/management/authentication#session-scopes). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.