diff --git a/docs/docs.json b/docs/docs.json
index b5dd580178..28f60153f3 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -101,55 +101,7 @@
"realtime/subscribe-to-batch"
]
},
- {
- "group": "API reference",
- "pages": [
- "management/overview",
- {
- "group": "Tasks API",
- "pages": ["management/tasks/trigger", "management/tasks/batch-trigger"]
- },
- {
- "group": "Runs API",
- "pages": [
- "management/runs/list",
- "management/runs/retrieve",
- "management/runs/replay",
- "management/runs/cancel",
- "management/runs/reschedule",
- "management/runs/update-metadata"
- ]
- },
- {
- "group": "Schedules API",
- "pages": [
- "management/schedules/list",
- "management/schedules/create",
- "management/schedules/retrieve",
- "management/schedules/update",
- "management/schedules/delete",
- "management/schedules/deactivate",
- "management/schedules/activate",
- "management/schedules/timezones"
- ]
- },
- {
- "group": "Env Vars API",
- "pages": [
- "management/envvars/list",
- "management/envvars/import",
- "management/envvars/create",
- "management/envvars/retrieve",
- "management/envvars/update",
- "management/envvars/delete"
- ]
- },
- {
- "group": "Projects API",
- "pages": ["management/projects/runs"]
- }
- ]
- },
+
{
"group": "CLI",
"pages": [
@@ -169,16 +121,6 @@
}
]
},
- {
- "group": "Open source",
- "pages": [
- "open-source-self-hosting",
- "open-source-contributing",
- "github-repo",
- "changelog",
- "roadmap"
- ]
- },
{
"group": "Troubleshooting",
"pages": [
@@ -192,17 +134,82 @@
"request-feature"
]
},
+ {
+ "group": "Open source",
+ "pages": [
+ "open-source-self-hosting",
+ "open-source-contributing",
+ "github-repo",
+ "changelog",
+ "roadmap"
+ ]
+ },
{
"group": "Help",
"pages": ["community", "help-slack", "help-email"]
}
]
},
+ {
+ "dropdown": "API reference",
+ "description": "The Trigger.dev API",
+ "icon": "code",
+ "groups": [
+ {
+ "group": "API reference",
+ "pages": [
+ "management/overview",
+ "management/authentication",
+ "management/errors-and-retries",
+ "management/auto-pagination",
+ "management/advanced-usage"
+ ]
+ },
+ {
+ "group": "Tasks API",
+ "pages": ["management/tasks/trigger", "management/tasks/batch-trigger"]
+ },
+ {
+ "group": "Runs API",
+ "pages": [
+ "management/runs/list",
+ "management/runs/retrieve",
+ "management/runs/replay",
+ "management/runs/cancel",
+ "management/runs/reschedule",
+ "management/runs/update-metadata"
+ ]
+ },
+ {
+ "group": "Schedules API",
+ "pages": [
+ "management/schedules/list",
+ "management/schedules/create",
+ "management/schedules/retrieve",
+ "management/schedules/update",
+ "management/schedules/delete",
+ "management/schedules/deactivate",
+ "management/schedules/activate",
+ "management/schedules/timezones"
+ ]
+ },
+ {
+ "group": "Env Vars API",
+ "pages": [
+ "management/envvars/list",
+ "management/envvars/import",
+ "management/envvars/create",
+ "management/envvars/retrieve",
+ "management/envvars/update",
+ "management/envvars/delete"
+ ]
+ }
+ ]
+ },
{
"dropdown": "Guides & examples",
"description": "A great way to get started",
- "icon": "book",
-
+ "icon": "books",
"groups": [
{
"group": "Introduction",
@@ -487,6 +494,10 @@
{
"source": "/frontend/react-hooks",
"destination": "/frontend/react-hooks/overview"
+ },
+ {
+ "source": "/management/projects/runs",
+ "destination": "/management/overview"
}
]
}
diff --git a/docs/management/advanced-usage.mdx b/docs/management/advanced-usage.mdx
new file mode 100644
index 0000000000..0413d1690b
--- /dev/null
+++ b/docs/management/advanced-usage.mdx
@@ -0,0 +1,25 @@
+---
+title: Advanced usage
+sidebarTitle: Advanced usage
+description: Advanced usage of the Trigger.dev management API
+---
+
+### Accessing raw HTTP responses
+
+All API methods return a `Promise` subclass `ApiPromise` that includes helpers for accessing the underlying HTTP response:
+
+```ts
+import { runs } from "@trigger.dev/sdk/v3";
+
+async function main() {
+ const { data: run, response: raw } = await runs.retrieve("run_1234").withResponse();
+
+ console.log(raw.status);
+ console.log(raw.headers);
+
+ const response = await runs.retrieve("run_1234").asResponse(); // Returns a Response object
+
+ console.log(response.status);
+ console.log(response.headers);
+}
+```
diff --git a/docs/management/authentication.mdx b/docs/management/authentication.mdx
new file mode 100644
index 0000000000..2d24c1f354
--- /dev/null
+++ b/docs/management/authentication.mdx
@@ -0,0 +1,97 @@
+---
+title: Authentication
+sidebarTitle: Authentication
+description: Authenticating with the Trigger.dev management API
+---
+
+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.
+
+
+ There is a separate authentication strategy when making requests from your frontend application.
+ See the [Frontend guide](/frontend/overview) for more information. This guide is for backend usage
+ only.
+
+
+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`:
+
+```ts
+import { configure, runs } from "@trigger.dev/sdk/v3";
+
+// Using secretKey authentication
+configure({
+ secretKey: process.env["TRIGGER_SECRET_KEY"], // starts with tr_dev_ or tr_prod_
+});
+
+function secretKeyExample() {
+ return runs.list({
+ limit: 10,
+ status: ["COMPLETED"],
+ });
+}
+
+// Using personalAccessToken authentication
+configure({
+ secretKey: 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", {
+ limit: 10,
+ status: ["COMPLETED"],
+ projectRef: "tr_proj_1234567890",
+ });
+}
+```
+
+
+ Consult the following table to see which endpoints support each authentication method.
+
+| Endpoint | Secret key | Personal Access Token |
+| ---------------------- | ---------- | --------------------- |
+| `task.trigger` | ✅ | |
+| `task.batchTrigger` | ✅ | |
+| `runs.list` | ✅ | ✅ |
+| `runs.retrieve` | ✅ | |
+| `runs.cancel` | ✅ | |
+| `runs.replay` | ✅ | |
+| `envvars.list` | ✅ | ✅ |
+| `envvars.retrieve` | ✅ | ✅ |
+| `envvars.upload` | ✅ | ✅ |
+| `envvars.create` | ✅ | ✅ |
+| `envvars.update` | ✅ | ✅ |
+| `envvars.del` | ✅ | ✅ |
+| `schedules.list` | ✅ | |
+| `schedules.create` | ✅ | |
+| `schedules.retrieve` | ✅ | |
+| `schedules.update` | ✅ | |
+| `schedules.activate` | ✅ | |
+| `schedules.deactivate` | ✅ | |
+| `schedules.del` | ✅ | |
+
+
+
+### Secret key
+
+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.
+
+### Personal Access Token (PAT)
+
+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).
+
+For example, when uploading environment variables using a PAT, you must provide the `projectRef` and `environment` arguments:
+
+```ts
+import { configure, envvars } from "@trigger.dev/sdk/v3";
+
+configure({
+ secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
+});
+
+await envvars.upload("proj_1234", "dev", {
+ variables: {
+ MY_ENV_VAR: "MY_ENV_VAR_VALUE",
+ },
+ override: true,
+});
+```
\ No newline at end of file
diff --git a/docs/management/auto-pagination.mdx b/docs/management/auto-pagination.mdx
new file mode 100644
index 0000000000..67fa69467b
--- /dev/null
+++ b/docs/management/auto-pagination.mdx
@@ -0,0 +1,41 @@
+---
+title: Auto-pagination
+sidebarTitle: Auto-pagination
+description: Using auto-pagination with the Trigger.dev management API
+---
+
+All list endpoints in the management API support auto-pagination.
+You can use `for await … of` syntax to iterate through items across all pages:
+
+```ts
+import { runs } from "@trigger.dev/sdk/v3";
+
+async function fetchAllRuns() {
+ const allRuns = [];
+
+ for await (const run of runs.list({ limit: 10 })) {
+ allRuns.push(run);
+ }
+
+ return allRuns;
+}
+```
+
+You can also use helpers on the return value from any `list` method to get the next/previous page of results:
+
+```ts
+import { runs } from "@trigger.dev/sdk/v3";
+
+async function main() {
+ let page = await runs.list({ limit: 10 });
+
+ for (const run of page.data) {
+ console.log(run);
+ }
+
+ while (page.hasNextPage()) {
+ page = await page.getNextPage();
+ // ... do something with the next page
+ }
+}
+```
\ No newline at end of file
diff --git a/docs/management/errors-and-retries.mdx b/docs/management/errors-and-retries.mdx
new file mode 100644
index 0000000000..cbb7ebf3d8
--- /dev/null
+++ b/docs/management/errors-and-retries.mdx
@@ -0,0 +1,66 @@
+---
+title: Errors and retries
+sidebarTitle: Errors and retries
+description: Handling errors and retries with the Trigger.dev management API
+---
+
+## Handling errors
+
+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/v3";
+
+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}`);
+ } else {
+ console.error(`Unknown error: ${error.message}`);
+ }
+ }
+}
+```
+
+## 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.
+
+You can customize the retry behavior by passing a `requestOptions` option to the `configure` function:
+
+```ts
+import { configure } from "@trigger.dev/sdk/v3";
+
+configure({
+ requestOptions: {
+ retry: {
+ maxAttempts: 5,
+ minTimeoutInMs: 1000,
+ maxTimeoutInMs: 5000,
+ factor: 1.8,
+ randomize: true,
+ },
+ },
+});
+```
+
+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:
+
+```ts
+import { runs } from "@trigger.dev/sdk/v3";
+
+async function main() {
+ const run = await runs.retrieve("run_1234", {
+ retry: {
+ maxAttempts: 1, // Disable retries
+ },
+ });
+}
+```
+
+
+ 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.
+
\ No newline at end of file
diff --git a/docs/management/overview.mdx b/docs/management/overview.mdx
index d4a8d3b60d..1c5467006d 100644
--- a/docs/management/overview.mdx
+++ b/docs/management/overview.mdx
@@ -1,7 +1,7 @@
---
-title: Overview & Authentication
-sidebarTitle: Overview & Authentication
-description: Using the Trigger.dev v3 management API
+title: Overview
+sidebarTitle: Overview
+description: Using the Trigger.dev management API
---
## Installation
@@ -44,219 +44,4 @@ async function main() {
}
main().catch(console.error);
-```
-
-## Authentication
-
-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.
-
-
- There is a separate authentication strategy when making requests from your frontend application.
- See the [Frontend guide](/frontend/overview) for more information. This guide is for backend usage
- only.
-
-
-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`:
-
-```ts
-import { configure, runs } from "@trigger.dev/sdk/v3";
-
-// Using secretKey authentication
-configure({
- secretKey: process.env["TRIGGER_SECRET_KEY"], // starts with tr_dev_ or tr_prod_
-});
-
-function secretKeyExample() {
- return runs.list({
- limit: 10,
- status: ["COMPLETED"],
- });
-}
-
-// Using personalAccessToken authentication
-configure({
- secretKey: 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", {
- limit: 10,
- status: ["COMPLETED"],
- projectRef: "tr_proj_1234567890",
- });
-}
-```
-
-
- Consult the following table to see which endpoints support each authentication method.
-
-| Endpoint | Secret key | Personal Access Token |
-| ---------------------- | ---------- | --------------------- |
-| `task.trigger` | ✅ | |
-| `task.batchTrigger` | ✅ | |
-| `runs.list` | ✅ | ✅ |
-| `runs.retrieve` | ✅ | |
-| `runs.cancel` | ✅ | |
-| `runs.replay` | ✅ | |
-| `envvars.list` | ✅ | ✅ |
-| `envvars.retrieve` | ✅ | ✅ |
-| `envvars.upload` | ✅ | ✅ |
-| `envvars.create` | ✅ | ✅ |
-| `envvars.update` | ✅ | ✅ |
-| `envvars.del` | ✅ | ✅ |
-| `schedules.list` | ✅ | |
-| `schedules.create` | ✅ | |
-| `schedules.retrieve` | ✅ | |
-| `schedules.update` | ✅ | |
-| `schedules.activate` | ✅ | |
-| `schedules.deactivate` | ✅ | |
-| `schedules.del` | ✅ | |
-
-
-
-### Secret key
-
-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.
-
-### Personal Access Token (PAT)
-
-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).
-
-For example, when uploading environment variables using a PAT, you must provide the `projectRef` and `environment` arguments:
-
-```ts
-import { configure, envvars } from "@trigger.dev/sdk/v3";
-
-configure({
- secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
-});
-
-await envvars.upload("proj_1234", "dev", {
- variables: {
- MY_ENV_VAR: "MY_ENV_VAR_VALUE",
- },
- override: true,
-});
-```
-
-## Handling errors
-
-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/v3";
-
-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}`);
- } else {
- console.error(`Unknown error: ${error.message}`);
- }
- }
-}
-```
-
-## 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.
-
-You can customize the retry behavior by passing a `requestOptions` option to the `configure` function:
-
-```ts
-import { configure } from "@trigger.dev/sdk/v3";
-
-configure({
- requestOptions: {
- retry: {
- maxAttempts: 5,
- minTimeoutInMs: 1000,
- maxTimeoutInMs: 5000,
- factor: 1.8,
- randomize: true,
- },
- },
-});
-```
-
-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:
-
-```ts
-import { runs } from "@trigger.dev/sdk/v3";
-
-async function main() {
- const run = await runs.retrieve("run_1234", {
- retry: {
- maxAttempts: 1, // Disable retries
- },
- });
-}
-```
-
-
- 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.
-
-
-## Auto-pagination
-
-All list endpoints in the management API support auto-pagination.
-You can use `for await … of` syntax to iterate through items across all pages:
-
-```ts
-import { runs } from "@trigger.dev/sdk/v3";
-
-async function fetchAllRuns() {
- const allRuns = [];
-
- for await (const run of runs.list({ limit: 10 })) {
- allRuns.push(run);
- }
-
- return allRuns;
-}
-```
-
-You can also use helpers on the return value from any `list` method to get the next/previous page of results:
-
-```ts
-import { runs } from "@trigger.dev/sdk/v3";
-
-async function main() {
- let page = await runs.list({ limit: 10 });
-
- for (const run of page.data) {
- console.log(run);
- }
-
- while (page.hasNextPage()) {
- page = await page.getNextPage();
- // ... do something with the next page
- }
-}
-```
-
-## Advanced usage
-
-### Accessing raw HTTP responses
-
-All API methods return a `Promise` subclass `ApiPromise` that includes helpers for accessing the underlying HTTP response:
-
-```ts
-import { runs } from "@trigger.dev/sdk/v3";
-
-async function main() {
- const { data: run, response: raw } = await runs.retrieve("run_1234").withResponse();
-
- console.log(raw.status);
- console.log(raw.headers);
-
- const response = await runs.retrieve("run_1234").asResponse(); // Returns a Response object
-
- console.log(response.status);
- console.log(response.headers);
-}
-```
+```
\ No newline at end of file