docs: fix inaccuracies in management API guides

Corrects the management API guides where they had drifted from the SDK
and API.

- Authentication: examples and prose use `accessToken` (with `secretKey`
noted as a deprecated alias), the documented key prefixes match what the
dashboard issues, and personal access tokens are passed as
`accessToken`.
- Errors and retries: the SDK import is `ApiError`, the error body is
`error.error`, and the retry defaults (5 attempts, 1 to 30 second
backoff, which statuses retry) match the client.
- Pagination, overview and multiple clients: fixes the `runs.list`
example, the auto-pagination intro, environment names, and the
`previewBranch` option.
- Session channels: documents the `session-closed` and `pending-version`
control records, the append response (`seq`, `pendingVersion`), the
closed and expired session errors, and the stream format.
- Batches: the error schema uses `error`, and the create-batch request
documents `taskIdentifiers` and the 1,000 item cap.

Fixes to endpoint reference pages generated from the main API spec will
follow in a separate PR.

Mono-RevId: 3fe0d3a3ef8937f32890b553d60708793aaa0adf

Author: isshaddad

docs/management/authentication.mdx

@@ -4,42 +4,42 @@ sidebarTitle: Authentication
 description: Authenticating with the Trigger.dev management API
 ---
 
-There are two methods of authenticating with the management API: using a named API key associated with a specific environment in a project (`secretKey`), or using a personal access token (`personalAccessToken`). Use both methods only on a backend server. An environment API key's access is limited by the preset and task restrictions selected when you create it.
+There are two methods of authenticating with the management API: using a named API key associated with a specific environment in a project, or using a personal access token (PAT). Pass either one as the `accessToken` option (`secretKey` is a deprecated alias). Use both methods only on a backend server. An environment API key's access is limited by the preset and task restrictions selected when you create it.
 
 <Note>
   There is a separate authentication strategy when making requests from your frontend application.
   See the [Realtime guide](/realtime/overview) for more information. This guide is for backend usage
   only.
 </Note>
 
-Certain API functions work with both authentication methods, but require different arguments depending on the method used. For example, the `runs.list` function can be called using either a `secretKey` or a `personalAccessToken`, but the `projectRef` argument is required when using a `personalAccessToken`:
+Certain API functions work with both authentication methods, but require different arguments depending on the method used. For example, the `runs.list` function can be called using either an environment API key or a personal access token, but the `projectRef` argument is required when using a personal access token:
 
 ```ts
 import { configure, runs } from "@trigger.dev/sdk";
 
-// Using secretKey authentication
+// Using accessToken authentication
 configure({
-  secretKey: process.env["TRIGGER_SECRET_KEY"], // starts with tr_dev_sk_, tr_prod_sk_, or tr_preview_sk_
+  accessToken: process.env["TRIGGER_SECRET_KEY"], // starts with tr_dev_, tr_stg_, tr_prod_, or tr_preview_ (named keys add sk_)
 });
 
-function secretKeyExample() {
+function accessTokenExample() {
   return runs.list({
     limit: 10,
     status: ["COMPLETED"],
   });
 }
 
-// Using personalAccessToken authentication
+// Using personal access token authentication
 configure({
-  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
+  accessToken: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
 });
 
 function personalAccessTokenExample() {
-  // Notice the projectRef argument is required when using a personalAccessToken
-  return runs.list("prof_1234", {
+  // Notice the projectRef argument is required when using a personal access token
+  return runs.list("proj_1234", {
     limit: 10,
     status: ["COMPLETED"],
-    projectRef: "tr_proj_1234567890",
+    env: "prod",
   });
 }
 ```
