Skip to content

Commit 6fbd665

Browse files
samejrsamejr
committed
Separates the reference Overview page into new pages
1 parent 3932ad5 commit 6fbd665

File tree

6 files changed

+240
-220
lines changed

6 files changed

+240
-220
lines changed

‎docs/docs.json

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,13 @@
157157
"groups": [
158158
{
159159
"group": "API reference",
160-
"pages": ["management/overview"]
160+
"pages": [
161+
"management/overview",
162+
"management/authentication",
163+
"management/errors-and-retries",
164+
"management/auto-pagination",
165+
"management/advanced-usage"
166+
]
161167
},
162168
{
163169
"group": "Tasks API",

‎docs/management/advanced-usage.mdx

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: Advanced usage
3+
sidebarTitle: Advanced usage
4+
description: Advanced usage of the Trigger.dev management API
5+
---
6+
7+
### Accessing raw HTTP responses
8+
9+
All API methods return a `Promise` subclass `ApiPromise` that includes helpers for accessing the underlying HTTP response:
10+
11+
```ts
12+
import { runs } from "@trigger.dev/sdk/v3";
13+
14+
async function main() {
15+
const { data: run, response: raw } = await runs.retrieve("run_1234").withResponse();
16+
17+
console.log(raw.status);
18+
console.log(raw.headers);
19+
20+
const response = await runs.retrieve("run_1234").asResponse(); // Returns a Response object
21+
22+
console.log(response.status);
23+
console.log(response.headers);
24+
}
25+
```

‎docs/management/authentication.mdx

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Authentication
3+
sidebarTitle: Authentication
4+
description: Authenticating with the Trigger.dev management API
5+
---
6+
7+
There are two methods of authenticating with the management API: using a secret key associated with a specific environment in a project (`secretKey`), or using a personal access token (`personalAccessToken`). Both methods should only be used in a backend server, as they provide full access to the project.
8+
9+
<Note>
10+
There is a separate authentication strategy when making requests from your frontend application.
11+
See the [Frontend guide](/frontend/overview) for more information. This guide is for backend usage
12+
only.
13+
</Note>
14+
15+
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`:
16+
17+
```ts
18+
import { configure, runs } from "@trigger.dev/sdk/v3";
19+
20+
// Using secretKey authentication
21+
configure({
22+
secretKey: process.env["TRIGGER_SECRET_KEY"], // starts with tr_dev_ or tr_prod_
23+
});
24+
25+
function secretKeyExample() {
26+
return runs.list({
27+
limit: 10,
28+
status: ["COMPLETED"],
29+
});
30+
}
31+
32+
// Using personalAccessToken authentication
33+
configure({
34+
secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
35+
});
36+
37+
function personalAccessTokenExample() {
38+
// Notice the projectRef argument is required when using a personalAccessToken
39+
return runs.list("prof_1234", {
40+
limit: 10,
41+
status: ["COMPLETED"],
42+
projectRef: "tr_proj_1234567890",
43+
});
44+
}
45+
```
46+
47+
<Accordion title="View endpoint support">
48+
Consult the following table to see which endpoints support each authentication method.
49+
50+
| Endpoint | Secret key | Personal Access Token |
51+
| ---------------------- | ---------- | --------------------- |
52+
| `task.trigger` | ✅ | |
53+
| `task.batchTrigger` | ✅ | |
54+
| `runs.list` | ✅ | ✅ |
55+
| `runs.retrieve` | ✅ | |
56+
| `runs.cancel` | ✅ | |
57+
| `runs.replay` | ✅ | |
58+
| `envvars.list` | ✅ | ✅ |
59+
| `envvars.retrieve` | ✅ | ✅ |
60+
| `envvars.upload` | ✅ | ✅ |
61+
| `envvars.create` | ✅ | ✅ |
62+
| `envvars.update` | ✅ | ✅ |
63+
| `envvars.del` | ✅ | ✅ |
64+
| `schedules.list` | ✅ | |
65+
| `schedules.create` | ✅ | |
66+
| `schedules.retrieve` | ✅ | |
67+
| `schedules.update` | ✅ | |
68+
| `schedules.activate` | ✅ | |
69+
| `schedules.deactivate` | ✅ | |
70+
| `schedules.del` | ✅ | |
71+
72+
</Accordion>
73+
74+
### Secret key
75+
76+
Secret key authentication scopes the API access to a specific environment in a project, and works with certain endpoints. You can read our [API Keys guide](/apikeys) for more information.
77+
78+
### Personal Access Token (PAT)
79+
80+
A PAT is a token associated with a specific user, and gives access to all the orgs, projects, and environments that the user has access to. You can identify a PAT by the `tr_pat_` prefix. Because a PAT does not scope access to a specific environment, you must provide the `projectRef` argument when using a PAT (and sometimes the environment as well).
81+
82+
For example, when uploading environment variables using a PAT, you must provide the `projectRef` and `environment` arguments:
83+
84+
```ts
85+
import { configure, envvars } from "@trigger.dev/sdk/v3";
86+
87+
configure({
88+
secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
89+
});
90+
91+
await envvars.upload("proj_1234", "dev", {
92+
variables: {
93+
MY_ENV_VAR: "MY_ENV_VAR_VALUE",
94+
},
95+
override: true,
96+
});
97+
```

‎docs/management/auto-pagination.mdx

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Auto-pagination
3+
sidebarTitle: Auto-pagination
4+
description: Using auto-pagination with the Trigger.dev management API
5+
---
6+
7+
All list endpoints in the management API support auto-pagination.
8+
You can use `for await … of` syntax to iterate through items across all pages:
9+
10+
```ts
11+
import { runs } from "@trigger.dev/sdk/v3";
12+
13+
async function fetchAllRuns() {
14+
const allRuns = [];
15+
16+
for await (const run of runs.list({ limit: 10 })) {
17+
allRuns.push(run);
18+
}
19+
20+
return allRuns;
21+
}
22+
```
23+
24+
You can also use helpers on the return value from any `list` method to get the next/previous page of results:
25+
26+
```ts
27+
import { runs } from "@trigger.dev/sdk/v3";
28+
29+
async function main() {
30+
let page = await runs.list({ limit: 10 });
31+
32+
for (const run of page.data) {
33+
console.log(run);
34+
}
35+
36+
while (page.hasNextPage()) {
37+
page = await page.getNextPage();
38+
// ... do something with the next page
39+
}
40+
}
41+
```

‎docs/management/errors-and-retries.mdx

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Errors and Retries
3+
sidebarTitle: Errors and Retries
4+
description: Handling errors and retries with the Trigger.dev management API
5+
---
6+
7+
## Handling errors
8+
9+
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:
10+
11+
```ts
12+
import { runs, APIError } from "@trigger.dev/sdk/v3";
13+
14+
async function main() {
15+
try {
16+
const run = await runs.retrieve("run_1234");
17+
} catch (error) {
18+
if (error instanceof ApiError) {
19+
console.error(`API error: ${error.status}, ${error.headers}, ${error.body}`);
20+
} else {
21+
console.error(`Unknown error: ${error.message}`);
22+
}
23+
}
24+
}
25+
```
26+
27+
## Retries
28+
29+
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.
30+
31+
You can customize the retry behavior by passing a `requestOptions` option to the `configure` function:
32+
33+
```ts
34+
import { configure } from "@trigger.dev/sdk/v3";
35+
36+
configure({
37+
requestOptions: {
38+
retry: {
39+
maxAttempts: 5,
40+
minTimeoutInMs: 1000,
41+
maxTimeoutInMs: 5000,
42+
factor: 1.8,
43+
randomize: true,
44+
},
45+
},
46+
});
47+
```
48+
49+
All SDK functions also take a `requestOptions` parameter as the last argument, which can be used to customize the request options. You can use this to disable retries for a specific request:
50+
51+
```ts
52+
import { runs } from "@trigger.dev/sdk/v3";
53+
54+
async function main() {
55+
const run = await runs.retrieve("run_1234", {
56+
retry: {
57+
maxAttempts: 1, // Disable retries
58+
},
59+
});
60+
}
61+
```
62+
63+
<Note>
64+
When running inside a task, the SDK ignores customized retry options for certain functions (e.g.,
65+
`task.trigger`, `task.batchTrigger`), and uses retry settings optimized for task execution.
66+
</Note>

0 commit comments

Comments
 (0)