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
This commit is contained in:
Iss
@@ -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",
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
@@ -306,6 +306,7 @@
|
||||
{
|
||||
"group": "Deployments API",
|
||||
"pages": [
|
||||
"management/deployments/list",
|
||||
"management/deployments/retrieve",
|
||||
"management/deployments/get-latest",
|
||||
"management/deployments/promote"
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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"
|
||||
---
|
||||
@@ -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
|
||||
|
||||
+50
-1
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user