POST /api/enrollments

Introduce exact roster#

Listed permission codes are alternatives, not token scopes. The service also checks access to the requested records and rejects stale revisions or controller generations.

• Authentication, envelopes and pagination
• Language-neutral client examples

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 ( enrollment )

Additional checks#

The following checks apply in addition to the field limits.

Constraint on controller.metadata:

function metadata(input: unknown): Result<Record<string, string>> {
    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length > 16)
        return failure('invalid', 'Controller metadata supports at most 16 text fields');
    const output: Record<string, string> = {};
    for (const [key, value] of Object.entries(input)) {
        if (!/^[a-z][a-z0-9-]{0,39}$/u.test(key) || !check.text(256, 0)(value).ok || typeof value !== 'string')
            return failure('invalid', 'Invalid controller metadata');
        output[key] = value;
    }
    return success(output);
}

Constraint on instances[].coordinationPolicy:

policy => (policy.wakeMode !== 'everyone' || policy.senders.length === 0)
    && new Set(policy.senders.map(sender => sender.matrixUserId)).size === policy.senders.length

Validation#

req.enrollment

Referenced definitions:

• enrollment

Response data#

object; fields below; unknown fields rejected ( enrollmentIntroduction )

Additional checks#

The following checks apply in addition to the field limits.

Constraint on enrollment.instances[].coordinationPolicy:

policy => (policy.wakeMode !== 'everyone' || policy.senders.length === 0)
    && new Set(policy.senders.map(sender => sender.matrixUserId)).size === policy.senders.length

Validation#

res.enrollmentIntroduction

Referenced definitions:

• enrollmentIntroduction

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"
  }
}