Skip to content

Commit 99f2caf

Browse files
samejrsamejr
authored
Docs/new reference section (#1719)
* Moves API reference to a new dropdown section * Move toubleshooting higher up * Separates the reference Overview page into new pages * Removed Projects api and redirects old page to overview * typo
1 parent e19bf2a commit 99f2caf

File tree

6 files changed

+305
-280
lines changed

6 files changed

+305
-280
lines changed

‎docs/docs.json

Lines changed: 72 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -101,55 +101,7 @@
101101
"realtime/subscribe-to-batch"
102102
]
103103
},
104-
{
105-
"group": "API reference",
106-
"pages": [
107-
"management/overview",
108-
{
109-
"group": "Tasks API",
110-
"pages": ["management/tasks/trigger", "management/tasks/batch-trigger"]
111-
},
112-
{
113-
"group": "Runs API",
114-
"pages": [
115-
"management/runs/list",
116-
"management/runs/retrieve",
117-
"management/runs/replay",
118-
"management/runs/cancel",
119-
"management/runs/reschedule",
120-
"management/runs/update-metadata"
121-
]
122-
},
123-
{
124-
"group": "Schedules API",
125-
"pages": [
126-
"management/schedules/list",
127-
"management/schedules/create",
128-
"management/schedules/retrieve",
129-
"management/schedules/update",
130-
"management/schedules/delete",
131-
"management/schedules/deactivate",
132-
"management/schedules/activate",
133-
"management/schedules/timezones"
134-
]
135-
},
136-
{
137-
"group": "Env Vars API",
138-
"pages": [
139-
"management/envvars/list",
140-
"management/envvars/import",
141-
"management/envvars/create",
142-
"management/envvars/retrieve",
143-
"management/envvars/update",
144-
"management/envvars/delete"
145-
]
146-
},
147-
{
148-
"group": "Projects API",
149-
"pages": ["management/projects/runs"]
150-
}
151-
]
152-
},
104+
153105
{
154106
"group": "CLI",
155107
"pages": [
@@ -169,16 +121,6 @@
169121
}
170122
]
171123
},
172-
{
173-
"group": "Open source",
174-
"pages": [
175-
"open-source-self-hosting",
176-
"open-source-contributing",
177-
"github-repo",
178-
"changelog",
179-
"roadmap"
180-
]
181-
},
182124
{
183125
"group": "Troubleshooting",
184126
"pages": [
@@ -192,17 +134,82 @@
192134
"request-feature"
193135
]
194136
},
137+
{
138+
"group": "Open source",
139+
"pages": [
140+
"open-source-self-hosting",
141+
"open-source-contributing",
142+
"github-repo",
143+
"changelog",
144+
"roadmap"
145+
]
146+
},
195147
{
196148
"group": "Help",
197149
"pages": ["community", "help-slack", "help-email"]
198150
}
199151
]
200152
},
153+
{
154+
"dropdown": "API reference",
155+
"description": "The Trigger.dev API",
156+
"icon": "code",
157+
"groups": [
158+
{
159+
"group": "API reference",
160+
"pages": [
161+
"management/overview",
162+
"management/authentication",
163+
"management/errors-and-retries",
164+
"management/auto-pagination",
165+
"management/advanced-usage"
166+
]
167+
},
168+
{
169+
"group": "Tasks API",
170+
"pages": ["management/tasks/trigger", "management/tasks/batch-trigger"]
171+
},
172+
{
173+
"group": "Runs API",
174+
"pages": [
175+
"management/runs/list",
176+
"management/runs/retrieve",
177+
"management/runs/replay",
178+
"management/runs/cancel",
179+
"management/runs/reschedule",
180+
"management/runs/update-metadata"
181+
]
182+
},
183+
{
184+
"group": "Schedules API",
185+
"pages": [
186+
"management/schedules/list",
187+
"management/schedules/create",
188+
"management/schedules/retrieve",
189+
"management/schedules/update",
190+
"management/schedules/delete",
191+
"management/schedules/deactivate",
192+
"management/schedules/activate",
193+
"management/schedules/timezones"
194+
]
195+
},
196+
{
197+
"group": "Env Vars API",
198+
"pages": [
199+
"management/envvars/list",
200+
"management/envvars/import",
201+
"management/envvars/create",
202+
"management/envvars/retrieve",
203+
"management/envvars/update",
204+
"management/envvars/delete"
205+
]
206+
}
207+
]
208+
},
201209
{
202210
"dropdown": "Guides & examples",
203211
"description": "A great way to get started",
204-
"icon": "book",
205-
212+
"icon": "books",
206213
"groups": [
207214
{
208215
"group": "Introduction",
@@ -487,6 +494,10 @@
487494
{
488495
"source": "/frontend/react-hooks",
489496
"destination": "/frontend/react-hooks/overview"
497+
},
498+
{
499+
"source": "/management/projects/runs",
500+
"destination": "/management/overview"
490501
}
491502
]
492503
}

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

0 commit comments

Comments
 (0)