Docs/new reference section

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"
     }
   ]
 }

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);
+}
+```

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.
+
+<Note>
+  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.
+</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`:
+
+```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",
+  });
+}
+```
+
+<Accordion title="View endpoint support">
+  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`        | ✅         |                       |
+
+</Accordion>
+
+### 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,
+});
+```

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
+  }
+}
+```