@productcraft/flags 0.0.0 → 0.2.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.
- package/LICENSE +21 -0
- package/README.md +395 -1
- package/api.md +1532 -0
- package/dist/browser/chunk-DIPMYL6H.cjs +598 -0
- package/dist/browser/chunk-DIPMYL6H.cjs.map +1 -0
- package/dist/browser/chunk-OI4KARX6.js +593 -0
- package/dist/browser/chunk-OI4KARX6.js.map +1 -0
- package/dist/browser/chunk-UFZYZXX5.js +1584 -0
- package/dist/browser/chunk-UFZYZXX5.js.map +1 -0
- package/dist/browser/chunk-YAW7UFU3.cjs +1584 -0
- package/dist/browser/chunk-YAW7UFU3.cjs.map +1 -0
- package/dist/browser/index.cjs +105 -0
- package/dist/browser/index.cjs.map +1 -0
- package/dist/browser/index.js +9 -0
- package/dist/browser/index.js.map +1 -0
- package/dist/browser/management.cjs +12 -0
- package/dist/browser/management.cjs.map +1 -0
- package/dist/browser/management.js +3 -0
- package/dist/browser/management.js.map +1 -0
- package/dist/browser/testing.cjs +1315 -0
- package/dist/browser/testing.cjs.map +1 -0
- package/dist/browser/testing.js +1307 -0
- package/dist/browser/testing.js.map +1 -0
- package/dist/chunk-ERCRURB5.js +1584 -0
- package/dist/chunk-ERCRURB5.js.map +1 -0
- package/dist/chunk-ERZAYN5A.js +626 -0
- package/dist/chunk-ERZAYN5A.js.map +1 -0
- package/dist/chunk-HOIKWDWQ.cjs +1584 -0
- package/dist/chunk-HOIKWDWQ.cjs.map +1 -0
- package/dist/chunk-J62ZCSIV.cjs +631 -0
- package/dist/chunk-J62ZCSIV.cjs.map +1 -0
- package/dist/client-DQaz2Leb.d.cts +175 -0
- package/dist/client-DQaz2Leb.d.ts +175 -0
- package/dist/client-bVEJfS6_.d.cts +11007 -0
- package/dist/client-bVEJfS6_.d.ts +11007 -0
- package/dist/index.cjs +105 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +5 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +9 -0
- package/dist/index.js.map +1 -0
- package/dist/management.cjs +12 -0
- package/dist/management.cjs.map +1 -0
- package/dist/management.d.cts +3 -0
- package/dist/management.d.ts +3 -0
- package/dist/management.js +3 -0
- package/dist/management.js.map +1 -0
- package/dist/testing.cjs +1315 -0
- package/dist/testing.cjs.map +1 -0
- package/dist/testing.d.cts +71 -0
- package/dist/testing.d.ts +71 -0
- package/dist/testing.js +1307 -0
- package/dist/testing.js.map +1 -0
- package/manifest.json +875 -0
- package/package.json +121 -5
package/api.md
ADDED
|
@@ -0,0 +1,1532 @@
|
|
|
1
|
+
# @productcraft/flags API reference
|
|
2
|
+
|
|
3
|
+
<!-- Generated by scripts/gen-sdk.mjs from Specs/flags.json. Do not edit. -->
|
|
4
|
+
<!-- snippet-preamble: import { Flags } from "@productcraft/flags"; const flags = new Flags(); -->
|
|
5
|
+
|
|
6
|
+
Every method of `Flags`, grouped by resource. Types are under the `Flags` namespace (`import type { Flags } from "@productcraft/flags"`). Every method takes per-request options last (`{ idempotencyKey, timeout, maxRetries, headers, signal, workspaceId }`).
|
|
7
|
+
|
|
8
|
+
## changes
|
|
9
|
+
|
|
10
|
+
### `flags.changes.retrieve(changeId, options?)`
|
|
11
|
+
|
|
12
|
+
`GET /v1/workspaces/{workspace_id}/changes/{change_id}` → `Flags.ChangeDetail`
|
|
13
|
+
|
|
14
|
+
Get a change.
|
|
15
|
+
|
|
16
|
+
One change with `before`, `after`, a JSON Patch `diff` (RFC 6902) and the summary. When `before` and `after` together exceed 64 KB, `diff_too_large` is true and the bodies are left out: compare the revisions in `revisions` (`url`, `previous_url`) instead.
|
|
17
|
+
|
|
18
|
+
| Status | Error class | Codes | When |
|
|
19
|
+
|---|---|---|---|
|
|
20
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
21
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CHANGE_NOT_FOUND` | `CHANGE_NOT_FOUND`: no such change in this workspace (or it was pruned). |
|
|
22
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
const changeDetail = await flags.changes.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-changes-change-id)
|
|
29
|
+
|
|
30
|
+
### `flags.changes.revert(changeId, params?, options?)`
|
|
31
|
+
|
|
32
|
+
`POST /v1/workspaces/{workspace_id}/changes/{change_id}/revert` → `Flags.ChangeDetail`
|
|
33
|
+
|
|
34
|
+
Restore a version.
|
|
35
|
+
|
|
36
|
+
Writes the change's `before` back as a new change (`reverts_change_id` points to this one), through the same checks as an edit: validation, the protected-environment and note rules, and publishing. Supported for `setting_value.updated`, `segment.updated` and `setting.updated`. Send the entity's current `version` (the value or segment); a setting is restored only while it is still as this change left it. Needs `flags.value.update` plus what the original edit needed (`flags.value.update` on the environment and setting, or `flags.update`; `flags.protected.update` in protected environments).
|
|
37
|
+
|
|
38
|
+
- Params: `Flags.ChangeRevertParams`
|
|
39
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
40
|
+
|
|
41
|
+
| Status | Error class | Codes | When |
|
|
42
|
+
|---|---|---|---|
|
|
43
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `version` is missing (value and segment restores) or invalid. |
|
|
44
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). A restore needs the actions of the original edit too. |
|
|
45
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CHANGE_NOT_FOUND`, `SETTING_NOT_FOUND`, `SEGMENT_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CHANGE_NOT_FOUND`; `SETTING_NOT_FOUND`, `SEGMENT_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND` when the entity was deleted since. |
|
|
46
|
+
| 409 | `ConflictError` | `CONFLICT`, `VERSION_CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `VERSION_CONFLICT`: the entity changed since you read it (`details.current_version`), or the setting no longer matches this change. `KEY_ALREADY_EXISTS`: the restored key is taken. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
47
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `REVERT_NOT_SUPPORTED`, `NOTHING_TO_RESTORE`, `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND`, `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE`, `OWNER_NOT_A_MEMBER` | `REVERT_NOT_SUPPORTED`: this kind of change cannot be restored. `NOTHING_TO_RESTORE`: it already matches the version before this change. The restored or copied targeting is refused by the normal write checks: `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND` (a segment it used was deleted), `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED` (the environment requires a `note`), `CONFIG_TOO_LARGE`, or `OWNER_NOT_A_MEMBER` (a restored owner left the workspace). |
|
|
48
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
const changeDetail = await flags.changes.revert("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { note: "Roll back FLAG-142" });
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-changes-change-id-revert)
|
|
55
|
+
|
|
56
|
+
## configs
|
|
57
|
+
|
|
58
|
+
### `flags.configs.compare(configId, params, options?)`
|
|
59
|
+
|
|
60
|
+
`GET /v1/workspaces/{workspace_id}/configs/{config_id}/compare` → `PagePromise<Flags.CompareRow>`
|
|
61
|
+
|
|
62
|
+
Compare environments.
|
|
63
|
+
|
|
64
|
+
Each setting's value and targeting side by side in 2-5 environments, with `differs` per setting.
|
|
65
|
+
|
|
66
|
+
- Params: `Flags.ConfigCompareParams`
|
|
67
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
68
|
+
|
|
69
|
+
| Status | Error class | Codes | When |
|
|
70
|
+
|---|---|---|---|
|
|
71
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `environment_ids` is not 2-5 environment ids. |
|
|
72
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
73
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
|
|
74
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
for await (const config of flags.configs.compare("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
78
|
+
environment_ids: "0b8c7a52-5a8e-4b8f-9d0a-6b1f0e0c1a11,7c1d9e44-2f3a-4c55-8e6b-1a2b3c4d5e6f",
|
|
79
|
+
})) {
|
|
80
|
+
console.log(config);
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-configs-config-id-compare)
|
|
85
|
+
|
|
86
|
+
### `flags.configs.delete(configId, params?, options?)`
|
|
87
|
+
|
|
88
|
+
`DELETE /v1/workspaces/{workspace_id}/configs/{config_id}` → `void`
|
|
89
|
+
|
|
90
|
+
Delete a config.
|
|
91
|
+
|
|
92
|
+
Deletes the config with its flags, values and SDK keys in every environment. Needs `flags.project.manage`.
|
|
93
|
+
|
|
94
|
+
- Params: `Flags.ConfigDeleteParams`
|
|
95
|
+
|
|
96
|
+
| Status | Error class | Codes | When |
|
|
97
|
+
|---|---|---|---|
|
|
98
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
99
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
|
|
100
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
await flags.configs.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#delete-v1-workspaces-workspace-id-configs-config-id)
|
|
107
|
+
|
|
108
|
+
### `flags.configs.retrieve(configId, options?)`
|
|
109
|
+
|
|
110
|
+
`GET /v1/workspaces/{workspace_id}/configs/{config_id}` → `Flags.Config`
|
|
111
|
+
|
|
112
|
+
Get a config.
|
|
113
|
+
|
|
114
|
+
| Status | Error class | Codes | When |
|
|
115
|
+
|---|---|---|---|
|
|
116
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
117
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
|
|
118
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
const config = await flags.configs.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-configs-config-id)
|
|
125
|
+
|
|
126
|
+
### `flags.configs.update(configId, params?, options?)`
|
|
127
|
+
|
|
128
|
+
`PATCH /v1/workspaces/{workspace_id}/configs/{config_id}` → `Flags.Config`
|
|
129
|
+
|
|
130
|
+
Update a config.
|
|
131
|
+
|
|
132
|
+
Key, name, description or order. Only the fields you send change. Needs `flags.project.manage`.
|
|
133
|
+
|
|
134
|
+
- Params: `Flags.ConfigUpdateParams`
|
|
135
|
+
|
|
136
|
+
| Status | Error class | Codes | When |
|
|
137
|
+
|---|---|---|---|
|
|
138
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
|
|
139
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
140
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
|
|
141
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS` | `KEY_ALREADY_EXISTS`: the project already has a config with this key. |
|
|
142
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
const config = await flags.configs.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { description: "string" });
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-configs-config-id)
|
|
149
|
+
|
|
150
|
+
## configs.environments
|
|
151
|
+
|
|
152
|
+
### `flags.configs.environments.copy(configId, environmentId, params, options?)`
|
|
153
|
+
|
|
154
|
+
`POST /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/copy` → `Flags.CopyEnvironment`
|
|
155
|
+
|
|
156
|
+
Copy targeting between environments.
|
|
157
|
+
|
|
158
|
+
Copies value and targeting (rules, splits, split attribute) of `setting_ids`, or of every setting that differs (`all_differing: true`), from `source_environment_id` into this environment. All or nothing: send the target `version` of every setting that will be copied in `versions`; if any moved, nothing is written and 409 lists them. Publishes one config revision, with one history entry per setting. Needs `flags.value.update` on this environment and each setting, plus `flags.protected.update` when it is protected.
|
|
159
|
+
|
|
160
|
+
- Params: `Flags.ConfigEnvironmentCopyParams`
|
|
161
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
162
|
+
|
|
163
|
+
| Status | Error class | Codes | When |
|
|
164
|
+
|---|---|---|---|
|
|
165
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: neither or both of `setting_ids` / `all_differing`, the source is the target, or a bad `versions` entry. |
|
|
166
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). Copies need `flags.value.update` on the environment and every setting, and `flags.protected.update` into a protected environment. |
|
|
167
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND`, `SETTING_NOT_FOUND` | `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` (target or source is not of this project) or `SETTING_NOT_FOUND`. |
|
|
168
|
+
| 409 | `ConflictError` | `CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `VERSION_CONFLICT`: a setting changed in the target since you read it, or has no entry in `versions` (`details.conflicts[]`: `setting_id`, `key`, `current_version`, `sent_version`); nothing was copied. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
169
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND`, `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE`, `OWNER_NOT_A_MEMBER` | The restored or copied targeting is refused by the normal write checks: `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND` (a segment it used was deleted), `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED` (the environment requires a `note`), `CONFIG_TOO_LARGE`, or `OWNER_NOT_A_MEMBER` (a restored owner left the workspace). |
|
|
170
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
171
|
+
|
|
172
|
+
```ts
|
|
173
|
+
const copyEnvironment = await flags.configs.environments.copy("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
174
|
+
source_environment_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b",
|
|
175
|
+
versions: { "0b8f8a2c-4d3e-4f5a-8b6c-7d8e9f0a1b2c": 3 },
|
|
176
|
+
});
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-copy)
|
|
180
|
+
|
|
181
|
+
### `flags.configs.environments.evaluate(configId, environmentId, params?, options?)`
|
|
182
|
+
|
|
183
|
+
`POST /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/evaluate` → `Flags.TestEvaluation`
|
|
184
|
+
|
|
185
|
+
Test an evaluation.
|
|
186
|
+
|
|
187
|
+
Evaluates a sample user against the published config of this environment (the current revision, or `revision`) with the same engine the SDKs run, and returns the evaluation details per key: value, reason, the rule and percentage option that decided, and soft-miss warnings. Each setting's own value is the default. Nothing is stored and the user is never logged. Limited to 30 calls a minute per credential; the evaluation has a 250 ms budget (422 `EVALUATION_BUDGET_EXCEEDED`, ask for fewer keys).
|
|
188
|
+
|
|
189
|
+
- Params: `Flags.ConfigEnvironmentEvaluateParams`
|
|
190
|
+
|
|
191
|
+
| Status | Error class | Codes | When |
|
|
192
|
+
|---|---|---|---|
|
|
193
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `user` is not an object or null, it has more than 200 attributes, more than 200 `keys`, or a bad `revision`. |
|
|
194
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
195
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND`, `REVISION_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. `REVISION_NOT_FOUND`: the requested revision was pruned or never published. |
|
|
196
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `EVALUATION_BUDGET_EXCEEDED`, `INVALID_TARGETING` | `EVALUATION_BUDGET_EXCEEDED`: the evaluation ran over 250 ms; ask for fewer keys. `INVALID_TARGETING`: the stored revision is not a config the engine accepts. |
|
|
197
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
198
|
+
|
|
199
|
+
```ts
|
|
200
|
+
const testEvaluation = await flags.configs.environments.evaluate("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { keys: ["new_checkout", "banner_text"] });
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-evaluate)
|
|
204
|
+
|
|
205
|
+
## configs.environments.revisions
|
|
206
|
+
|
|
207
|
+
### `flags.configs.environments.revisions.list(configId, environmentId, params?, options?)`
|
|
208
|
+
|
|
209
|
+
`GET /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/revisions` → `PagePromise<Flags.ConfigRevision>`
|
|
210
|
+
|
|
211
|
+
List config revisions.
|
|
212
|
+
|
|
213
|
+
Published revisions of the config in one environment, newest first. Every write that changes what SDKs download publishes a revision; edits that do not (a description, a name) do not. The last 100 revisions, or 20 MiB of compressed snapshots, are kept, and the current one always.
|
|
214
|
+
|
|
215
|
+
- Params: `Flags.ConfigEnvironmentRevisionListParams`
|
|
216
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
217
|
+
|
|
218
|
+
| Status | Error class | Codes | When |
|
|
219
|
+
|---|---|---|---|
|
|
220
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor or `limit`. |
|
|
221
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
222
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. |
|
|
223
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
for await (const revision of flags.configs.environments.revisions.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
|
|
227
|
+
console.log(revision);
|
|
228
|
+
}
|
|
229
|
+
const page = await flags.configs.environments.revisions.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {}, { timeout: 5_000 });
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-revisions)
|
|
233
|
+
|
|
234
|
+
### `flags.configs.environments.revisions.retrieve(configId, environmentId, revision, options?)`
|
|
235
|
+
|
|
236
|
+
`GET /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/revisions/{revision}` → `Flags.ConfigEnvironmentRevisionRetrieveResponse`
|
|
237
|
+
|
|
238
|
+
Get a config revision.
|
|
239
|
+
|
|
240
|
+
The config JSON (schema 1) of one revision, byte for byte what SDKs download: keys, types, values, rules, segments and hashes, but no names, descriptions or cleartext of confidential lists. The response body is the document itself (no envelope).
|
|
241
|
+
|
|
242
|
+
| Status | Error class | Codes | When |
|
|
243
|
+
|---|---|---|---|
|
|
244
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `revision` is not a positive integer. |
|
|
245
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
246
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND`, `REVISION_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. `REVISION_NOT_FOUND`: no such revision (never published, or pruned). |
|
|
247
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
248
|
+
|
|
249
|
+
```ts
|
|
250
|
+
const result = await flags.configs.environments.revisions.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "1");
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-revisions-revision)
|
|
254
|
+
|
|
255
|
+
## configs.environments.sdkKeys
|
|
256
|
+
|
|
257
|
+
### `flags.configs.environments.sdkKeys.endGracePeriod(configId, environmentId, options?)`
|
|
258
|
+
|
|
259
|
+
`DELETE /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/sdk-keys/secondary` → `Flags.SdkKeyList`
|
|
260
|
+
|
|
261
|
+
End the grace period.
|
|
262
|
+
|
|
263
|
+
Revokes the secondary key now instead of at its `expires_at`. SDK servers still using it get 404 within about 5 seconds. Recorded in the history (`sdk_key.grace_ended`) and the workspace audit log.
|
|
264
|
+
|
|
265
|
+
| Status | Error class | Codes | When |
|
|
266
|
+
|---|---|---|---|
|
|
267
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
268
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND`, `SDK_KEY_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. `SDK_KEY_NOT_FOUND`: there is no secondary key. |
|
|
269
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
const sdkKeyList = await flags.configs.environments.sdkKeys.endGracePeriod("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#delete-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-sdk-keys-secondary)
|
|
276
|
+
|
|
277
|
+
### `flags.configs.environments.sdkKeys.list(configId, environmentId, options?)`
|
|
278
|
+
|
|
279
|
+
`GET /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/sdk-keys` → `Flags.SdkKeyList`
|
|
280
|
+
|
|
281
|
+
List SDK keys.
|
|
282
|
+
|
|
283
|
+
The SDK keys of this config in this environment, masked (prefix and last four characters): the primary key, and the secondary key while a rotation's grace period runs. The first call for a new environment mints its primary key.
|
|
284
|
+
|
|
285
|
+
| Status | Error class | Codes | When |
|
|
286
|
+
|---|---|---|---|
|
|
287
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
288
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. |
|
|
289
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
290
|
+
|
|
291
|
+
```ts
|
|
292
|
+
const sdkKeyList = await flags.configs.environments.sdkKeys.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-sdk-keys)
|
|
296
|
+
|
|
297
|
+
### `flags.configs.environments.sdkKeys.reveal(configId, environmentId, options?)`
|
|
298
|
+
|
|
299
|
+
`POST /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/sdk-keys/reveal` → `Flags.RevealedSdkKeyList`
|
|
300
|
+
|
|
301
|
+
Reveal SDK keys.
|
|
302
|
+
|
|
303
|
+
The full primary key, and the secondary key while a grace period runs. Needs `flags.sdk_key.reveal`; every call is recorded in the history (`sdk_key.revealed`) and the workspace audit log. Never cached. Whoever holds a key can download the whole config of this environment: keep server keys server-side.
|
|
304
|
+
|
|
305
|
+
| Status | Error class | Codes | When |
|
|
306
|
+
|---|---|---|---|
|
|
307
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
308
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. |
|
|
309
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
310
|
+
|
|
311
|
+
```ts
|
|
312
|
+
const revealedSdkKeyList = await flags.configs.environments.sdkKeys.reveal("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-sdk-keys-reveal)
|
|
316
|
+
|
|
317
|
+
### `flags.configs.environments.sdkKeys.rotate(configId, environmentId, params?, options?)`
|
|
318
|
+
|
|
319
|
+
`POST /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/sdk-keys/rotate` → `Flags.SdkKeyList`
|
|
320
|
+
|
|
321
|
+
Rotate the SDK key.
|
|
322
|
+
|
|
323
|
+
Mints a new primary key. The current primary becomes the secondary key and keeps working for `grace_hours` (default 24, at most 168; `0` revokes it at once); a previous secondary key is revoked. SDK servers pick up the change within about 5 seconds. The response is masked: reveal the new key separately.
|
|
324
|
+
|
|
325
|
+
- Params: `Flags.ConfigEnvironmentSdkKeyRotateParams`
|
|
326
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
327
|
+
|
|
328
|
+
| Status | Error class | Codes | When |
|
|
329
|
+
|---|---|---|---|
|
|
330
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `grace_hours` is not an integer from 0 to 168, or `note` is too long. |
|
|
331
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
332
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. |
|
|
333
|
+
| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
334
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
335
|
+
|
|
336
|
+
```ts
|
|
337
|
+
const sdkKeyList = await flags.configs.environments.sdkKeys.rotate("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { grace_hours: 24 });
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-sdk-keys-rotate)
|
|
341
|
+
|
|
342
|
+
## configs.environments.values
|
|
343
|
+
|
|
344
|
+
### `flags.configs.environments.values.list(configId, environmentId, params?, options?)`
|
|
345
|
+
|
|
346
|
+
`GET /v1/workspaces/{workspace_id}/configs/{config_id}/environments/{environment_id}/values` → `PagePromise<Flags.EnvironmentValueRow>`
|
|
347
|
+
|
|
348
|
+
List values in an environment.
|
|
349
|
+
|
|
350
|
+
Every setting of the config with its value and targeting in one environment (the flag list), in `ordinal` order. `include=states` adds each setting's compact state in every environment.
|
|
351
|
+
|
|
352
|
+
- Params: `Flags.ConfigEnvironmentValueListParams`
|
|
353
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
354
|
+
|
|
355
|
+
| Status | Error class | Codes | When |
|
|
356
|
+
|---|---|---|---|
|
|
357
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor, `limit` or `include`. |
|
|
358
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
359
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND` (not an environment of the config's project). |
|
|
360
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
361
|
+
|
|
362
|
+
```ts
|
|
363
|
+
for await (const value of flags.configs.environments.values.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
|
|
364
|
+
console.log(value);
|
|
365
|
+
}
|
|
366
|
+
const page = await flags.configs.environments.values.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {}, { timeout: 5_000 });
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-configs-config-id-environments-environment-id-values)
|
|
370
|
+
|
|
371
|
+
## configs.settings
|
|
372
|
+
|
|
373
|
+
### `flags.configs.settings.create(configId, params, options?)`
|
|
374
|
+
|
|
375
|
+
`POST /v1/workspaces/{workspace_id}/configs/{config_id}/settings` → `Flags.SettingDetail`
|
|
376
|
+
|
|
377
|
+
Create a setting.
|
|
378
|
+
|
|
379
|
+
Adds a feature flag (`boolean`) or a typed setting to the config, with a value in every environment (`initial_value`, else the type's zero). Needs `flags.create`; a non-zero `initial_value` is also a value write in every environment (protected ones need `flags.protected.update`).
|
|
380
|
+
|
|
381
|
+
- Params: `Flags.ConfigSettingsCreateParams`
|
|
382
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
383
|
+
|
|
384
|
+
| Status | Error class | Codes | When |
|
|
385
|
+
|---|---|---|---|
|
|
386
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
|
|
387
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
388
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
|
|
389
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: the config already has a setting with this key. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
390
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_VALUE`, `LIMIT_EXCEEDED`, `OWNER_NOT_A_MEMBER`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE` | `INVALID_VALUE`: `initial_value` does not match the type; `LIMIT_EXCEEDED`: the config has the maximum number of settings; `OWNER_NOT_A_MEMBER`: `owner_id` is not a workspace member; `NOTE_REQUIRED`. Publishing: `CONFIG_TOO_LARGE` (the rendered config would exceed 1 MiB; `details.size_bytes`, `max_bytes`) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config` (over 20,000 comparison values in the config); the write is not applied. |
|
|
391
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
392
|
+
| 503 | `InternalServerError` | `SERVICE_UNAVAILABLE` | `SERVICE_UNAVAILABLE`: the member lookup for `owner_id` is unavailable; retry. |
|
|
393
|
+
|
|
394
|
+
```ts
|
|
395
|
+
const settingDetail = await flags.configs.settings.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { key: "new_checkout", type: "boolean" });
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-configs-config-id-settings)
|
|
399
|
+
|
|
400
|
+
### `flags.configs.settings.list(configId, params?, options?)`
|
|
401
|
+
|
|
402
|
+
`GET /v1/workspaces/{workspace_id}/configs/{config_id}/settings` → `PagePromise<Flags.Setting>`
|
|
403
|
+
|
|
404
|
+
List settings.
|
|
405
|
+
|
|
406
|
+
The config's feature flags and settings, in `ordinal` order, with filters.
|
|
407
|
+
|
|
408
|
+
- Params: `Flags.ConfigSettingsListParams`
|
|
409
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
410
|
+
|
|
411
|
+
| Status | Error class | Codes | When |
|
|
412
|
+
|---|---|---|---|
|
|
413
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad filter, cursor or `limit`. |
|
|
414
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
415
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
|
|
416
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
417
|
+
|
|
418
|
+
```ts
|
|
419
|
+
for await (const settings of flags.configs.settings.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
|
|
420
|
+
console.log(settings);
|
|
421
|
+
}
|
|
422
|
+
const page = await flags.configs.settings.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {}, { timeout: 5_000 });
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-configs-config-id-settings)
|
|
426
|
+
|
|
427
|
+
## imports
|
|
428
|
+
|
|
429
|
+
### `flags.imports.create(params, options?)`
|
|
430
|
+
|
|
431
|
+
`POST /v1/workspaces/{workspace_id}/imports` → `Flags.Import`
|
|
432
|
+
|
|
433
|
+
Import from ConfigCat.
|
|
434
|
+
|
|
435
|
+
Reads a ConfigCat product through ConfigCat's Public Management API with credentials you send for this one request (never stored, logged or cached), and maps it to a new Flags project: environments, configs, feature flags and settings (seed = the ConfigCat key, so every user stays in the same percentage bucket), segments, targeting rules, percentage options and prerequisite flags; sensitive comparators become confidential comparators re-hashed under the project salt. Send `dry_run: true` first: it reads and reports (`counts`, `mapped`, `unsupported`, `warnings`) and writes nothing. A real run (`dry_run: false`) creates the project and answers 201; while the report lists `unsupported` items it answers 422 `IMPORT_UNSUPPORTED` unless `skip_unsupported: true`. One synchronous call with a 120 s budget for the ConfigCat reads (paced to ConfigCat's rate limits). Needs `flags.project.manage` and `flags.create`. No Idempotency-Key: the body carries credentials, and a retry of a finished import answers 409 `KEY_ALREADY_EXISTS` (the project name is taken).
|
|
436
|
+
|
|
437
|
+
- Params: `Flags.ImportCreateParams`
|
|
438
|
+
|
|
439
|
+
| Status | Error class | Codes | When |
|
|
440
|
+
|---|---|---|---|
|
|
441
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid (`source` must be `configcat`, `configcat_product_id` a uuid). |
|
|
442
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
443
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `IMPORT_SOURCE_NOT_FOUND` | `IMPORT_SOURCE_NOT_FOUND`: the ConfigCat product does not exist, or the credentials cannot see it. |
|
|
444
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS` | `KEY_ALREADY_EXISTS`: a project with the target name already exists (pass `target_project_name`). |
|
|
445
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `IMPORT_CREDENTIALS_INVALID`, `IMPORT_UNSUPPORTED`, `IMPORT_EXCEEDS_LIMITS` | `IMPORT_CREDENTIALS_INVALID`: ConfigCat rejected the credentials. `IMPORT_UNSUPPORTED`: a real run while the report lists unsupported items (`details.items`); send `skip_unsupported: true` to import without them. `IMPORT_EXCEEDS_LIMITS`: the product is larger than the Flags limits, or reading it ran over the 120 s budget (`details`: `limit`, `max`, `current`). Nothing was imported. |
|
|
446
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
447
|
+
| 502 | `InternalServerError` | `BAD_GATEWAY`, `IMPORT_SOURCE_UNAVAILABLE` | `IMPORT_SOURCE_UNAVAILABLE`: ConfigCat answered 5xx, timed out or could not be reached. |
|
|
448
|
+
|
|
449
|
+
```ts
|
|
450
|
+
const importResult = await flags.imports.create({
|
|
451
|
+
configcat_product_id: "08d8a0b0-0000-4c1f-8a1c-1a2b3c4d5e6f",
|
|
452
|
+
credentials: { password: "cc-basic-auth-password", username: "cc-basic-auth-username" },
|
|
453
|
+
dry_run: true,
|
|
454
|
+
source: "configcat",
|
|
455
|
+
});
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-imports)
|
|
459
|
+
|
|
460
|
+
## limits
|
|
461
|
+
|
|
462
|
+
### `flags.limits.retrieve(options?)`
|
|
463
|
+
|
|
464
|
+
`GET /v1/workspaces/{workspace_id}/limits` → `Flags.FlagsLimits`
|
|
465
|
+
|
|
466
|
+
Get Flags limits and usage.
|
|
467
|
+
|
|
468
|
+
The preview limits that apply to this workspace and how much of the counted ones it uses.
|
|
469
|
+
|
|
470
|
+
| Status | Error class | Codes | When |
|
|
471
|
+
|---|---|---|---|
|
|
472
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
473
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
474
|
+
|
|
475
|
+
```ts
|
|
476
|
+
const flagsLimits = await flags.limits.retrieve();
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-limits)
|
|
480
|
+
|
|
481
|
+
## projects
|
|
482
|
+
|
|
483
|
+
### `flags.projects.create(params, options?)`
|
|
484
|
+
|
|
485
|
+
`POST /v1/workspaces/{workspace_id}/projects` → `Flags.Project`
|
|
486
|
+
|
|
487
|
+
Create a project.
|
|
488
|
+
|
|
489
|
+
Creates the project with the environments of `environment_preset` (default `dev_prod`: Development and a protected Production) and one config, `main`, unless you pass `environments` / `configs`. Every config gets a published state in every environment. Needs `flags.project.manage`.
|
|
490
|
+
|
|
491
|
+
- Params: `Flags.ProjectCreateParams`
|
|
492
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
493
|
+
|
|
494
|
+
| Status | Error class | Codes | When |
|
|
495
|
+
|---|---|---|---|
|
|
496
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
|
|
497
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
498
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: another project has this name, or a key repeats in `environments` / `configs`. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
499
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `LIMIT_EXCEEDED` | `LIMIT_EXCEEDED`: the workspace already has the maximum number of projects (`details`: `limit`, `max`, `current`). |
|
|
500
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
501
|
+
|
|
502
|
+
```ts
|
|
503
|
+
const project = await flags.projects.create({ name: "Storefront" });
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-projects)
|
|
507
|
+
|
|
508
|
+
### `flags.projects.delete(projectId, params, options?)`
|
|
509
|
+
|
|
510
|
+
`DELETE /v1/workspaces/{workspace_id}/projects/{project_id}` → `void`
|
|
511
|
+
|
|
512
|
+
Delete a project.
|
|
513
|
+
|
|
514
|
+
Deletes the project with all of its environments, configs, flags, segments, SDK keys and history. Pass `confirm` with the exact project name. SDKs using its keys stop receiving updates. Needs `flags.project.manage`; recorded in the workspace audit log.
|
|
515
|
+
|
|
516
|
+
- Params: `Flags.ProjectDeleteParams`
|
|
517
|
+
|
|
518
|
+
| Status | Error class | Codes | When |
|
|
519
|
+
|---|---|---|---|
|
|
520
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
521
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
522
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CONFIRMATION_REQUIRED` | `CONFIRMATION_REQUIRED`: `confirm` is missing or is not the exact project name. |
|
|
523
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
524
|
+
|
|
525
|
+
```ts
|
|
526
|
+
await flags.projects.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { confirm: "Storefront" });
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#delete-v1-workspaces-workspace-id-projects-project-id)
|
|
530
|
+
|
|
531
|
+
### `flags.projects.list(params?, options?)`
|
|
532
|
+
|
|
533
|
+
`GET /v1/workspaces/{workspace_id}/projects` → `PagePromise<Flags.Project>`
|
|
534
|
+
|
|
535
|
+
List projects.
|
|
536
|
+
|
|
537
|
+
The workspace's projects, oldest first, each with its environments and configs.
|
|
538
|
+
|
|
539
|
+
- Params: `Flags.ProjectListParams`
|
|
540
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
541
|
+
|
|
542
|
+
| Status | Error class | Codes | When |
|
|
543
|
+
|---|---|---|---|
|
|
544
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor or a `limit` outside 1-100. |
|
|
545
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
546
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
547
|
+
|
|
548
|
+
```ts
|
|
549
|
+
for await (const project of flags.projects.list()) {
|
|
550
|
+
console.log(project);
|
|
551
|
+
}
|
|
552
|
+
const page = await flags.projects.list({}, { timeout: 5_000 });
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-projects)
|
|
556
|
+
|
|
557
|
+
### `flags.projects.retrieve(projectId, options?)`
|
|
558
|
+
|
|
559
|
+
`GET /v1/workspaces/{workspace_id}/projects/{project_id}` → `Flags.Project`
|
|
560
|
+
|
|
561
|
+
Get a project.
|
|
562
|
+
|
|
563
|
+
The project with its environments and configs.
|
|
564
|
+
|
|
565
|
+
| Status | Error class | Codes | When |
|
|
566
|
+
|---|---|---|---|
|
|
567
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
568
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
569
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
570
|
+
|
|
571
|
+
```ts
|
|
572
|
+
const project = await flags.projects.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-projects-project-id)
|
|
576
|
+
|
|
577
|
+
### `flags.projects.update(projectId, params?, options?)`
|
|
578
|
+
|
|
579
|
+
`PATCH /v1/workspaces/{workspace_id}/projects/{project_id}` → `Flags.Project`
|
|
580
|
+
|
|
581
|
+
Update a project.
|
|
582
|
+
|
|
583
|
+
Rename, describe or reorder the project. Only the fields you send change. Needs `flags.project.manage`.
|
|
584
|
+
|
|
585
|
+
- Params: `Flags.ProjectUpdateParams`
|
|
586
|
+
|
|
587
|
+
| Status | Error class | Codes | When |
|
|
588
|
+
|---|---|---|---|
|
|
589
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
|
|
590
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
591
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
592
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS` | `KEY_ALREADY_EXISTS`: another project has this name. |
|
|
593
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
594
|
+
|
|
595
|
+
```ts
|
|
596
|
+
const project = await flags.projects.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { description: "string" });
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-projects-project-id)
|
|
600
|
+
|
|
601
|
+
## projects.changes
|
|
602
|
+
|
|
603
|
+
### `flags.projects.changes.export(projectId, params?, options?)`
|
|
604
|
+
|
|
605
|
+
`GET /v1/workspaces/{workspace_id}/projects/{project_id}/changes/export` → `Response`
|
|
606
|
+
|
|
607
|
+
Export changes.
|
|
608
|
+
|
|
609
|
+
The filtered history as a file, newest first, at most 50,000 rows, streamed. `csv`: one row per change with the summary (no bodies). `json`: JSON Lines (`application/x-ndjson`), one change object per line with `before` and `after` (confidential lists as counts). Cells a spreadsheet would run as a formula start with `'`.
|
|
610
|
+
|
|
611
|
+
- Params: `Flags.ProjectChangeExportParams`
|
|
612
|
+
|
|
613
|
+
| Status | Error class | Codes | When |
|
|
614
|
+
|---|---|---|---|
|
|
615
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad filter or `format`, or `since` is not before `until`. |
|
|
616
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
617
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
618
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
619
|
+
|
|
620
|
+
```ts
|
|
621
|
+
const response = await flags.projects.changes.export("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
622
|
+
const text = await response.text();
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-projects-project-id-changes-export)
|
|
626
|
+
|
|
627
|
+
### `flags.projects.changes.list(projectId, params?, options?)`
|
|
628
|
+
|
|
629
|
+
`GET /v1/workspaces/{workspace_id}/projects/{project_id}/changes` → `PagePromise<Flags.Change>`
|
|
630
|
+
|
|
631
|
+
List changes.
|
|
632
|
+
|
|
633
|
+
The history of a project, newest first: every write with who made it (user, API key, or a client acting for a user), its note, the config revisions it published and a human summary ("Production: value false → true"). Filter by config, environment, setting, segment, actor or time. Confidential lists show as counts, never values.
|
|
634
|
+
|
|
635
|
+
- Params: `Flags.ProjectChangeListParams`
|
|
636
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
637
|
+
|
|
638
|
+
| Status | Error class | Codes | When |
|
|
639
|
+
|---|---|---|---|
|
|
640
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad filter, cursor or `limit`, or `since` is not before `until`. |
|
|
641
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
642
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
643
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
644
|
+
|
|
645
|
+
```ts
|
|
646
|
+
for await (const change of flags.projects.changes.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
|
|
647
|
+
console.log(change);
|
|
648
|
+
}
|
|
649
|
+
const page = await flags.projects.changes.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {}, { timeout: 5_000 });
|
|
650
|
+
```
|
|
651
|
+
|
|
652
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-projects-project-id-changes)
|
|
653
|
+
|
|
654
|
+
## projects.configs
|
|
655
|
+
|
|
656
|
+
### `flags.projects.configs.create(projectId, params, options?)`
|
|
657
|
+
|
|
658
|
+
`POST /v1/workspaces/{workspace_id}/projects/{project_id}/configs` → `Flags.Config`
|
|
659
|
+
|
|
660
|
+
Create a config.
|
|
661
|
+
|
|
662
|
+
Adds a config to the project, with a published state in every environment. Each (config, environment) pair has its own SDK key. Needs `flags.project.manage`.
|
|
663
|
+
|
|
664
|
+
- Params: `Flags.ProjectConfigCreateParams`
|
|
665
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
666
|
+
|
|
667
|
+
| Status | Error class | Codes | When |
|
|
668
|
+
|---|---|---|---|
|
|
669
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
|
|
670
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
671
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
672
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: the project already has a config with this key. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
673
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `LIMIT_EXCEEDED` | `LIMIT_EXCEEDED`: the project already has the maximum number of configs (`details`: `limit`, `max`, `current`). |
|
|
674
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
675
|
+
|
|
676
|
+
```ts
|
|
677
|
+
const config = await flags.projects.configs.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { key: "checkout", name: "Checkout" });
|
|
678
|
+
```
|
|
679
|
+
|
|
680
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-projects-project-id-configs)
|
|
681
|
+
|
|
682
|
+
### `flags.projects.configs.list(projectId, params?, options?)`
|
|
683
|
+
|
|
684
|
+
`GET /v1/workspaces/{workspace_id}/projects/{project_id}/configs` → `PagePromise<Flags.Config>`
|
|
685
|
+
|
|
686
|
+
List configs.
|
|
687
|
+
|
|
688
|
+
The project's configs, in `ordinal` order.
|
|
689
|
+
|
|
690
|
+
- Params: `Flags.ProjectConfigListParams`
|
|
691
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
692
|
+
|
|
693
|
+
| Status | Error class | Codes | When |
|
|
694
|
+
|---|---|---|---|
|
|
695
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor or a `limit` outside 1-100. |
|
|
696
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
697
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
698
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
699
|
+
|
|
700
|
+
```ts
|
|
701
|
+
for await (const config of flags.projects.configs.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
|
|
702
|
+
console.log(config);
|
|
703
|
+
}
|
|
704
|
+
const page = await flags.projects.configs.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {}, { timeout: 5_000 });
|
|
705
|
+
```
|
|
706
|
+
|
|
707
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-projects-project-id-configs)
|
|
708
|
+
|
|
709
|
+
## projects.environments
|
|
710
|
+
|
|
711
|
+
### `flags.projects.environments.create(projectId, params, options?)`
|
|
712
|
+
|
|
713
|
+
`POST /v1/workspaces/{workspace_id}/projects/{project_id}/environments` → `Flags.Environment`
|
|
714
|
+
|
|
715
|
+
Create an environment.
|
|
716
|
+
|
|
717
|
+
Adds an environment to every config of the project. The key `production` starts protected unless you say otherwise. Needs `flags.project.manage`.
|
|
718
|
+
|
|
719
|
+
- Params: `Flags.ProjectEnvironmentCreateParams`
|
|
720
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
721
|
+
|
|
722
|
+
| Status | Error class | Codes | When |
|
|
723
|
+
|---|---|---|---|
|
|
724
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
|
|
725
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
726
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
727
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: the project already has an environment with this key. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
728
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `LIMIT_EXCEEDED` | `LIMIT_EXCEEDED`: the project already has the maximum number of environments (`details`: `limit`, `max`, `current`). |
|
|
729
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
730
|
+
|
|
731
|
+
```ts
|
|
732
|
+
const environment = await flags.projects.environments.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { key: "staging", name: "Staging" });
|
|
733
|
+
```
|
|
734
|
+
|
|
735
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-projects-project-id-environments)
|
|
736
|
+
|
|
737
|
+
### `flags.projects.environments.delete(projectId, environmentId, params?, options?)`
|
|
738
|
+
|
|
739
|
+
`DELETE /v1/workspaces/{workspace_id}/projects/{project_id}/environments/{environment_id}` → `void`
|
|
740
|
+
|
|
741
|
+
Delete an environment.
|
|
742
|
+
|
|
743
|
+
Deletes the environment with its values in every config, and its SDK keys. A project keeps at least one environment. Needs `flags.project.manage`.
|
|
744
|
+
|
|
745
|
+
- Params: `Flags.ProjectEnvironmentDeleteParams`
|
|
746
|
+
|
|
747
|
+
| Status | Error class | Codes | When |
|
|
748
|
+
|---|---|---|---|
|
|
749
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
750
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `ENVIRONMENT_NOT_FOUND`: no such environment in this project. |
|
|
751
|
+
| 409 | `ConflictError` | `CONFLICT`, `LAST_ENVIRONMENT` | `LAST_ENVIRONMENT`: this is the project's only environment. |
|
|
752
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
753
|
+
|
|
754
|
+
```ts
|
|
755
|
+
await flags.projects.environments.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
756
|
+
```
|
|
757
|
+
|
|
758
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#delete-v1-workspaces-workspace-id-projects-project-id-environments-environment-id)
|
|
759
|
+
|
|
760
|
+
### `flags.projects.environments.list(projectId, options?)`
|
|
761
|
+
|
|
762
|
+
`GET /v1/workspaces/{workspace_id}/projects/{project_id}/environments` → `Flags.EnvironmentList`
|
|
763
|
+
|
|
764
|
+
List environments.
|
|
765
|
+
|
|
766
|
+
Every environment of the project, in `ordinal` order.
|
|
767
|
+
|
|
768
|
+
| Status | Error class | Codes | When |
|
|
769
|
+
|---|---|---|---|
|
|
770
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
771
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
772
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
773
|
+
|
|
774
|
+
```ts
|
|
775
|
+
const environmentList = await flags.projects.environments.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
776
|
+
```
|
|
777
|
+
|
|
778
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-projects-project-id-environments)
|
|
779
|
+
|
|
780
|
+
### `flags.projects.environments.retrieve(projectId, environmentId, options?)`
|
|
781
|
+
|
|
782
|
+
`GET /v1/workspaces/{workspace_id}/projects/{project_id}/environments/{environment_id}` → `Flags.Environment`
|
|
783
|
+
|
|
784
|
+
Get an environment.
|
|
785
|
+
|
|
786
|
+
| Status | Error class | Codes | When |
|
|
787
|
+
|---|---|---|---|
|
|
788
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
789
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `ENVIRONMENT_NOT_FOUND`: no such environment in this project. |
|
|
790
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
791
|
+
|
|
792
|
+
```ts
|
|
793
|
+
const environment = await flags.projects.environments.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
794
|
+
```
|
|
795
|
+
|
|
796
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-projects-project-id-environments-environment-id)
|
|
797
|
+
|
|
798
|
+
### `flags.projects.environments.update(projectId, environmentId, params?, options?)`
|
|
799
|
+
|
|
800
|
+
`PATCH /v1/workspaces/{workspace_id}/projects/{project_id}/environments/{environment_id}` → `Flags.Environment`
|
|
801
|
+
|
|
802
|
+
Update an environment.
|
|
803
|
+
|
|
804
|
+
Name, color, order, `protected` and `require_note`; the key never changes. Changing `protected` or `require_note` is recorded in the workspace audit log. Needs `flags.project.manage`.
|
|
805
|
+
|
|
806
|
+
- Params: `Flags.ProjectEnvironmentUpdateParams`
|
|
807
|
+
|
|
808
|
+
| Status | Error class | Codes | When |
|
|
809
|
+
|---|---|---|---|
|
|
810
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
|
|
811
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
812
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `ENVIRONMENT_NOT_FOUND`: no such environment in this project. |
|
|
813
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
814
|
+
|
|
815
|
+
```ts
|
|
816
|
+
const environment = await flags.projects.environments.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { color: "#e67700" });
|
|
817
|
+
```
|
|
818
|
+
|
|
819
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-projects-project-id-environments-environment-id)
|
|
820
|
+
|
|
821
|
+
## projects.segments
|
|
822
|
+
|
|
823
|
+
### `flags.projects.segments.create(projectId, params, options?)`
|
|
824
|
+
|
|
825
|
+
`POST /v1/workspaces/{workspace_id}/projects/{project_id}/segments` → `Flags.SegmentDetail`
|
|
826
|
+
|
|
827
|
+
Create a segment.
|
|
828
|
+
|
|
829
|
+
A reusable set of ANDed user conditions that any config of the project can target with `{segment: {segment_id, comparator: in | not_in}}`. Confidential lists are stored as hashes plus encrypted cleartext; the response shows only their count.
|
|
830
|
+
|
|
831
|
+
- Params: `Flags.ProjectSegmentCreateParams`
|
|
832
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
833
|
+
|
|
834
|
+
| Status | Error class | Codes | When |
|
|
835
|
+
|---|---|---|---|
|
|
836
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
|
|
837
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
838
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
839
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: the project already has a segment with this key. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
840
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_TARGETING`, `LIMIT_EXCEEDED`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `NOTE_REQUIRED` | The conditions are invalid; `details.errors` lists every problem (`param`, `code`, `message`) and `code` is the first one: `INVALID_TARGETING` (shape, comparator or value), `LIMIT_EXCEEDED` (conditions, values or segments per project), `CONFIDENTIAL_LIST_NOT_EDITABLE` (`values_add` / `values_remove` on a list sent pre-hashed), or `NOTE_REQUIRED` (the segment is used in an environment that requires a `note`). |
|
|
841
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
842
|
+
|
|
843
|
+
```ts
|
|
844
|
+
const segmentDetail = await flags.projects.segments.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
845
|
+
conditions: [
|
|
846
|
+
{
|
|
847
|
+
user: { attribute: "email", comparator: "ends_with_any_hashed", values: ["@acme.test"] },
|
|
848
|
+
},
|
|
849
|
+
],
|
|
850
|
+
key: "qa_staff",
|
|
851
|
+
});
|
|
852
|
+
```
|
|
853
|
+
|
|
854
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-projects-project-id-segments)
|
|
855
|
+
|
|
856
|
+
### `flags.projects.segments.list(projectId, params?, options?)`
|
|
857
|
+
|
|
858
|
+
`GET /v1/workspaces/{workspace_id}/projects/{project_id}/segments` → `PagePromise<Flags.Segment>`
|
|
859
|
+
|
|
860
|
+
List segments.
|
|
861
|
+
|
|
862
|
+
The project's segments, oldest first, with `usage_count`.
|
|
863
|
+
|
|
864
|
+
- Params: `Flags.ProjectSegmentListParams`
|
|
865
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
866
|
+
|
|
867
|
+
| Status | Error class | Codes | When |
|
|
868
|
+
|---|---|---|---|
|
|
869
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor or `limit`. |
|
|
870
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
871
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
|
|
872
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
873
|
+
|
|
874
|
+
```ts
|
|
875
|
+
for await (const segment of flags.projects.segments.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
|
|
876
|
+
console.log(segment);
|
|
877
|
+
}
|
|
878
|
+
const page = await flags.projects.segments.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {}, { timeout: 5_000 });
|
|
879
|
+
```
|
|
880
|
+
|
|
881
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-projects-project-id-segments)
|
|
882
|
+
|
|
883
|
+
## segments
|
|
884
|
+
|
|
885
|
+
### `flags.segments.delete(segmentId, params?, options?)`
|
|
886
|
+
|
|
887
|
+
`DELETE /v1/workspaces/{workspace_id}/segments/{segment_id}` → `void`
|
|
888
|
+
|
|
889
|
+
Delete a segment.
|
|
890
|
+
|
|
891
|
+
Deletes an unused segment. Needs `flags.delete`.
|
|
892
|
+
|
|
893
|
+
- Params: `Flags.SegmentDeleteParams`
|
|
894
|
+
|
|
895
|
+
| Status | Error class | Codes | When |
|
|
896
|
+
|---|---|---|---|
|
|
897
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
898
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
|
|
899
|
+
| 409 | `ConflictError` | `CONFLICT`, `SEGMENT_IN_USE` | `SEGMENT_IN_USE`: a rule uses it (`details.used_by` lists where). |
|
|
900
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
901
|
+
|
|
902
|
+
```ts
|
|
903
|
+
await flags.segments.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
904
|
+
```
|
|
905
|
+
|
|
906
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#delete-v1-workspaces-workspace-id-segments-segment-id)
|
|
907
|
+
|
|
908
|
+
### `flags.segments.retrieve(segmentId, options?)`
|
|
909
|
+
|
|
910
|
+
`GET /v1/workspaces/{workspace_id}/segments/{segment_id}` → `Flags.SegmentDetail`
|
|
911
|
+
|
|
912
|
+
Get a segment.
|
|
913
|
+
|
|
914
|
+
The segment with its conditions and every (setting, environment) that uses it (`used_by`).
|
|
915
|
+
|
|
916
|
+
| Status | Error class | Codes | When |
|
|
917
|
+
|---|---|---|---|
|
|
918
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
919
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
|
|
920
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
921
|
+
|
|
922
|
+
```ts
|
|
923
|
+
const segmentDetail = await flags.segments.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
924
|
+
```
|
|
925
|
+
|
|
926
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-segments-segment-id)
|
|
927
|
+
|
|
928
|
+
### `flags.segments.revealConfidential(segmentId, options?)`
|
|
929
|
+
|
|
930
|
+
`GET /v1/workspaces/{workspace_id}/segments/{segment_id}/confidential` → `Flags.ConfidentialReveal`
|
|
931
|
+
|
|
932
|
+
Reveal confidential values of a segment.
|
|
933
|
+
|
|
934
|
+
The cleartext of the segment's confidential lists, decrypted. Needs `flags.confidential.read`; every call is recorded in the history (`confidential.revealed`). Never cached.
|
|
935
|
+
|
|
936
|
+
| Status | Error class | Codes | When |
|
|
937
|
+
|---|---|---|---|
|
|
938
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
939
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
|
|
940
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CONFIDENTIAL_LIST_NOT_EDITABLE` | `CONFIDENTIAL_LIST_NOT_EDITABLE`: every confidential list was sent pre-hashed, so there is no cleartext. |
|
|
941
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
942
|
+
|
|
943
|
+
```ts
|
|
944
|
+
const confidentialReveal = await flags.segments.revealConfidential("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
945
|
+
```
|
|
946
|
+
|
|
947
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-segments-segment-id-confidential)
|
|
948
|
+
|
|
949
|
+
### `flags.segments.update(segmentId, params?, options?)`
|
|
950
|
+
|
|
951
|
+
`PATCH /v1/workspaces/{workspace_id}/segments/{segment_id}` → `Flags.SegmentDetail`
|
|
952
|
+
|
|
953
|
+
Update a segment.
|
|
954
|
+
|
|
955
|
+
Key, name, description or conditions; only the fields you send change. Edit a confidential list with `list_id` plus `values_add` / `values_remove`. A segment used in a protected environment also needs `flags.protected.update` there.
|
|
956
|
+
|
|
957
|
+
- Params: `Flags.SegmentUpdateParams`
|
|
958
|
+
|
|
959
|
+
| Status | Error class | Codes | When |
|
|
960
|
+
|---|---|---|---|
|
|
961
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
|
|
962
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). A segment used in a protected environment also needs `flags.protected.update` on it. |
|
|
963
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
|
|
964
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `VERSION_CONFLICT` | `KEY_ALREADY_EXISTS`: the project already has a segment with this key; `VERSION_CONFLICT`: `version` is stale (`details.current_version`). |
|
|
965
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_TARGETING`, `LIMIT_EXCEEDED`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE` | The conditions are invalid; `details.errors` lists every problem (`param`, `code`, `message`) and `code` is the first one: `INVALID_TARGETING` (shape, comparator or value), `LIMIT_EXCEEDED` (conditions, values or segments per project), `CONFIDENTIAL_LIST_NOT_EDITABLE` (`values_add` / `values_remove` on a list sent pre-hashed), or `NOTE_REQUIRED` (the segment is used in an environment that requires a `note`). Publishing (every config that uses the segment): `CONFIG_TOO_LARGE` (a rendered config would exceed 1 MiB) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config`; the edit is not applied. |
|
|
966
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
967
|
+
|
|
968
|
+
```ts
|
|
969
|
+
const segmentDetail = await flags.segments.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
|
|
970
|
+
conditions: [
|
|
971
|
+
{
|
|
972
|
+
user: {
|
|
973
|
+
attribute: "email",
|
|
974
|
+
comparator: "ends_with_any_hashed",
|
|
975
|
+
list_id: "3f0c6a3e-0f5e-4b8e-9d1a-2c7b9f1e8a10",
|
|
976
|
+
values_add: ["@beta.test"],
|
|
977
|
+
},
|
|
978
|
+
},
|
|
979
|
+
],
|
|
980
|
+
});
|
|
981
|
+
```
|
|
982
|
+
|
|
983
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-segments-segment-id)
|
|
984
|
+
|
|
985
|
+
## settings
|
|
986
|
+
|
|
987
|
+
### `flags.settings.delete(settingId, params?, options?)`
|
|
988
|
+
|
|
989
|
+
`DELETE /v1/workspaces/{workspace_id}/settings/{setting_id}` → `void`
|
|
990
|
+
|
|
991
|
+
Delete a setting.
|
|
992
|
+
|
|
993
|
+
Deletes the setting and its values in every environment. Needs `flags.delete`.
|
|
994
|
+
|
|
995
|
+
- Params: `Flags.SettingsDeleteParams`
|
|
996
|
+
|
|
997
|
+
| Status | Error class | Codes | When |
|
|
998
|
+
|---|---|---|---|
|
|
999
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
1000
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND` | `SETTING_NOT_FOUND`: no such setting in this workspace. |
|
|
1001
|
+
| 409 | `ConflictError` | `CONFLICT`, `SETTING_IN_USE` | `SETTING_IN_USE`: another setting uses it as a prerequisite (`details.used_by`). |
|
|
1002
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1003
|
+
|
|
1004
|
+
```ts
|
|
1005
|
+
await flags.settings.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
1006
|
+
```
|
|
1007
|
+
|
|
1008
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#delete-v1-workspaces-workspace-id-settings-setting-id)
|
|
1009
|
+
|
|
1010
|
+
### `flags.settings.retrieve(settingId, options?)`
|
|
1011
|
+
|
|
1012
|
+
`GET /v1/workspaces/{workspace_id}/settings/{setting_id}` → `Flags.SettingDetail`
|
|
1013
|
+
|
|
1014
|
+
Get a setting.
|
|
1015
|
+
|
|
1016
|
+
The setting with its value and targeting in every environment, and what depends on it (`dependents`).
|
|
1017
|
+
|
|
1018
|
+
| Status | Error class | Codes | When |
|
|
1019
|
+
|---|---|---|---|
|
|
1020
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
1021
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND` | `SETTING_NOT_FOUND`: no such setting in this workspace. |
|
|
1022
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1023
|
+
|
|
1024
|
+
```ts
|
|
1025
|
+
const settingDetail = await flags.settings.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
1026
|
+
```
|
|
1027
|
+
|
|
1028
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-settings-setting-id)
|
|
1029
|
+
|
|
1030
|
+
### `flags.settings.update(settingId, params?, options?)`
|
|
1031
|
+
|
|
1032
|
+
`PATCH /v1/workspaces/{workspace_id}/settings/{setting_id}` → `Flags.SettingDetail`
|
|
1033
|
+
|
|
1034
|
+
Update a setting.
|
|
1035
|
+
|
|
1036
|
+
Key, name, description, hint, tags, lifecycle, owner or order; only the fields you send change. The type cannot change. Renaming the key keeps the seed (users stay in their split buckets) and needs `flags.protected.update` when the project has a protected environment.
|
|
1037
|
+
|
|
1038
|
+
- Params: `Flags.SettingsUpdateParams`
|
|
1039
|
+
|
|
1040
|
+
| Status | Error class | Codes | When |
|
|
1041
|
+
|---|---|---|---|
|
|
1042
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
|
|
1043
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
1044
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND` | `SETTING_NOT_FOUND`: no such setting in this workspace. |
|
|
1045
|
+
| 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS` | `KEY_ALREADY_EXISTS`: the config already has a setting with this key. |
|
|
1046
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `SETTING_TYPE_IMMUTABLE`, `OWNER_NOT_A_MEMBER`, `CONFIG_TOO_LARGE`, `LIMIT_EXCEEDED` | `SETTING_TYPE_IMMUTABLE`: `type` differs from the current one; `OWNER_NOT_A_MEMBER`: `owner_id` is not a workspace member. Publishing: `CONFIG_TOO_LARGE` (the rendered config would exceed 1 MiB; `details.size_bytes`, `max_bytes`) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config` (over 20,000 comparison values in the config); the write is not applied. |
|
|
1047
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1048
|
+
| 503 | `InternalServerError` | `SERVICE_UNAVAILABLE` | `SERVICE_UNAVAILABLE`: the member lookup for `owner_id` is unavailable; retry. |
|
|
1049
|
+
|
|
1050
|
+
```ts
|
|
1051
|
+
const settingDetail = await flags.settings.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { description: "string" });
|
|
1052
|
+
```
|
|
1053
|
+
|
|
1054
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-settings-setting-id)
|
|
1055
|
+
|
|
1056
|
+
## settings.values
|
|
1057
|
+
|
|
1058
|
+
### `flags.settings.values.replace(settingId, environmentId, params, options?)`
|
|
1059
|
+
|
|
1060
|
+
`PUT /v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}` → `Flags.SettingValue`
|
|
1061
|
+
|
|
1062
|
+
Replace a value.
|
|
1063
|
+
|
|
1064
|
+
Replaces the value and the whole targeting (rules, flag-level split, split attribute) in one environment. Send the `version` you read.
|
|
1065
|
+
|
|
1066
|
+
- Params: `Flags.SettingsValueReplaceParams`
|
|
1067
|
+
|
|
1068
|
+
| Status | Error class | Codes | When |
|
|
1069
|
+
|---|---|---|---|
|
|
1070
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `version` or `note` is missing or invalid. |
|
|
1071
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). Value writes need `flags.value.update` on the environment and the setting, plus `flags.protected.update` in a protected environment. |
|
|
1072
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
|
|
1073
|
+
| 409 | `ConflictError` | `CONFLICT`, `VERSION_CONFLICT` | `VERSION_CONFLICT`: the value changed since you read it (`details.current_version`, `updated_at`, `updated_by`). |
|
|
1074
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `PERCENTAGES_MUST_SUM_TO_100`, `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE` | The value or targeting is invalid; `details.errors` lists every problem (`param`, `code`, `message`) and `code` is the first one: `INVALID_VALUE` (type mismatch, over 100 KB, json that does not parse), `INVALID_TARGETING` (shape, comparator or comparison value), `SEGMENT_NOT_FOUND` (a segment condition names no segment of this project), `CONFIDENTIAL_LIST_NOT_EDITABLE` (`values_add` / `values_remove` on a list sent pre-hashed), `PERCENTAGES_MUST_SUM_TO_100`, `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE` (`details.cycle` lists the keys), `LIMIT_EXCEEDED` (rules, conditions, values or prerequisite depth), or `NOTE_REQUIRED` (the environment requires a `note`). Publishing: `CONFIG_TOO_LARGE` (the rendered config would exceed 1 MiB; `details.size_bytes`, `max_bytes`) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config` (over 20,000 comparison values in the config); the write is not applied. |
|
|
1075
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1076
|
+
|
|
1077
|
+
```ts
|
|
1078
|
+
const settingValue = await flags.settings.values.replace("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { value: false, version: 3 });
|
|
1079
|
+
```
|
|
1080
|
+
|
|
1081
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#put-v1-workspaces-workspace-id-settings-setting-id-values-environment-id)
|
|
1082
|
+
|
|
1083
|
+
### `flags.settings.values.retrieve(settingId, environmentId, options?)`
|
|
1084
|
+
|
|
1085
|
+
`GET /v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}` → `Flags.SettingValue`
|
|
1086
|
+
|
|
1087
|
+
Get a value.
|
|
1088
|
+
|
|
1089
|
+
The setting's value and targeting in one environment, with its `version`.
|
|
1090
|
+
|
|
1091
|
+
| Status | Error class | Codes | When |
|
|
1092
|
+
|---|---|---|---|
|
|
1093
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
1094
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
|
|
1095
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1096
|
+
|
|
1097
|
+
```ts
|
|
1098
|
+
const settingValue = await flags.settings.values.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
1099
|
+
```
|
|
1100
|
+
|
|
1101
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-settings-setting-id-values-environment-id)
|
|
1102
|
+
|
|
1103
|
+
### `flags.settings.values.revealConfidential(settingId, environmentId, options?)`
|
|
1104
|
+
|
|
1105
|
+
`GET /v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/confidential` → `Flags.ConfidentialReveal`
|
|
1106
|
+
|
|
1107
|
+
Reveal confidential values.
|
|
1108
|
+
|
|
1109
|
+
The cleartext of this value's confidential lists, decrypted. Needs `flags.confidential.read` on the environment and the setting; every call is recorded in the history (`confidential.revealed`). Never cached.
|
|
1110
|
+
|
|
1111
|
+
| Status | Error class | Codes | When |
|
|
1112
|
+
|---|---|---|---|
|
|
1113
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
1114
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
|
|
1115
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CONFIDENTIAL_LIST_NOT_EDITABLE` | `CONFIDENTIAL_LIST_NOT_EDITABLE`: every confidential list was sent pre-hashed, so there is no cleartext. |
|
|
1116
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1117
|
+
|
|
1118
|
+
```ts
|
|
1119
|
+
const confidentialReveal = await flags.settings.values.revealConfidential("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
1120
|
+
```
|
|
1121
|
+
|
|
1122
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-settings-setting-id-values-environment-id-confidential)
|
|
1123
|
+
|
|
1124
|
+
### `flags.settings.values.update(settingId, environmentId, params, options?)`
|
|
1125
|
+
|
|
1126
|
+
`PATCH /v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}` → `Flags.SettingValue`
|
|
1127
|
+
|
|
1128
|
+
Update a value.
|
|
1129
|
+
|
|
1130
|
+
The quick edits: `value` (the toggle), `percentage_attribute`, and `clear_rules: true` to drop every rule and split so `value` is served to everyone (the kill switch). Send the `version` you read.
|
|
1131
|
+
|
|
1132
|
+
- Params: `Flags.SettingsValueUpdateParams`
|
|
1133
|
+
|
|
1134
|
+
| Status | Error class | Codes | When |
|
|
1135
|
+
|---|---|---|---|
|
|
1136
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: nothing to change, or `version` is missing. |
|
|
1137
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). Value writes need `flags.value.update` on the environment and the setting, plus `flags.protected.update` in a protected environment. |
|
|
1138
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
|
|
1139
|
+
| 409 | `ConflictError` | `CONFLICT`, `VERSION_CONFLICT` | `VERSION_CONFLICT`: the value changed since you read it (`details.current_version`, `updated_at`, `updated_by`). |
|
|
1140
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_VALUE`, `INVALID_TARGETING`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE`, `LIMIT_EXCEEDED` | `INVALID_VALUE`, `INVALID_TARGETING` or `NOTE_REQUIRED`; `details.errors` lists each problem. Publishing: `CONFIG_TOO_LARGE` (the rendered config would exceed 1 MiB; `details.size_bytes`, `max_bytes`) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config` (over 20,000 comparison values in the config); the write is not applied. |
|
|
1141
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1142
|
+
|
|
1143
|
+
```ts
|
|
1144
|
+
const settingValue = await flags.settings.values.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { version: 3 });
|
|
1145
|
+
```
|
|
1146
|
+
|
|
1147
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-settings-setting-id-values-environment-id)
|
|
1148
|
+
|
|
1149
|
+
## stats
|
|
1150
|
+
|
|
1151
|
+
### `flags.stats.retrieve(options?)`
|
|
1152
|
+
|
|
1153
|
+
`GET /v1/workspaces/{workspace_id}/stats` → `Flags.FlagsStats`
|
|
1154
|
+
|
|
1155
|
+
Get Flags stats.
|
|
1156
|
+
|
|
1157
|
+
Counts for the workspace: projects, configs, flags and settings, segments, changes in the last 7 days and when the latest change was made, plus each project’s history usage against the retention caps (50,000 rows or 200 MiB per project; `warning` from 80%). Counts only: no keys, values or rules.
|
|
1158
|
+
|
|
1159
|
+
| Status | Error class | Codes | When |
|
|
1160
|
+
|---|---|---|---|
|
|
1161
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
|
|
1162
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1163
|
+
|
|
1164
|
+
```ts
|
|
1165
|
+
const flagsStats = await flags.stats.retrieve();
|
|
1166
|
+
```
|
|
1167
|
+
|
|
1168
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-stats)
|
|
1169
|
+
|
|
1170
|
+
## webhooks
|
|
1171
|
+
|
|
1172
|
+
### `flags.webhooks.unwrap({ payload, headers, secret? })`
|
|
1173
|
+
|
|
1174
|
+
Verifies the signature and returns `Flags.UnwrapWebhookEvent`. Events: `config.published`, `sdk_key.rotated`, plus `UnknownWebhookEvent` for types added later.
|
|
1175
|
+
|
|
1176
|
+
### `flags.webhooks.sign({ payload, secret?, id?, timestamp? })`
|
|
1177
|
+
|
|
1178
|
+
Signs a test event exactly as ProductCraft signs deliveries (Standard Webhooks) and returns `{ payload, headers }`, ready for `unwrap` or a request to your handler. For tests; real deliveries come signed.
|
|
1179
|
+
|
|
1180
|
+
## webhooks.endpoints
|
|
1181
|
+
|
|
1182
|
+
### `flags.webhooks.endpoints.create(params, options?)`
|
|
1183
|
+
|
|
1184
|
+
`POST /v1/workspaces/{workspace_id}/webhooks/endpoints` → `Flags.WebhookEndpointWithSecret`
|
|
1185
|
+
|
|
1186
|
+
Add a webhook endpoint. Returns its signing secret once.
|
|
1187
|
+
|
|
1188
|
+
Deliveries are signed with the Standard Webhooks headers `webhook-id`, `webhook-timestamp` and `webhook-signature` (`v1,<base64 HMAC-SHA256 of "<id>.<timestamp>.<body>">`); the returned `whsec_…` secret works unchanged with any Standard Webhooks library. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h.
|
|
1189
|
+
|
|
1190
|
+
- Params: `Flags.WebhookEndpointCreateParams`
|
|
1191
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
1192
|
+
|
|
1193
|
+
| Status | Error class | Codes | When |
|
|
1194
|
+
|---|---|---|---|
|
|
1195
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `WEBHOOK_EVENT_TYPE_UNKNOWN` | Validation failure: URL not https with a public host, or an unknown event type (`WEBHOOK_EVENT_TYPE_UNKNOWN`). |
|
|
1196
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1197
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1198
|
+
| 409 | `ConflictError` | `CONFLICT`, `WEBHOOK_ENDPOINT_LIMIT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Already 10 endpoints (`WEBHOOK_ENDPOINT_LIMIT`), or Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
1199
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | The URL points at a private, loopback or internal address. |
|
|
1200
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1201
|
+
|
|
1202
|
+
```ts
|
|
1203
|
+
const webhookEndpoint = await flags.webhooks.endpoints.create({ url: "https://api.acme.com/webhooks" });
|
|
1204
|
+
```
|
|
1205
|
+
|
|
1206
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-webhooks-endpoints)
|
|
1207
|
+
|
|
1208
|
+
### `flags.webhooks.endpoints.delete(endpointId, options?)`
|
|
1209
|
+
|
|
1210
|
+
`DELETE /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}` → `void`
|
|
1211
|
+
|
|
1212
|
+
Delete a webhook endpoint.
|
|
1213
|
+
|
|
1214
|
+
Queued retries are dropped. Its past attempts stay in the event log until the events expire.
|
|
1215
|
+
|
|
1216
|
+
| Status | Error class | Codes | When |
|
|
1217
|
+
|---|---|---|---|
|
|
1218
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `endpoint_id` is not a UUID. |
|
|
1219
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1220
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1221
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
|
|
1222
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1223
|
+
|
|
1224
|
+
```ts
|
|
1225
|
+
await flags.webhooks.endpoints.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
1226
|
+
```
|
|
1227
|
+
|
|
1228
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#delete-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id)
|
|
1229
|
+
|
|
1230
|
+
### `flags.webhooks.endpoints.list(options?)`
|
|
1231
|
+
|
|
1232
|
+
`GET /v1/workspaces/{workspace_id}/webhooks/endpoints` → `PagePromise<Flags.WebhookEndpoint>`
|
|
1233
|
+
|
|
1234
|
+
List webhook endpoints, oldest first.
|
|
1235
|
+
|
|
1236
|
+
At most 10, so this is always one page. Signing secrets are never returned here, only their last 4 characters.
|
|
1237
|
+
|
|
1238
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
1239
|
+
|
|
1240
|
+
| Status | Error class | Codes | When |
|
|
1241
|
+
|---|---|---|---|
|
|
1242
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | The scope id in the path is malformed. |
|
|
1243
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1244
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1245
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1246
|
+
|
|
1247
|
+
```ts
|
|
1248
|
+
for await (const endpoint of flags.webhooks.endpoints.list()) {
|
|
1249
|
+
console.log(endpoint);
|
|
1250
|
+
}
|
|
1251
|
+
```
|
|
1252
|
+
|
|
1253
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-webhooks-endpoints)
|
|
1254
|
+
|
|
1255
|
+
### `flags.webhooks.endpoints.retrieve(endpointId, options?)`
|
|
1256
|
+
|
|
1257
|
+
`GET /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}` → `Flags.WebhookEndpoint`
|
|
1258
|
+
|
|
1259
|
+
Get one webhook endpoint (without its secret).
|
|
1260
|
+
|
|
1261
|
+
The endpoint's URL, subscription, on/off state, failure streak and the last 4 characters of its signing secret. The full secret is only returned when the endpoint is created or its secret is rotated.
|
|
1262
|
+
|
|
1263
|
+
| Status | Error class | Codes | When |
|
|
1264
|
+
|---|---|---|---|
|
|
1265
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `endpoint_id` is not a UUID. |
|
|
1266
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1267
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1268
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
|
|
1269
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1270
|
+
|
|
1271
|
+
```ts
|
|
1272
|
+
const webhookEndpoint = await flags.webhooks.endpoints.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
|
|
1273
|
+
```
|
|
1274
|
+
|
|
1275
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id)
|
|
1276
|
+
|
|
1277
|
+
### `flags.webhooks.endpoints.rotateSecret(endpointId, params?, options?)`
|
|
1278
|
+
|
|
1279
|
+
`POST /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}/rotate-secret` → `Flags.WebhookEndpointWithSecret`
|
|
1280
|
+
|
|
1281
|
+
Rotate the signing secret. The new one is returned once.
|
|
1282
|
+
|
|
1283
|
+
For `grace_hours` (default 24) the previous secret keeps signing too: `webhook-signature` then lists one `v1,` signature per secret, so receivers can switch over without dropping a delivery.
|
|
1284
|
+
|
|
1285
|
+
- Params: `Flags.WebhookEndpointRotateSecretParams`
|
|
1286
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
1287
|
+
|
|
1288
|
+
| Status | Error class | Codes | When |
|
|
1289
|
+
|---|---|---|---|
|
|
1290
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `grace_hours` out of range, or `endpoint_id` is not a UUID. |
|
|
1291
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1292
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1293
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
|
|
1294
|
+
| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
1295
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1296
|
+
|
|
1297
|
+
```ts
|
|
1298
|
+
const webhookEndpoint = await flags.webhooks.endpoints.rotateSecret("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { grace_hours: 24 });
|
|
1299
|
+
```
|
|
1300
|
+
|
|
1301
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id-rotate-secret)
|
|
1302
|
+
|
|
1303
|
+
### `flags.webhooks.endpoints.test(endpointId, params, options?)`
|
|
1304
|
+
|
|
1305
|
+
`POST /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}/test` → `Flags.WebhookDeliveryAttempt`
|
|
1306
|
+
|
|
1307
|
+
Send a test event to this endpoint now and return the result.
|
|
1308
|
+
|
|
1309
|
+
Delivers the catalogue example of `event_type`, signed like any delivery, with `"test": true` in the body. Works while the endpoint is switched off or not subscribed to that type, is logged in the event log, and is never retried or counted toward an automatic disable. Waits up to 15 s for your receiver.
|
|
1310
|
+
|
|
1311
|
+
- Params: `Flags.WebhookEndpointTestParams`
|
|
1312
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
1313
|
+
|
|
1314
|
+
| Status | Error class | Codes | When |
|
|
1315
|
+
|---|---|---|---|
|
|
1316
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Unknown `event_type`, or `endpoint_id` is not a UUID. |
|
|
1317
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1318
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1319
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
|
|
1320
|
+
| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
1321
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1322
|
+
|
|
1323
|
+
```ts
|
|
1324
|
+
const webhookDeliveryAttempt = await flags.webhooks.endpoints.test("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { event_type: "config.published" });
|
|
1325
|
+
```
|
|
1326
|
+
|
|
1327
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id-test)
|
|
1328
|
+
|
|
1329
|
+
### `flags.webhooks.endpoints.update(endpointId, params?, options?)`
|
|
1330
|
+
|
|
1331
|
+
`PATCH /v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}` → `Flags.WebhookEndpoint`
|
|
1332
|
+
|
|
1333
|
+
Change a webhook endpoint: URL, description, events, on/off.
|
|
1334
|
+
|
|
1335
|
+
Only the fields sent change. `enabled: true` (or a new URL) also clears an automatic disable. Switching off cancels queued retries. The secret is unchanged; rotate it with `POST …/rotate-secret`.
|
|
1336
|
+
|
|
1337
|
+
- Params: `Flags.WebhookEndpointUpdateParams`
|
|
1338
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
1339
|
+
|
|
1340
|
+
| Status | Error class | Codes | When |
|
|
1341
|
+
|---|---|---|---|
|
|
1342
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure, or `endpoint_id` is not a UUID. |
|
|
1343
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1344
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1345
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
|
|
1346
|
+
| 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
1347
|
+
| 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | The new URL points at a private, loopback or internal address. |
|
|
1348
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1349
|
+
|
|
1350
|
+
```ts
|
|
1351
|
+
const webhookEndpoint = await flags.webhooks.endpoints.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { config_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b" });
|
|
1352
|
+
```
|
|
1353
|
+
|
|
1354
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#patch-v1-workspaces-workspace-id-webhooks-endpoints-endpoint-id)
|
|
1355
|
+
|
|
1356
|
+
## webhooks.eventTypes
|
|
1357
|
+
|
|
1358
|
+
### `flags.webhooks.eventTypes.list(options?)`
|
|
1359
|
+
|
|
1360
|
+
`GET /v1/workspaces/{workspace_id}/webhooks/event-types` → `Flags.WebhookEventTypeList`
|
|
1361
|
+
|
|
1362
|
+
List the events an endpoint can subscribe to.
|
|
1363
|
+
|
|
1364
|
+
Each type with a plain description, its group and an example `data` object (what "Send test" delivers).
|
|
1365
|
+
|
|
1366
|
+
| Status | Error class | Codes | When |
|
|
1367
|
+
|---|---|---|---|
|
|
1368
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1369
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1370
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1371
|
+
|
|
1372
|
+
```ts
|
|
1373
|
+
const webhookEventTypeList = await flags.webhooks.eventTypes.list();
|
|
1374
|
+
```
|
|
1375
|
+
|
|
1376
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-webhooks-event-types)
|
|
1377
|
+
|
|
1378
|
+
## webhooks.events
|
|
1379
|
+
|
|
1380
|
+
### `flags.webhooks.events.list(params?, options?)`
|
|
1381
|
+
|
|
1382
|
+
`GET /v1/workspaces/{workspace_id}/webhooks/events` → `PagePromise<Flags.WebhookEvent>`
|
|
1383
|
+
|
|
1384
|
+
List webhook events, newest first (kept for 30 days).
|
|
1385
|
+
|
|
1386
|
+
Every event logged while at least one endpoint existed, with the latest state per endpoint and when the next retry is due.
|
|
1387
|
+
|
|
1388
|
+
- Params: `Flags.WebhookEventListParams`
|
|
1389
|
+
- Paginated: `for await` iterates every item; `await` gives one page
|
|
1390
|
+
|
|
1391
|
+
| Status | Error class | Codes | When |
|
|
1392
|
+
|---|---|---|---|
|
|
1393
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid filter value or cursor. |
|
|
1394
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1395
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1396
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1397
|
+
|
|
1398
|
+
```ts
|
|
1399
|
+
for await (const event of flags.webhooks.events.list()) {
|
|
1400
|
+
console.log(event);
|
|
1401
|
+
}
|
|
1402
|
+
const page = await flags.webhooks.events.list({}, { timeout: 5_000 });
|
|
1403
|
+
```
|
|
1404
|
+
|
|
1405
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-webhooks-events)
|
|
1406
|
+
|
|
1407
|
+
### `flags.webhooks.events.replay(eventId, params?, options?)`
|
|
1408
|
+
|
|
1409
|
+
`POST /v1/workspaces/{workspace_id}/webhooks/events/{event_id}/replay` → `Flags.WebhookEventReplay`
|
|
1410
|
+
|
|
1411
|
+
Send a logged event again, to its endpoints or to one endpoint.
|
|
1412
|
+
|
|
1413
|
+
Same body and `webhook-id`, freshly signed, to every switched-on endpoint that receives this event type now, or only to `endpoint_id`. Waits for the receivers (up to 15 s each) and returns the attempts. A success cancels a retry still queued for that endpoint.
|
|
1414
|
+
|
|
1415
|
+
- Params: `Flags.WebhookEventReplayParams`
|
|
1416
|
+
- Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
|
|
1417
|
+
|
|
1418
|
+
| Status | Error class | Codes | When |
|
|
1419
|
+
|---|---|---|---|
|
|
1420
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `event_id` is not `evt_<uuid>`, or `endpoint_id` is not a UUID. |
|
|
1421
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1422
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1423
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_EVENT_NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such event here (`WEBHOOK_EVENT_NOT_FOUND`); events are kept for 30 days. Or No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
|
|
1424
|
+
| 409 | `ConflictError` | `CONFLICT`, `WEBHOOK_ENDPOINT_NOT_SUBSCRIBED`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `endpoint_id` is switched off or does not receive this event type (`WEBHOOK_ENDPOINT_NOT_SUBSCRIBED`), or Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
|
|
1425
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1426
|
+
|
|
1427
|
+
```ts
|
|
1428
|
+
const webhookEventReplay = await flags.webhooks.events.replay("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
|
|
1429
|
+
```
|
|
1430
|
+
|
|
1431
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#post-v1-workspaces-workspace-id-webhooks-events-event-id-replay)
|
|
1432
|
+
|
|
1433
|
+
### `flags.webhooks.events.retrieve(eventId, options?)`
|
|
1434
|
+
|
|
1435
|
+
`GET /v1/workspaces/{workspace_id}/webhooks/events/{event_id}` → `Flags.WebhookEventDetail`
|
|
1436
|
+
|
|
1437
|
+
Get one webhook event with every delivery attempt.
|
|
1438
|
+
|
|
1439
|
+
The event as it was sent (`type`, `data`) and every delivery attempt to every endpoint, with its trigger, HTTP status, error and the start of the response body. Use it to debug a receiver, then `replay` to send it again.
|
|
1440
|
+
|
|
1441
|
+
| Status | Error class | Codes | When |
|
|
1442
|
+
|---|---|---|---|
|
|
1443
|
+
| 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `event_id` is not `evt_<uuid>`. |
|
|
1444
|
+
| 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
|
|
1445
|
+
| 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
|
|
1446
|
+
| 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_EVENT_NOT_FOUND` | No such event here (`WEBHOOK_EVENT_NOT_FOUND`); events are kept for 30 days. |
|
|
1447
|
+
| 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
|
|
1448
|
+
|
|
1449
|
+
```ts
|
|
1450
|
+
const webhookEventDetail = await flags.webhooks.events.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
|
|
1451
|
+
```
|
|
1452
|
+
|
|
1453
|
+
[HTTP reference](https://productcraft.co/docs/flags/api-reference#get-v1-workspaces-workspace-id-webhooks-events-event-id)
|
|
1454
|
+
|
|
1455
|
+
## Error codes
|
|
1456
|
+
|
|
1457
|
+
`err.code` on an `APIError` is one of these (an open set: new codes may appear).
|
|
1458
|
+
|
|
1459
|
+
| Code | Meaning |
|
|
1460
|
+
|---|---|
|
|
1461
|
+
| `BAD_REQUEST` | The request is malformed (not valid JSON, a bad header, an unusable parameter). |
|
|
1462
|
+
| `VALIDATION_ERROR` | One or more request fields are invalid; `errors` lists each field (`param`, `message`, `code`). |
|
|
1463
|
+
| `UNAUTHORIZED` | No credentials, or the token or API key is invalid, expired or revoked. |
|
|
1464
|
+
| `PAYMENT_REQUIRED` | The workspace has no credit or plan for this operation. |
|
|
1465
|
+
| `FORBIDDEN` | The caller is authenticated but not allowed to do this. |
|
|
1466
|
+
| `NOT_FOUND` | The resource does not exist, or belongs to another workspace or app. |
|
|
1467
|
+
| `METHOD_NOT_ALLOWED` | The route does not accept this HTTP method. |
|
|
1468
|
+
| `NOT_ACCEPTABLE` | The route cannot produce the requested content type. |
|
|
1469
|
+
| `REQUEST_TIMEOUT` | The request took too long to arrive. |
|
|
1470
|
+
| `CONFLICT` | The request conflicts with the current state of the resource. |
|
|
1471
|
+
| `GONE` | The resource existed but has been removed for good. |
|
|
1472
|
+
| `PRECONDITION_FAILED` | A precondition header did not match. |
|
|
1473
|
+
| `PAYLOAD_TOO_LARGE` | The request body is over the size limit. |
|
|
1474
|
+
| `UNSUPPORTED_MEDIA_TYPE` | The request body is not in a content type the route accepts. |
|
|
1475
|
+
| `UNPROCESSABLE_ENTITY` | The request is well-formed but cannot be carried out. |
|
|
1476
|
+
| `PRECONDITION_REQUIRED` | The route requires a precondition header. |
|
|
1477
|
+
| `RATE_LIMITED` | Too many requests; retry after the `Retry-After` header. |
|
|
1478
|
+
| `INTERNAL_SERVER_ERROR` | An unexpected server error. Retrying is safe for idempotent requests; quote `request_id` to support. |
|
|
1479
|
+
| `NOT_IMPLEMENTED` | The server does not support this operation. |
|
|
1480
|
+
| `BAD_GATEWAY` | An upstream service returned an invalid response. |
|
|
1481
|
+
| `SERVICE_UNAVAILABLE` | The service or one of its dependencies is temporarily unavailable; retry. |
|
|
1482
|
+
| `GATEWAY_TIMEOUT` | An upstream service did not answer in time; retry. |
|
|
1483
|
+
| `SERVICE_NOT_ENABLED` | The workspace has not enabled this product. |
|
|
1484
|
+
| `INVALID_CREDENTIALS` | The credentials were not accepted. |
|
|
1485
|
+
| `SESSION_REVOKED` | The session behind this token was signed out or revoked. |
|
|
1486
|
+
| `MCP_NOT_PERMITTED` | An MCP (agent) token cannot call this route. |
|
|
1487
|
+
| `MCP_WORKSPACE_MISMATCH` | The MCP token was issued for a different workspace. |
|
|
1488
|
+
| `PAK_NOT_PERMITTED` | A workspace API key cannot call this route. |
|
|
1489
|
+
| `ACTIONS_NOT_GRANTABLE` | The policy grants actions the caller does not hold. |
|
|
1490
|
+
| `IDEMPOTENCY_KEY_REUSE` | The `Idempotency-Key` was already used with a different body or route. |
|
|
1491
|
+
| `IDEMPOTENCY_KEY_REQUIRED` | This operation requires an `Idempotency-Key` header. |
|
|
1492
|
+
| `IDEMPOTENCY_IN_PROGRESS` | A request with the same `Idempotency-Key` is still running. Retry after `Retry-After` seconds with the same key to get its response. |
|
|
1493
|
+
| `WEBHOOK_ENDPOINT_LIMIT` | The workspace has the maximum number of webhook endpoints. |
|
|
1494
|
+
| `WEBHOOK_ENDPOINT_NOT_FOUND` | No webhook endpoint with this id in this workspace. |
|
|
1495
|
+
| `WEBHOOK_ENDPOINT_NOT_SUBSCRIBED` | The endpoint is not subscribed to this event type. |
|
|
1496
|
+
| `WEBHOOK_EVENT_NOT_FOUND` | No webhook event with this id in this workspace. |
|
|
1497
|
+
| `WEBHOOK_EVENT_TYPE_UNKNOWN` | The event type is not one this product sends. |
|
|
1498
|
+
| `PROJECT_NOT_FOUND` | The project does not exist in this workspace. |
|
|
1499
|
+
| `ENVIRONMENT_NOT_FOUND` | The environment does not exist in this project. |
|
|
1500
|
+
| `CONFIG_NOT_FOUND` | The config does not exist in this workspace. |
|
|
1501
|
+
| `SETTING_NOT_FOUND` | The feature flag or setting does not exist in this workspace. |
|
|
1502
|
+
| `SEGMENT_NOT_FOUND` | The segment does not exist in this workspace. |
|
|
1503
|
+
| `CHANGE_NOT_FOUND` | The change does not exist in this workspace. |
|
|
1504
|
+
| `REVISION_NOT_FOUND` | The config revision does not exist for this environment. |
|
|
1505
|
+
| `SDK_KEY_NOT_FOUND` | The SDK key is unknown, revoked or expired. |
|
|
1506
|
+
| `KEY_ALREADY_EXISTS` | Another resource in the same scope already uses this key. |
|
|
1507
|
+
| `LAST_ENVIRONMENT` | A project needs at least one environment; this is the last one. |
|
|
1508
|
+
| `VERSION_CONFLICT` | The resource changed since you read it; reload and apply your change again. |
|
|
1509
|
+
| `SETTING_IN_USE` | Another setting uses this one as a prerequisite. |
|
|
1510
|
+
| `SEGMENT_IN_USE` | A targeting rule uses this segment. |
|
|
1511
|
+
| `CIRCULAR_PREREQUISITE` | The prerequisite would create a cycle between settings. |
|
|
1512
|
+
| `PREREQUISITE_NOT_FOUND` | The prerequisite setting does not exist in this config. |
|
|
1513
|
+
| `PREREQUISITE_TYPE_MISMATCH` | The comparison value does not match the prerequisite setting's type. |
|
|
1514
|
+
| `INVALID_VALUE` | The value does not match the setting's type or exceeds its size limit. |
|
|
1515
|
+
| `INVALID_TARGETING` | The targeting rules are not valid. |
|
|
1516
|
+
| `PERCENTAGES_MUST_SUM_TO_100` | The percentage options must add up to 100. |
|
|
1517
|
+
| `CONFIG_TOO_LARGE` | The rendered config would exceed the maximum config size. |
|
|
1518
|
+
| `LIMIT_EXCEEDED` | The workspace has reached a Flags limit. |
|
|
1519
|
+
| `CONFIRMATION_REQUIRED` | The request needs an explicit confirmation parameter. |
|
|
1520
|
+
| `NOTE_REQUIRED` | This environment requires a change note. |
|
|
1521
|
+
| `CONFIDENTIAL_LIST_NOT_EDITABLE` | The confidential list was sent pre-hashed, so it has no cleartext to edit, re-hash or reveal; send the full list instead. |
|
|
1522
|
+
| `REVERT_NOT_SUPPORTED` | This kind of change cannot be restored. |
|
|
1523
|
+
| `NOTHING_TO_RESTORE` | The entity already matches the version before this change. |
|
|
1524
|
+
| `EVALUATION_BUDGET_EXCEEDED` | The test evaluation ran over its time budget. |
|
|
1525
|
+
| `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable; SDK config delivery keeps serving. |
|
|
1526
|
+
| `IMPORT_CREDENTIALS_INVALID` | ConfigCat rejected the import credentials. |
|
|
1527
|
+
| `IMPORT_SOURCE_UNAVAILABLE` | The ConfigCat API could not be reached. |
|
|
1528
|
+
| `IMPORT_SOURCE_NOT_FOUND` | The ConfigCat product does not exist or the credentials cannot see it. |
|
|
1529
|
+
| `IMPORT_UNSUPPORTED` | The ConfigCat product uses features Flags cannot import; see details.items. |
|
|
1530
|
+
| `IMPORT_EXCEEDS_LIMITS` | The ConfigCat product is larger than the Flags workspace limits. |
|
|
1531
|
+
| `OWNER_NOT_A_MEMBER` | The owner_id is not a member of this workspace, or membership could not be checked with this credential. |
|
|
1532
|
+
| `SETTING_TYPE_IMMUTABLE` | A setting's type cannot change; create a new setting instead. |
|