docs: add list deployments endpoint, fix defaultMachine, and clarify wait token browser completion (#3350)

Adds missing list deployments API page, fixes defaultMachine → machine
in config docs, and clarifies browser CORS usage for wait token
completion with corrected warning placement

Author: isshaddad

docs/config/config-file.mdx

@@ -297,7 +297,7 @@ import { defineConfig } from "@trigger.dev/sdk";
 export default defineConfig({
   project: "<project ref>",
   // Your other config settings...
-  defaultMachine: "large-1x",
+  machine: "large-1x",
 });
 ```
 

docs/docs.json

@@ -306,6 +306,7 @@
           {
             "group": "Deployments API",
             "pages": [
+              "management/deployments/list",
               "management/deployments/retrieve",
               "management/deployments/get-latest",
               "management/deployments/promote"

docs/management/deployments/get-latest.mdx

@@ -2,3 +2,10 @@
 title: "Get latest deployment"
 openapi: "v3-openapi GET /api/v1/deployments/latest"
 ---
+
+<Warning>
+  This endpoint only returns **unmanaged** deployments, which are used in self-hosted setups. It
+  will return `404` for standard CLI deployments made against Trigger.dev Cloud.
+
+  If you're using the CLI to deploy, use the [list deployments](/management/deployments/list) endpoint instead.
+</Warning>

docs/management/deployments/list.mdx

@@ -0,0 +1,5 @@
+---
+title: "List deployments"
+description: "List all deployments for the authenticated environment, ordered by most recent first."
+openapi: "v3-openapi GET /api/v1/deployments"
+---

docs/v3-openapi.yaml

@@ -784,6 +784,145 @@ paths:
 
             await runs.cancel("run_1234");
 
+  "/api/v1/deployments":
+    get:
+      operationId: list_deployments_v1
+      summary: List deployments
+      description: List deployments for the authenticated environment, ordered by most recent first.
+      parameters:
+        - in: query
+          name: "page[after]"
+          schema:
+            type: string
+          description: The deployment ID to start the search from, to get the next page.
+        - in: query
+          name: "page[size]"
+          schema:
+            type: integer
+            minimum: 5
+            maximum: 100
+            default: 20
+          description: The number of deployments to return (default 20, min 5, max 100).
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum:
+              [
+                "PENDING",
+                "BUILDING",
+                "DEPLOYING",
+                "DEPLOYED",
+                "FAILED",
+                "CANCELED",
+                "TIMED_OUT",
+              ]
+          description: Filter deployments by status.
+        - in: query
+          name: period
+          schema:
+            type: string
+          description: Filter deployments created within this period (e.g. 1d, 7d, 3h).
+        - in: query
+          name: from
+          schema:
+            type: string
+          description: Filter deployments created on or after this date (ISO 8601).
+        - in: query
+          name: to
+          schema:
+            type: string
+          description: Filter deployments created on or before this date (ISO 8601). Only applied when `from` is also provided.
+      responses:
+        "200":
+          description: Successful request
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          description: The deployment ID
+                        createdAt:
+                          type: string
+                          format: date-time
+                          description: When the deployment was created
+                        shortCode:
+                          type: string
+                          description: The short code for the deployment
+                        version:
+                          type: string
+                          description: The deployment version (e.g., "20250228.1")
+                        runtime:
+                          type: string
+                          nullable: true
+                          description: The runtime used (e.g., "node")
+                        runtimeVersion:
+                          type: string
+                          nullable: true
+                          description: The runtime version
+                        status:
+                          type: string
+                          enum:
+                            [
+                              "PENDING",
+                              "BUILDING",
+                              "DEPLOYING",
+                              "DEPLOYED",
+                              "FAILED",
+                              "CANCELED",
+                              "TIMED_OUT",
+                            ]
+                          description: The current status of the deployment
+                        deployedAt:
+                          type: string
+                          format: date-time
+                          nullable: true
+                          description: When the deployment was promoted to DEPLOYED
+                        git:
+                          type: object
+                          nullable: true
+                          description: Git metadata associated with the deployment
+                        error:
+                          type: object
+                          nullable: true
+                          description: Error data if the deployment failed
+                  pagination:
+                    type: object
+                    properties:
+                      next:
+                        type: string
+                        description: Cursor for the next page. Pass as `page[after]` to get the next page. Omitted if there are no more results.
+        "401":
+          description: Unauthorized - Access token is missing or invalid
+      tags:
+        - deployments
+      security:
+        - secretKey: []
+      x-codeSamples:
+        - lang: typescript
+          source: |-
+            const response = await fetch(
+              "https://api.trigger.dev/api/v1/deployments",
+              {
+                method: "GET",
+                headers: {
+                  "Authorization": `Bearer ${secretKey}`,
+                },
+              }
+            );
+            const { data, pagination } = await response.json();
+        - lang: curl
+          source: |-
+            curl -X GET "https://api.trigger.dev/api/v1/deployments" \
+              -H "Authorization: Bearer tr_dev_1234"
+
   "/api/v1/deployments/{deploymentId}":
     parameters:
       - in: path

docs/wait-for-token.mdx

@@ -8,7 +8,10 @@ Waitpoint tokens pause task runs until you complete the token. They're commonly
 You can complete a token using the SDK or by making a POST request to the token's URL.
 
 <Note>
-  If you're waiting for data from an [input stream](/tasks/streams#input-streams), use [`inputStream.wait()`](/tasks/streams#wait--suspend-until-data-arrives) instead — it uses waitpoint tokens internally but provides a simpler API with full type safety from your stream definition.
+  If you're waiting for data from an [input stream](/tasks/streams#input-streams), use
+  [`inputStream.wait()`](/tasks/streams#wait--suspend-until-data-arrives) instead — it uses
+  waitpoint tokens internally but provides a simpler API with full type safety from your stream
+  definition.
 </Note>
 
 ## Usage
@@ -54,6 +57,52 @@ await wait.completeToken<ApprovalToken>(tokenId, {
 });
 ```
 
+## Completing from the browser
+
+The `publicAccessToken` returned by `wait.createToken()` is scoped to that specific waitpoint and intended for client-side completion. The completion endpoint has CORS enabled, so you can call it directly from client-side code without proxying through your backend.
+
+<Steps>
+  <Step title="Create the token in your backend">
+    ```typescript
+    import { wait } from "@trigger.dev/sdk";
+
+    const token = await wait.createToken({ timeout: "10m" });
+    // Pass token.id and token.publicAccessToken to your frontend
+    ```
+  </Step>
+  <Step title="Complete the token from the browser">
+    ```typescript
+    // tokenId and publicAccessToken passed from your backend
+    const tokenId = token.id;
+    const publicAccessToken = token.publicAccessToken;
+
+    const response = await fetch(
+      `https://api.trigger.dev/api/v1/waitpoints/tokens/${tokenId}/complete`,
+      {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${publicAccessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ data: { status: "approved" } }),
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`Failed to complete token: ${response.statusText}`);
+    }
+    ```
+  </Step>
+</Steps>
+
+## Completing via webhook callback
+
+<Warning>
+  The `token.url` webhook callback URL is designed for server-to-server use and does **not** have
+  CORS headers. Don't call it from the browser, use the [Completing from the
+  browser](#completing-from-the-browser) pattern instead.
+</Warning>
+
 Or you can make an HTTP POST request to the `url` it returns. This is an HTTP callback:
 
 ```ts