52bf0279Scheduled Wake-ups#
| Property | Value |
|---|---|
| Service | crossfire |
| Operation | wakeRules |
| Method | GET |
| Path | /api/wake-rules |
| Authentication | human |
| Success status | 200 |
| Response data | Paginated collection |
| Request format | json |
| Maximum request body | 2097152 bytes (service default) |
| Permission codes | wake-rule.read.owned, wake-rule.read.any |
Listed permission codes are alternatives, not token scopes. The service also checks access to the requested records and rejects stale revisions or controller generations.
Path parameters#
empty object; unknown fields rejected
Validation#
check.emptyReferenced definitions:
Query parameters#
custom validation:
fleets
; see function below
Accepted query parameters: ownerId, search.
Query parameters are URL text. The validation function below specifies their format, defaults and combinations. Pagination applies only to operations that use it.
Additional checks#
The following checks apply in addition to the field limits.
Constraint on value:
export function fleets(input: unknown) {
const parsed = checked(input, ['ownerId', 'search']);
if (!parsed.ok)
return parsed;
const params = new URLSearchParams(parsed.value), search = params.get('search') ?? '';
params.delete('search');
if (!check.text(200, 0)(search).ok)
return failure('invalid', 'Invalid search');
const scope = scoped(params);
return scope.ok ? success({ ...scope.value, search }) : scope;
}Validation#
query.fleetsReferenced definitions:
Request body#
empty object; unknown fields rejected
Validation#
check.emptyReferenced definitions:
Response data#
array; 0–100 entries; item: object; fields below; unknown fields rejected (
wakeRuleSummary
)
| Field path | Representation and constraints |
|---|---|
[].ruleId | lowercase opaque UUID |
[].owner | object; fields below; unknown fields rejected (
principal
) |
[].owner.principalId | lowercase opaque UUID |
[].owner.matrixUserId | well-formed Matrix user ID; maximum 255 UTF-16 units |
[].owner.kind | human or agent |
[].owner.displayName | string; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls |
[].owner.ownerId | lowercase opaque UUID |
[].owner.ownerMatrixId | well-formed Matrix user ID; maximum 255 UTF-16 units |
[].configuredById | lowercase opaque UUID |
[].name | string; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls; constraint: Provide a Wake-up name (
name
) |
[].message | plain-text string; at most 16384 UTF-8 bytes; allowed whitespace controls only; constraint: Provide a wake-up message (
message
) |
[].schedule | custom validation:
wakeSchedule
; see function below |
[].schedule.kind (parser branch 1) | interval |
[].schedule.seconds (parser branch 1) | exact JSON integer; 1…31536000 |
[].schedule.kind (parser branch 2) | cron |
[].schedule.expression (parser branch 2) | string; 1–200 UTF-16 units; well-formed Unicode; no C0/DEL controls |
[].schedule.timeZone (parser branch 2) | string; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls |
[].enabled | boolean |
[].revision | exact JSON integer; 0…9007199254740991 |
[].createdAt | exact JSON integer; 0…9007199254740991 |
[].updatedAt | exact JSON integer; 0…9007199254740991 |
[].agentCount | exact JSON integer; 0…1000 |
[].nextDueAt | exact JSON integer; 0…9007199254740991; JSON null permitted |
[].lastDeliveredAt | exact JSON integer; 0…9007199254740991; JSON null permitted |
Additional checks#
The following checks apply in addition to the field limits.
Constraint on [].message:
value => !!value.trim()Constraint on [].schedule:
input => {
if (!input || typeof input !== 'object' || !('kind' in input))
return failure('invalid', 'Choose an interval or calendar schedule');
if (input.kind === 'interval')
return check.object({ kind: check.choice('interval'), seconds: check.integer(1, 31536000) })(input);
if (input.kind === 'cron')
return check.object({ kind: check.choice('cron'), expression: check.text(200), timeZone: check.text(100) })(input);
return failure('invalid', 'Unknown schedule kind');
}Validation#
check.list(wake.wakeRuleSummary, 100)Referenced definitions:
Response envelope#
A successful JSON response contains data and meta. Replace the data placeholder below with the response fields described above. Errors contain error instead of data.
{
"data": "<value matching the response-data validator>",
"meta": {
"requestId": "00000000-0000-0000-0000-000000000001",
"page": 1,
"pageSize": 20,
"totalItems": 0,
"totalPages": 1
}
}