POST /api/wake-rules

Generated from services/crossfire/node/packages/contracts/src/rest/operations.ts at 52bf0279

Create a scheduled Wake-up#

Property	Value
Service	`crossfire`
Operation	`createWakeRule`
Method	`POST`
Path	`/api/wake-rules`
Authentication	`human`
Success status	`201`
Response data	Unpaginated value
Request format	`json`
Maximum request body	2097152 bytes (service default)
Permission codes	`wake-rule.manage.owned`

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.empty

Referenced definitions:

empty

Query parameters#

custom validation: none ; see function below

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 none(input: unknown) {
    const parsed = listQuery([])(input);
    return parsed.ok ? success({}) : parsed;
}

Validation#

query.none

Referenced definitions:

none

Request body#

object; fields below; unknown fields rejected ( wakeRuleCreation )

Field path	Representation and constraints
`ruleId`	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
`agentIds`	array; 0–1000 entries; item: lowercase opaque UUID; constraint: Duplicate attached agents ( `agentIds` )

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');
}

Constraint on agentIds:

ids => new Set(ids).size === ids.length

Validation#

wake.wakeRuleCreation

Referenced definitions:

wakeRuleCreation

Response data#

object; fields below; unknown fields rejected ( wakeRuleDetails )

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
`agents`	array; 0–1000 entries; item: object; fields below; unknown fields rejected ( `wakeRuleAgent` )
`agents[].principalId`	lowercase opaque UUID
`agents[].matrixUserId`	well-formed Matrix user ID; maximum 255 UTF-16 units
`agents[].kind`	`agent`
`agents[].displayName`	string; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls
`agents[].ownerId`	lowercase opaque UUID
`agents[].ownerMatrixId`	well-formed Matrix user ID; maximum 255 UTF-16 units
`agents[].ruleId`	lowercase opaque UUID
`agents[].agentId`	lowercase opaque UUID
`agents[].nextDueAt`	exact JSON integer; 0…9007199254740991
`agents[].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#

wake.wakeRuleDetails

Referenced definitions:

wakeRuleDetails

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 source Source revisions