@@ -73,7 +73,7 @@ function personalAccessTokenExample() {
 
 ### Environment API key
 
-Create a named environment API key with the narrowest access preset that supports your integration. Pass it through the `secretKey` option or `TRIGGER_SECRET_KEY` environment variable. Read the [API Keys guide](/apikeys) for available presets and task restrictions.
+Create a named environment API key with the narrowest access preset that supports your integration. Pass it through the `accessToken` option or `TRIGGER_SECRET_KEY` environment variable. Read the [API Keys guide](/apikeys) for available presets and task restrictions.
 
 ### Personal Access Token (PAT)
 
@@ -85,7 +85,7 @@ For example, when uploading environment variables using a PAT, you must provide
 import { configure, envvars } from "@trigger.dev/sdk";
 
 configure({
-  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
+  accessToken: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
 });
 
 await envvars.upload("proj_1234", "dev", {
@@ -108,7 +108,7 @@ When working with preview branches, you may need to target a specific branch whe
 import { configure, envvars } from "@trigger.dev/sdk";
 
 configure({
-  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
+  accessToken: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
   previewBranch: "feature-xyz",
 });
 
@@ -137,8 +137,7 @@ curl --request PUT \
 This will set the `DATABASE_URL` environment variable specifically for the `feature-xyz` preview branch.
 
 <Note>
-  The `x-trigger-branch` header is only relevant when working with the `preview` or `dev` environments (`{env}
-  ` parameter set to `preview` or `development`). It has no effect when working with `staging`, or `prod`
+  The `x-trigger-branch` header is only relevant when working with the `preview` or `dev` environments (`{env}` parameter set to `preview` or `dev`). It has no effect when working with `staging`, or `prod`
   environments.
 </Note>
 
@@ -150,7 +149,7 @@ When using the SDK to manage preview branch environment variables, the branch ta
 import { configure, envvars } from "@trigger.dev/sdk";
 
 configure({
-  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
+  accessToken: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
   previewBranch: "feature-xyz", // Optional: specify the branch
 });
 
@@ -219,7 +218,7 @@ const publicToken = await auth.createPublicToken({
 });
 ```
 
-`sessions` accepts a single ID or an array. The default token TTL is 1 hour. One token authorizes **both** URL forms — pass either your `externalId` or the `session_…` ID in the path.
+`sessions` accepts a single ID or an array. When you mint the token with `auth.createPublicToken()`, the default TTL is 15 minutes (pass `expirationTime` to change it). Tokens returned by `sessions.start()` default to 1 hour. One token authorizes **both** URL forms — pass either your `externalId` or the `session_…` ID in the path.
 
 The `publicAccessToken` returned by [`sessions.start()`](/management/sessions/create) already carries both scopes for the session it created, so you usually don't mint one by hand for the create flow.
 

docs/management/auto-pagination.mdx

@@ -4,7 +4,7 @@ sidebarTitle: Auto-pagination
 description: Using auto-pagination with the Trigger.dev management API
 ---
 
-All list endpoints in the management API support auto-pagination.
+Paginated list methods in the management API (`runs`, `schedules`, `queues`, `deployments`, and others) support auto-pagination.
 You can use `for await … of` syntax to iterate through items across all pages:
 
 ```ts

docs/management/errors-and-retries.mdx

@@ -9,14 +9,14 @@ description: Handling errors and retries with the Trigger.dev management API
 When the SDK method is unable to connect to the API server, or the API server returns a non-successful response, the SDK will throw an `ApiError` that you can catch and handle:
 
 ```ts
-import { runs, APIError } from "@trigger.dev/sdk";
+import { runs, ApiError } from "@trigger.dev/sdk";
 
 async function main() {
   try {
     const run = await runs.retrieve("run_1234");
   } catch (error) {
     if (error instanceof ApiError) {
-      console.error(`API error: ${error.status}, ${error.headers}, ${error.body}`);
+      console.error(`API error: ${error.status} ${error.message}`, error.error);
     } else {
       console.error(`Unknown error: ${error.message}`);
     }
@@ -26,7 +26,7 @@ async function main() {
 
 ## Retries
 
-The SDK will automatically retry requests that fail due to network errors or server errors. By default, the SDK will retry requests up to 3 times, with an exponential backoff delay between retries.
+The SDK will automatically retry requests that fail due to network errors, `5xx` responses, and `408`, `409` and `429` responses. By default, the SDK makes up to 5 attempts per request (`maxAttempts: 5`, so up to 4 retries) with exponential backoff (`minTimeoutInMs` 1000, `maxTimeoutInMs` 30000, `factor` 1.6, `randomize` false). Any retry fields you pass are merged over these defaults.
 
 You can customize the retry behavior by passing a `requestOptions` option to the `configure` function:
 
@@ -58,9 +58,4 @@ async function main() {
     },
   });
 }
-```
-
-<Note>
-  When running inside a task, the SDK ignores customized retry options for certain functions (e.g.,
-  `task.trigger`, `task.batchTrigger`), and uses retry settings optimized for task execution.
-</Note>
+```

docs/management/multiple-clients.mdx

@@ -27,7 +27,7 @@ await preview.runs.list({ status: ["COMPLETED"] });
 | Field           | Description                                                                                              | Env-var fallback                                  |
 | --------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
 | `accessToken`   | Environment API key (`tr_dev_sk_*`, `tr_prod_sk_*`, `tr_preview_sk_*`) or personal access token (`tr_pat_*`). | `TRIGGER_SECRET_KEY`, then `TRIGGER_ACCESS_TOKEN` |
-| `previewBranch` | Preview branch name when using a `tr_preview_sk_*` key.                                                     | `TRIGGER_PREVIEW_BRANCH`, then `VERCEL_GIT_COMMIT_REF` |
+| `previewBranch` | Preview branch name when using a `tr_preview_sk_*` key, or dev branch name for a dev environment.            | `TRIGGER_PREVIEW_BRANCH`, then `VERCEL_GIT_COMMIT_REF`, then `TRIGGER_DEV_BRANCH` |
 | `baseURL`       | Override the Trigger.dev API URL. Defaults to `https://api.trigger.dev`.                                  | `TRIGGER_API_URL`                                 |
 | `requestOptions`| Request-level options (retry policy, additional headers, etc.) — see the `ApiRequestOptions` type.        | —                                                 |
 

docs/management/overview.mdx

@@ -33,7 +33,7 @@ import { configure, runs } from "@trigger.dev/sdk";
 
 configure({
   // this is the default and if the `TRIGGER_SECRET_KEY` environment variable is set, can omit calling configure
-  secretKey: process.env["TRIGGER_SECRET_KEY"],
+  accessToken: process.env["TRIGGER_SECRET_KEY"],
 });
 
 async function main() {

docs/management/sessions/channels.mdx

@@ -25,9 +25,9 @@ curl -X POST "https://api.trigger.dev/realtime/v1/sessions/{session}/in/append"
   --data '{"type":"user-message","text":"hello"}'
 ```
 
-The body is the raw record — any text up to 1MiB (records over the per-record cap return `413`). The response is `{ "ok": true }`.
+The body is the raw record — any text up to 1MiB (records over the per-record cap return `413`). The response is `{ "ok": true, "seq": <number> }`, where `seq` is the sequence number of the appended record. `seq` is omitted when no new record was written, for example when a retry reuses an `X-Part-Id` that was already appended. When the session's run is parked awaiting its deployment, the response also includes `"pendingVersion": true`.
 
-Set the `X-Part-Id` header to a unique value per record to make the append idempotent: replaying the same `X-Part-Id` does not duplicate the record. Appending to a closed or expired session returns `400`.
+Set the `X-Part-Id` header to a unique value per record to make the append idempotent: replaying the same `X-Part-Id` does not duplicate the record. Appending to a closed session returns `409` (`code: "session_closed"`); appending to an expired session returns `400` (`code: "session_expired"`).
 
 <Warning>
   Appending to `.out` requires a **secret key**. A session public token (even one with
@@ -48,27 +48,21 @@ curl -N "https://api.trigger.dev/realtime/v1/sessions/{session}/out" \
 
 | Header | Direction | Description |
 | --- | --- | --- |
-| `Last-Event-ID` | request | Resume after this sequence number. Set it to the last `id:` you received to pick up exactly where you left off after a disconnect. |
+| `Last-Event-ID` | request | Resume after this sequence number. Set it to the `seq_num` of the last record you processed. |
 | `Timeout-Seconds` | request | How long the server holds the stream open with no new records before closing, `1`–`600`. |
 
-Each SSE event carries:
-
-- `id:` — the record's sequence number. Use the most recent one as `Last-Event-ID` to resume.
-- `data:` — a JSON record `{ "data": <record>, "id": <id> }`. For `.out` on a `chat.agent` session, `data` is a UI message chunk (text, reasoning, tool call, or a custom data part).
-
-```text
-id: 42
-data: {"data":{"type":"text","text":"echo: hello"},"id":42}
-```
+The stream is passed through from S2. Events are `batch` (records), `ping` (keepalive) and a final `data: [DONE]`. The `id:` line is an internal S2 cursor (`startSeq,endSeq,byteOffset`); do not parse it. Each `batch` event has `data: {"records":[{"seq_num":42,"timestamp":1712150400000,"body":"{\"data\":<record>,\"id\":\"<partId>\"}","headers":[...]}],"tail":{...}}`, where `body` is a JSON string (empty for control records). See the [stream format](/ai-chat/client-protocol#stream-format-s2) for details.
 
 ### Control records
 
 Some `.out` events are **control records** rather than data. A control record has an empty body and carries a `trigger-control` header naming its subtype:
 
 | Subtype | Meaning |
 | --- | --- |
-| `turn-complete` | The current turn finished. Carries sibling headers `public-access-token` (a refreshed session token), `session-in-event-id`, and `last-event-id`. |
+| `turn-complete` | The current turn finished. Can carry sibling headers `public-access-token` (a refreshed session token), `session-in-event-id`, and `session-in-consumed-id`. It also carries a `session-closed` header (and `session-closed-reason`, when a reason was given) when the session was closed during that turn. |
 | `upgrade-required` | The session needs to hand off to a run on a newer deployed version. |
+| `session-closed` | The session was closed. Carries a `session-closed-reason` header when a reason was given. |
+| `pending-version` | The session's run is waiting for its deployment to land. |
 
 Route control records by their subtype instead of treating them as message content. The TypeScript SDK does this for you — `session.out.read` filters control records out of the chunk stream and surfaces them through `onControl`.
 
@@ -86,12 +80,12 @@ Pass `afterEventId` to return only records after that sequence number; omit it t
 ```json
 {
   "records": [
-    { "data": { "type": "text", "text": "echo: hello" }, "id": 43, "seqNum": 43 }
+    { "data": "{\"type\":\"text\",\"text\":\"echo: hello\"}", "id": "a1b2c3d", "seqNum": 43 }
   ]
 }
 ```
 
-Each record carries `data`, `id`, `seqNum`, and an optional `headers` array (present on control records). Page forward by passing the highest `seqNum` you received as the next `afterEventId`.
+Each record carries `data` (the appended record body as a string), `id` (the part ID: the `X-Part-Id` you sent on append, otherwise a generated ID; empty string on control records), `seqNum` (the sequence number), and an optional `headers` array. Page forward by passing the highest `seqNum` you received as the next `afterEventId`.
 
 ## Authorization
 
@@ -127,4 +121,4 @@ for await (const chunk of stream) {
 }
 ```
 
-See [`session.in`](/ai-chat/sessions#session-in-—-clients-→-task) and [`session.out`](/ai-chat/sessions#session-out-—-task-→-clients) for the full handle API.
+See [`session.in`](/ai-chat/sessions) and [`session.out`](/ai-chat/sessions) for the full handle API.

docs/openapi.yml

@@ -201,7 +201,7 @@ components:
     Error:
       type: object
       properties:
-        message:
+        error:
           type: string
     EventRequest:
       type: object
@@ -291,7 +291,13 @@ components:
         runCount:
           type: integer
           minimum: 1
-          description: Expected number of items in the batch. Must be a positive integer.
+          description: Expected number of items in the batch. Must be a positive integer, up to the server's maximum batch size (1,000 by default; self-hosted instances can configure it). Requests above the maximum return a 400.
+        taskIdentifiers:
+          type: array
+          minItems: 1
+          items:
+            type: string
+          description: Distinct task identifiers of the items in the batch. Used to authorize tokens scoped to specific tasks. If omitted, only credentials with broad task access are accepted.
         parentRunId:
           type: string
           description: Parent run ID (friendly ID) for batchTriggerAndWait.