@cosmicdrift/kumiko-samples 0.411.0 → 0.412.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +1 -1
  3. package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts +64 -3
  4. package/packages/bundled-features/src/agent-tools/agent-manifest.ts +13 -130
  5. package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +60 -0
  6. package/packages/bundled-features/src/agent-tools/api-docs/check.ts +25 -0
  7. package/packages/bundled-features/src/agent-tools/api-docs/collect-events.ts +140 -0
  8. package/packages/bundled-features/src/agent-tools/api-docs/collect.ts +175 -0
  9. package/packages/bundled-features/src/agent-tools/api-docs/curl.ts +28 -0
  10. package/packages/bundled-features/src/agent-tools/api-docs/error-table.ts +45 -0
  11. package/packages/bundled-features/src/agent-tools/api-docs/examples.ts +43 -0
  12. package/packages/bundled-features/src/agent-tools/api-docs/generate.ts +179 -0
  13. package/packages/bundled-features/src/agent-tools/api-docs/index-json.ts +29 -0
  14. package/packages/bundled-features/src/agent-tools/api-docs/index.ts +21 -0
  15. package/packages/bundled-features/src/agent-tools/api-docs/list-parameters.ts +38 -0
  16. package/packages/bundled-features/src/agent-tools/api-docs/markdown.ts +70 -0
  17. package/packages/bundled-features/src/agent-tools/api-docs/menu-path.ts +82 -0
  18. package/packages/bundled-features/src/agent-tools/api-docs/model.ts +83 -0
  19. package/packages/bundled-features/src/agent-tools/api-docs/problems.ts +58 -0
  20. package/packages/bundled-features/src/agent-tools/api-docs/render-events.ts +76 -0
  21. package/packages/bundled-features/src/agent-tools/api-docs/render-openapi.ts +216 -0
  22. package/packages/bundled-features/src/agent-tools/api-docs/render-overview.ts +86 -0
  23. package/packages/bundled-features/src/agent-tools/api-docs/render-reference.ts +79 -0
  24. package/packages/bundled-features/src/agent-tools/api-docs/render-tokens.ts +136 -0
  25. package/packages/bundled-features/src/agent-tools/api-docs/schema-fields.ts +167 -0
  26. package/packages/bundled-features/src/agent-tools/api-docs/section-ids.ts +28 -0
  27. package/packages/bundled-features/src/agent-tools/api-docs/system-only.ts +11 -0
  28. package/packages/bundled-features/src/agent-tools/api-docs/texts/de.ts +166 -0
  29. package/packages/bundled-features/src/agent-tools/api-docs/texts/en.ts +159 -0
  30. package/packages/bundled-features/src/agent-tools/api-docs/texts/es.ts +162 -0
  31. package/packages/bundled-features/src/agent-tools/api-docs/texts/fr.ts +169 -0
  32. package/packages/bundled-features/src/agent-tools/api-docs/texts/index.ts +67 -0
  33. package/packages/bundled-features/src/agent-tools/api-docs/texts/it.ts +165 -0
  34. package/packages/bundled-features/src/agent-tools/api-docs/texts/types.ts +130 -0
  35. package/packages/bundled-features/src/agent-tools/api-docs/ui-writes.ts +81 -0
  36. package/packages/bundled-features/src/agent-tools/changes.json +24 -0
  37. package/packages/bundled-features/src/agent-tools/handler-schema.ts +45 -0
  38. package/packages/bundled-features/src/agent-tools/index.ts +24 -0
  39. package/packages/bundled-features/src/agent-tools/labels.ts +181 -0
  40. package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
  41. package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
  42. package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
  43. package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
  44. package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
  45. package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
  46. package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
  47. package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
  48. package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +28 -0
  49. package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
  50. package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
  51. package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
  52. package/samples/recipes/api-docs/README.md +52 -0
  53. package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
  54. package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
  55. package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
  56. package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
  57. package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
  58. package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
  59. package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
  60. package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
  61. package/samples/recipes/api-docs/api-docs/index.json +371 -0
  62. package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
  63. package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
  64. package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
  65. package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
  66. package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
  67. package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
  68. package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
  69. package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
  70. package/samples/recipes/api-docs/kumiko.config.ts +33 -0
  71. package/samples/recipes/api-docs/package.json +14 -0
  72. package/samples/recipes/api-docs/src/feature.ts +218 -0
  73. package/samples/recipes/api-docs/tsconfig.json +22 -0
