docs: document the Sessions HTTP API (reference, channels, scopes)

[ericallam]

Summary

Documents the Sessions HTTP API for non-SDK and server-to-server callers, which until now appeared only in the conceptual ai-chat/sessions page.

What's covered

• Sessions API reference — create/list/retrieve/update/close added to the OpenAPI spec and a new "Sessions API" group (management/sessions/*), mirroring the Runs API.
• Channel endpoints — a reference page for the .in/.out realtime HTTP endpoints (append, SSE read, records drain), the wire protocol, Last-Event-ID resume, and the per-direction auth boundary (.out append is secret-key only).
• Session scopes — read:sessions:{id} / write:sessions:{id} in the authentication docs, with the capability boundary and the 1h token TTL.

Cross-linked with the SDK-side ai-chat/sessions page. Verified by rendering each page on the Mintlify dev server.

[changeset-bot]

⚠️ No Changeset found

Latest commit: b5b06ee

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
trigger	🟢 Ready	View Preview	Jun 14, 2026, 11:11 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Walkthrough

This PR adds a complete Sessions API to the OpenAPI spec with five new path operations (create, list, retrieve, update, close) and eight new component schemas plus three reusable parameters. Corresponding MDX stub pages are created for each operation and wired into the docs.json navigation under a new "Sessions API" group. A new channels.mdx page documents the raw HTTP endpoints for session .in/.out channel interactions. A "Session scopes" section is added to authentication.mdx covering public token scope definitions and enforcement boundaries. Existing cross-references in docs/ai-chat/sessions.mdx are updated to clarify externalId immutability and point to the new channel and scope documentation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description provides a comprehensive summary of changes and what is covered, but does not follow the provided template structure with required sections.	Follow the repository template by including issue reference, contributing guide checklist, testing steps, changelog, and other standard sections to ensure consistency with repository conventions.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: documenting the Sessions HTTP API with references, channels, and scopes guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/tri-10876-docs-add-a-sessions-api-group-to-the-api-reference

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

Devin Review found 1 new potential issue.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 3b1b2539-2ec6-4ed3-9ea1-d4851604658d

📥 Commits

Reviewing files that changed from the base of the PR and between 2f33c66 and b5b06ee.

📒 Files selected for processing (3)

• docs/ai-chat/sessions.mdx
• docs/management/authentication.mdx
• docs/v3-openapi.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/management/authentication.mdx

📜 Review details

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/CLAUDE.md)

docs/**/*.mdx: MDX documentation pages must include frontmatter with title (required), description (required), and sidebarTitle (optional) in YAML format
Use Mintlify components for structured content: , , , , , , /, /
Always import from @trigger.dev/sdk in code examples (never from @trigger.dev/sdk/v3)
Code examples must be complete and runnable where possible
Use language tags in code fences: typescript, bash, json

Files:

• docs/ai-chat/sessions.mdx

🧠 Learnings (2)

📚 Learning: 2026-03-10T12:44:14.176Z

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3200
File: docs/config/config-file.mdx:353-368
Timestamp: 2026-03-10T12:44:14.176Z
Learning: In the trigger.dev repo, docs PRs are often companions to implementation PRs. When reviewing docs PRs (MDX files under docs/), check the PR description for any companion/related PR references and verify that the documented features exist in those companion PRs before flagging missing implementations. This ensures docs stay in sync with code changes across related PRs.

Applied to files:

• docs/ai-chat/sessions.mdx

📚 Learning: 2026-04-30T20:30:29.458Z

Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3226
File: docs/ai-chat/quick-start.mdx:13-13
Timestamp: 2026-04-30T20:30:29.458Z
Learning: In this repo’s documentation MDX files (`docs/**/*.mdx`), use `ts` and `tsx` (not `typescript`) as the code-fence language tags for TypeScript/TSX snippets. Do not flag `ts`/`tsx` code-fence language tags as incorrect in any docs MDX file, since this is the site-wide Mintlify-compatible convention.

Applied to files:

• docs/ai-chat/sessions.mdx

🪛 LanguageTool

docs/ai-chat/sessions.mdx

[grammar] ~141-~141: Ensure spelling is correct
Context: ...ession. externalId is read-only after create: it cannot be changed or cleared (it key...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (4)

docs/v3-openapi.yaml (2)

3353-3353: LGTM!

Also applies to: 3580-3603

---

3433-3435: LGTM!

Also applies to: 4421-4423

docs/ai-chat/sessions.mdx (2)

1-5: Frontmatter is complete and valid.

All required fields (title, description) and optional field (sidebarTitle) are present in YAML format.

---

29-315: Code examples are correctly formatted and use the right import sources.

All TypeScript code examples use ts language tags (per repo convention) and import from @trigger.dev/sdk, not @trigger.dev/sdk/v3. Examples are complete and illustrate the concepts clearly.