@@ -0,0 +1,100 @@
1
+ ---
2
+ title: "HTTP API"
3
+ description: "Endpoints, request body, responses, error codes, lists and batches of the HTTP API."
4
+ ---
5
+
6
+ Every call is a POST with a JSON body. The `type` field names the handler, `payload` carries its fields. The reference pages list every handler with its fields.
7
+
8
+ ## Endpoints
9
+
10
+ | Endpoint | |
11
+ | --- | --- |
12
+ | `POST /api/query` | Reads data. Never changes anything. |
13
+ | `POST /api/write` | Changes data: create, update, delete or a specific action. |
14
+ | `POST /api/batch` | Runs several write calls in one transaction. |
15
+
16
+ ## Authentication
17
+
18
+ Send an API token in the `Authorization` header as `Bearer <token>`. Requests with a token need no cookie and no CSRF token. The token also fixes the account the request runs in, so you never send an account or tenant ID.
19
+
20
+ ## Request body
21
+
22
+ `type` is the handler name, for example `helpdesk:query:ticket:detail`. `payload` holds the fields from the reference. `requestId` is optional, see below. The payload may be nested at most 20 levels deep.
23
+
24
+ ```bash
25
+ curl -X POST https://helpdesk.example.com/api/query \
26
+ -H "Authorization: Bearer $API_TOKEN" \
27
+ -H "Content-Type: application/json" \
28
+ -d '{
29
+ "type": "helpdesk:query:ticket:detail",
30
+ "payload": {
31
+ "id": "00000000-0000-4000-8000-000000000001"
32
+ }
33
+ }'
34
+ ```
35
+
36
+ ## Responses
37
+
38
+ A successful read returns `data`. A successful write returns `isSuccess: true` and `data`.
39
+
40
+ On failure the HTTP status is 4xx or 5xx and the body contains `error`. Write calls also return `isSuccess: false`. Branch on `error.code` and the status. `message` is meant for people and may change.
41
+
42
+ ## Error codes
43
+
44
+ | Code | HTTP status | Meaning |
45
+ | --- | --- | --- |
46
+ | `ambiguous_auth` | 400 | The request carried both a session cookie and a token. Send only one. |
47
+ | `validation_error` | 400 | The payload does not match the handler's fields. `details` names the fields. |
48
+ | `invalid_token` | 401 | The token is unknown, revoked or expired. |
49
+ | `missing_token` | 401 | The `Authorization` header is missing. |
50
+ | `unauthenticated` | 401 | No valid credentials were sent. |
51
+ | `access_denied` | 403 | The token lacks the scope for this handler, or the endpoint does not accept tokens. |
52
+ | `feature_disabled` | 403 | This function is switched off or not part of your plan. |
53
+ | `not_found` | 404 | The record does not exist or you cannot see it. |
54
+ | `conflict` | 409 | The change conflicts with the current state of the data. |
55
+ | `idempotent_replay` | 409 | This change was already applied under the same idempotency key. The first attempt succeeded, so do not send it again. |
56
+ | `precondition_failed` | 409 | A field of the record no longer has the value the change expected. Read the record again and retry. |
57
+ | `record_locked` | 409 | Another change holds a lock on the record. Retry shortly. |
58
+ | `unique_violation` | 409 | A record with this value already exists. |
59
+ | `version_conflict` | 409 | The record changed after you read it. Read it again and retry with the new `version`. |
60
+ | `unconfigured` | 422 | A setting this function needs is still empty. Set it up in the app first, then retry. |
61
+ | `unprocessable` | 422 | The data is valid, but a business rule rejects the change. `details.reason` names the rule. |
62
+ | `pat_rate_limited` | 429 | This token sent too many requests in a short time. Wait a moment and retry. |
63
+ | `rate_limited` | 429 | Too many requests. Wait as many seconds as the `Retry-After` header says. |
64
+ | `internal_error` | 500 | Unexpected server error. Retry later. |
65
+ | `rate_limit_unavailable` | 503 | The rate limiter is temporarily unavailable, so the request was refused. Retry shortly. |
66
+ | `member_read_timeout` | 504 | A read on the server took too long and was stopped. Retry later. |
67
+
68
+ ## Versions and conflicts
69
+
70
+ Every record has a `version`. An update takes the `version` you read last. If someone changed the record in between, the call fails with 409 `version_conflict`. Read the record again, check the change and send it with the new version.
71
+
72
+ ## Lists
73
+
74
+ List handlers end in `:list` and accept these fields:
75
+
76
+ | Field | Type | Description |
77
+ | --- | --- | --- |
78
+ | `cursor` | string | Position from `nextCursor` of the previous page. |
79
+ | `limit` | integer | Rows per page, 50 by default, at most 200. |
80
+ | `search` | string | Full-text search across the searchable fields. |
81
+ | `sort` | string | Field to sort by. |
82
+ | `sortDirection` | "asc" \| "desc" | `asc` or `desc`. |
83
+ | `offset` | integer | Number of rows to skip. Prefer `cursor` for paging. |
84
+ | `totalCount` | boolean | Set `true` to also get `total`, the number of matching rows. |
85
+ | `includeDeleted` | boolean | Set `true` to include deleted rows. Only for entities with soft delete. |
86
+ | `onlyDeleted` | boolean | Set `true` to return only deleted rows. Only for entities with soft delete, not together with `includeDeleted`. |
87
+ | `filter` | object | One field filter with `field`, `op` and `value`. `op` is one of `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
88
+ | `filters` | array of object | Several field filters, each with `field`, `op` and `value`. `op` is one of `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
89
+ | `namedFilter` | string | Name of a predefined filter of the entity, for example a work queue. |
90
+ | `aggregate` | object | Returns aggregated values instead of rows. |
91
+
92
+ The response contains `rows` and `nextCursor`. For the next page send `nextCursor` as `cursor`. On the last page `nextCursor` is `null`.
93
+
94
+ ## Batches
95
+
96
+ `POST /api/batch` takes `commands`, a list of `{ type, payload }` write calls. They run in one transaction: if one fails, none takes effect. The response then has `isSuccess: false`, the `error` and `failedIndex`, the position of the failed command counted from 0.
97
+
98
+ ## Safe retries
99
+
100
+ Send a `requestId` with write and batch calls, any string that is unique per change. If the connection drops and you send the same call again with the same `requestId`, you get the first result back and the change does not run twice.
@@ -0,0 +1,305 @@
1
+ ---
2
+ title: "Tickets"
3
+ description: "API reference for Tickets: every handler with its fields and an example."
4
+ ---
5
+
6
+ ### ticket: detail
7
+
8
+ **Show ticket**
9
+
10
+ Returns one ticket.
11
+
12
+ - Required scope: `tickets:read`
13
+ - Endpoint: `POST /api/query`
14
+
15
+ | Field | Type | Required | Description |
16
+ | --- | --- | --- | --- |
17
+ | `id` | string (uuid) | yes | Ticket ID |
18
+
19
+ **Example request**
20
+
21
+ ```bash
22
+ curl -X POST https://helpdesk.example.com/api/query \
23
+ -H "Authorization: Bearer $API_TOKEN" \
24
+ -H "Content-Type: application/json" \
25
+ -d '{
26
+ "type": "helpdesk:query:ticket:detail",
27
+ "payload": {
28
+ "id": "00000000-0000-4000-8000-000000000001"
29
+ }
30
+ }'
31
+ ```
32
+
33
+ **Example response**
34
+
35
+ Status: 200
36
+
37
+ ```json
38
+ {
39
+ "data": {
40
+ "id": "00000000-0000-4000-8000-000000000001",
41
+ "tenantId": "00000000-0000-4000-8000-000000000002",
42
+ "version": 1,
43
+ "insertedAt": "2026-01-15T09:30:00.000Z",
44
+ "modifiedAt": null,
45
+ "insertedById": "00000000-0000-4000-8000-000000000003",
46
+ "modifiedById": null,
47
+ "title": "Printer is on fire",
48
+ "status": "open",
49
+ "priority": "high"
50
+ }
51
+ }
52
+ ```
53
+
54
+ ### ticket: list
55
+
56
+ **List tickets**
57
+
58
+ Lists tickets, newest first.
59
+
60
+ - Required scope: `tickets:read`
61
+ - Endpoint: `POST /api/query`
62
+
63
+ | Field | Type | Required | Description |
64
+ | --- | --- | --- | --- |
65
+ | `cursor` | string | no | Position from `nextCursor` of the previous page. |
66
+ | `limit` | integer | no | Rows per page, 50 by default, at most 200. |
67
+ | `search` | string | no | Full-text search across the searchable fields. |
68
+ | `sort` | string | no | Field to sort by. |
69
+ | `sortDirection` | "asc" \| "desc" | no | `asc` or `desc`. |
70
+ | `offset` | integer | no | Number of rows to skip. Prefer `cursor` for paging. |
71
+ | `totalCount` | boolean | no | Set `true` to also get `total`, the number of matching rows. |
72
+ | `includeDeleted` | boolean | no | Set `true` to include deleted rows. Only for entities with soft delete. |
73
+ | `onlyDeleted` | boolean | no | Set `true` to return only deleted rows. Only for entities with soft delete, not together with `includeDeleted`. |
74
+ | `filter` | object | no | One field filter with `field`, `op` and `value`. `op` is one of `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
75
+ | `filter.field` | string | yes | |
76
+ | `filter.op` | "eq" \| "ne" \| "lt" \| "gt" \| "lte" \| "gte" \| "in" | yes | |
77
+ | `filter.value` | any | yes | |
78
+ | `filters` | array of object | no | Several field filters, each with `field`, `op` and `value`. `op` is one of `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
79
+ | `namedFilter` | string | no | Name of a predefined filter of the entity, for example a work queue. |
80
+ | `aggregate` | object | no | Returns aggregated values instead of rows. |
81
+ | `aggregate.groupBy` | string | no | |
82
+ | `aggregate.measures` | array of object | no | |
83
+
84
+ **Example request**
85
+
86
+ ```bash
87
+ curl -X POST https://helpdesk.example.com/api/query \
88
+ -H "Authorization: Bearer $API_TOKEN" \
89
+ -H "Content-Type: application/json" \
90
+ -d '{
91
+ "type": "helpdesk:query:ticket:list",
92
+ "payload": {}
93
+ }'
94
+ ```
95
+
96
+ **Example response**
97
+
98
+ Status: 200
99
+
100
+ ```json
101
+ {
102
+ "data": {
103
+ "rows": [
104
+ {
105
+ "id": "00000000-0000-4000-8000-000000000001",
106
+ "tenantId": "00000000-0000-4000-8000-000000000002",
107
+ "version": 1,
108
+ "insertedAt": "2026-01-15T09:30:00.000Z",
109
+ "modifiedAt": null,
110
+ "insertedById": "00000000-0000-4000-8000-000000000003",
111
+ "modifiedById": null,
112
+ "title": "Printer is on fire",
113
+ "status": "open",
114
+ "priority": "high"
115
+ }
116
+ ],
117
+ "nextCursor": null
118
+ }
119
+ }
120
+ ```
121
+
122
+ ### ticket: close
123
+
124
+ **Close ticket**
125
+
126
+ Closes a ticket and records how it was resolved.
127
+
128
+ - Required scope: `tickets:write`
129
+ - Endpoint: `POST /api/write`
130
+
131
+ | Field | Type | Required | Description |
132
+ | --- | --- | --- | --- |
133
+ | `id` | string (uuid) | yes | Ticket |
134
+ | `resolution` | string | yes | Resolution |
135
+
136
+ **Example request**
137
+
138
+ ```bash
139
+ curl -X POST https://helpdesk.example.com/api/write \
140
+ -H "Authorization: Bearer $API_TOKEN" \
141
+ -H "Content-Type: application/json" \
142
+ -d '{
143
+ "type": "helpdesk:write:ticket:close",
144
+ "payload": {
145
+ "id": "00000000-0000-4000-8000-000000000001",
146
+ "resolution": "Replaced the cartridge"
147
+ }
148
+ }'
149
+ ```
150
+
151
+ **Example response**
152
+
153
+ Status: 200
154
+
155
+ ```json
156
+ {
157
+ "isSuccess": true,
158
+ "data": {
159
+ "id": "00000000-0000-4000-8000-000000000001"
160
+ }
161
+ }
162
+ ```
163
+
164
+ ### ticket: create
165
+
166
+ **Create ticket**
167
+
168
+ Opens a new ticket.
169
+
170
+ - Required scope: `tickets:write`
171
+ - Endpoint: `POST /api/write`
172
+
173
+ | Field | Type | Required | Description |
174
+ | --- | --- | --- | --- |
175
+ | `title` | string | yes | Title |
176
+ | `status` | "open" \| "closed" | no | Status |
177
+ | `priority` | "low" \| "normal" \| "high" | no | Priority |
178
+
179
+ **Example request**
180
+
181
+ ```bash
182
+ curl -X POST https://helpdesk.example.com/api/write \
183
+ -H "Authorization: Bearer $API_TOKEN" \
184
+ -H "Content-Type: application/json" \
185
+ -d '{
186
+ "type": "helpdesk:write:ticket:create",
187
+ "payload": {
188
+ "title": "Printer is on fire",
189
+ "priority": "high"
190
+ }
191
+ }'
192
+ ```
193
+
194
+ **Example response**
195
+
196
+ Status: 200
197
+
198
+ ```json
199
+ {
200
+ "isSuccess": true,
201
+ "data": {
202
+ "kind": "save",
203
+ "id": "00000000-0000-4000-8000-000000000001",
204
+ "data": {
205
+ "id": "00000000-0000-4000-8000-000000000001",
206
+ "tenantId": "00000000-0000-4000-8000-000000000002",
207
+ "version": 1,
208
+ "insertedAt": "2026-01-15T09:30:00.000Z",
209
+ "modifiedAt": null,
210
+ "insertedById": "00000000-0000-4000-8000-000000000003",
211
+ "modifiedById": null,
212
+ "title": "Printer is on fire",
213
+ "status": "open",
214
+ "priority": "high"
215
+ },
216
+ "changes": {
217
+ "title": "Printer is on fire",
218
+ "status": "open",
219
+ "priority": "high"
220
+ },
221
+ "previous": {},
222
+ "isNew": true,
223
+ "entityName": "ticket"
224
+ }
225
+ }
226
+ ```
227
+
228
+ ### ticket: update
229
+
230
+ **Update ticket**
231
+
232
+ Changes the title or the priority of a ticket.
233
+
234
+ - Required scope: `tickets:write`
235
+ - Endpoint: `POST /api/write`
236
+
237
+ | Field | Type | Required | Description |
238
+ | --- | --- | --- | --- |
239
+ | `id` | string (uuid) | yes | Ticket ID |
240
+ | `version` | number | yes | |
241
+ | `changes` | object | yes | |
242
+ | `changes.title` | string | no | Title |
243
+ | `changes.status` | "open" \| "closed" | no | Status |
244
+ | `changes.priority` | "low" \| "normal" \| "high" | no | Priority |
245
+
246
+ **Example request**
247
+
248
+ ```bash
249
+ curl -X POST https://helpdesk.example.com/api/write \
250
+ -H "Authorization: Bearer $API_TOKEN" \
251
+ -H "Content-Type: application/json" \
252
+ -d '{
253
+ "type": "helpdesk:write:ticket:update",
254
+ "payload": {
255
+ "id": "00000000-0000-4000-8000-000000000001",
256
+ "version": 1,
257
+ "changes": {
258
+ "priority": "normal"
259
+ }
260
+ }
261
+ }'
262
+ ```
263
+
264
+ **Example response**
265
+
266
+ Status: 200
267
+
268
+ ```json
269
+ {
270
+ "isSuccess": true,
271
+ "data": {
272
+ "kind": "save",
273
+ "id": "00000000-0000-4000-8000-000000000001",
274
+ "data": {
275
+ "id": "00000000-0000-4000-8000-000000000001",
276
+ "tenantId": "00000000-0000-4000-8000-000000000002",
277
+ "version": 2,
278
+ "insertedAt": "2026-01-15T09:30:00.000Z",
279
+ "modifiedAt": "2026-01-15T09:30:00.000Z",
280
+ "insertedById": "00000000-0000-4000-8000-000000000003",
281
+ "modifiedById": "00000000-0000-4000-8000-000000000003",
282
+ "title": "Printer is on fire",
283
+ "status": "open",
284
+ "priority": "normal"
285
+ },
286
+ "changes": {
287
+ "priority": "normal"
288
+ },
289
+ "previous": {
290
+ "id": "00000000-0000-4000-8000-000000000001",
291
+ "tenantId": "00000000-0000-4000-8000-000000000002",
292
+ "version": 1,
293
+ "insertedAt": "2026-01-15T09:30:00.000Z",
294
+ "modifiedAt": null,
295
+ "insertedById": "00000000-0000-4000-8000-000000000003",
296
+ "modifiedById": null,
297
+ "title": "Printer is on fire",
298
+ "status": "open",
299
+ "priority": "high"
300
+ },
301
+ "isNew": false,
302
+ "entityName": "ticket"
303
+ }
304
+ }
305
+ ```
@@ -0,0 +1,66 @@
1
+ ---
2
+ title: "API tokens"
3
+ description: "Create an API token for Helpdesk, choose its scopes and send it with your requests."
4
+ ---
5
+
6
+ An API token lets a script or another service call the Helpdesk API in your name. Its scopes decide which data it may read or change.
7
+
8
+ ## Create a token
9
+
10
+ 1. Open Settings › API tokens.
11
+ 2. Choose **Create a new token**.
12
+ 3. Enter a name, pick the scopes and the expiry, and confirm with your password.
13
+ 4. Copy the token. It starts with `kpat_` and is shown only once.
14
+
15
+ A token expires after 90 days unless you pick another expiry. The longest possible expiry is 3650 days.
16
+
17
+ ## Use the token
18
+
19
+ Send the token in the `Authorization` header. Requests with a token need no cookie and no CSRF token.
20
+
21
+ ```bash
22
+ curl -X POST https://helpdesk.example.com/api/query \
23
+ -H "Authorization: Bearer $API_TOKEN" \
24
+ -H "Content-Type: application/json" \
25
+ -d '{
26
+ "type": "helpdesk:query:ticket:detail",
27
+ "payload": {
28
+ "id": "00000000-0000-4000-8000-000000000001"
29
+ }
30
+ }'
31
+ ```
32
+
33
+ ## Scopes
34
+
35
+ Each scope comes in two levels. `read` allows the read handlers. `write` allows everything `read` allows plus the write handlers.
36
+
37
+ | Scope | Grant | Handlers |
38
+ | --- | --- | --- |
39
+ | `tickets` (Tickets) | `tickets:read` | `helpdesk:query:ticket:detail`, `helpdesk:query:ticket:list` |
40
+ | `tickets` (Tickets) | `tickets:write` | `helpdesk:write:ticket:close`, `helpdesk:write:ticket:create`, `helpdesk:write:ticket:update` |
41
+
42
+ ## Rate limit
43
+
44
+ Each token may send 60 requests per 60 seconds. Above that the API answers 429 `pat_rate_limited`.
45
+
46
+ API tokens are included in every Helpdesk plan.
47
+
48
+ ## Errors
49
+
50
+ | HTTP status | Code | Cause |
51
+ | --- | --- | --- |
52
+ | 401 | `missing_token` | No `Authorization` header. |
53
+ | 401 | `invalid_token` | The token is unknown, revoked or expired. |
54
+ | 403 | `access_denied` | The token lacks the scope for this handler. |
55
+ | 403 | `access_denied` | The endpoint does not accept tokens. Tokens work only on the API endpoints. |
56
+ | 429 | `pat_rate_limited` | Too many requests from this token. |
57
+
58
+ ## Revoke a token
59
+
60
+ Revoke a token in Settings › API tokens as soon as you stop using it. Changing your password revokes all your tokens. A token always acts with your current roles. If you leave the account or your user is deleted, it stops working.
61
+
62
+ ## Security
63
+
64
+ - Treat a token like a password. Keep it in a secret store, never in code, a repository, an app or web page, or a log.
65
+ - Give each script its own token with only the scopes it needs.
66
+ - Revoke tokens you no longer use. Revoke a token at once if it may have leaked.