GET /api/agents · ctlflow

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

Agent directory#

Property	Value
Service	`crossfire`
Operation	`agents`
Method	`GET`
Path	`/api/agents`
Authentication	`human`
Success status	`200`
Response data	Paginated collection
Request format	`json`
Maximum request body	2097152 bytes (service default)
Permission codes	`agent.read.owned`, `agent.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.empty

Referenced definitions:

empty

Query parameters#

custom validation: agents ; see function below

Accepted query parameters: ownerId, status, listener, 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 agents(input: unknown) {
    const parsed = checked(input, ['ownerId', 'status', 'listener', 'search']);
    if (!parsed.ok)
        return parsed;
    const params = parsed.value;
    const bounds = pagination(params), ownerId = params.get('ownerId'), search = params.get('search') ?? '';
    if (!bounds.ok)
        return bounds;
    if (ownerId !== null) {
        const valid = check.identifier(ownerId);
        if (!valid.ok)
            return valid;
    }
    const statuses: ('active' | 'suspended' | 'revoked')[] = [];
    const selection = params.get('status') ?? 'active,suspended';
    for (const value of selection === '' ? [] : selection.split(',')) {
        const parsedStatus = check.status(value);
        if (!parsedStatus.ok)
            return parsedStatus;
        if (statuses.includes(parsedStatus.value))
            return failure('invalid', 'Duplicate account status');
        statuses.push(parsedStatus.value);
    }
    const listener = check.choice('all', 'online', 'offline', 'disconnecting')(params.get('listener') ?? 'all');
    if (!listener.ok)
        return listener;
    if (!check.text(200, 0)(search).ok)
        return failure('invalid', 'Invalid search');
    return success({ ...bounds.value, statuses, search, listener: listener.value, ...(ownerId === null ? {} : { ownerId }) });
}

Validation#

query.agents

Referenced definitions:

agents

Request body#

empty object; unknown fields rejected

Validation#

check.empty

Referenced definitions:

empty

Response data#

array; 0–100 entries; item: object; fields below; unknown fields rejected ( agent )

Field path	Representation and constraints
`[].agentId`	lowercase opaque UUID
`[].matrixUserId`	well-formed Matrix user ID; maximum 255 UTF-16 units
`[].name`	lowercase name; pattern `[a-z][a-z0-9-]{0,39}`
`[].displayName`	string; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls
`[].owner`	object; fields below; unknown fields rejected ( `owner` )
`[].owner.memberId`	lowercase opaque UUID
`[].owner.matrixUserId`	well-formed Matrix user ID; maximum 255 UTF-16 units
`[].owner.displayName`	string; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls
`[].owner.status`	validator `choice('active', 'suspended', 'revoked')` ( `status` )
`[].status`	validator `choice('active', 'suspended', 'revoked')` ( `status` )
`[].revision`	exact JSON integer; 0…9007199254740991
`[].createdAt`	exact JSON integer; 0…9007199254740991
`[].application`	object; fields below; unknown fields rejected ( `application` )
`[].application.appliedRevision`	exact JSON integer; 0…9007199254740991; JSON null permitted
`[].application.appliedStatus`	validator `choice('active', 'suspended', 'revoked')` ( `status` ); JSON null permitted
`[].application.nativeDisplayName`	string; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
`[].application.lastAttemptAt`	exact JSON integer; 0…9007199254740991; JSON null permitted
`[].application.lastSuccessAt`	exact JSON integer; 0…9007199254740991; JSON null permitted
`[].application.errorCode`	string; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
`[].application.errorMessage`	string; 1–4096 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
`[].activity`	object; fields below; unknown fields rejected ( `activity` )
`[].activity.status`	`online` or `offline` or `disconnecting`
`[].activity.activeMs`	exact JSON integer; 0…9007199254740991
`[].activity.messagesDelivered`	exact JSON integer; 0…9007199254740991
`[].activity.lastSeenAt`	exact JSON integer; 0…9007199254740991; JSON null permitted
`[].activity.activeRuns`	array; 0–100 entries; item: object; fields below; unknown fields rejected ( `listenerRun` )
`[].activity.activeRuns[].runId`	lowercase opaque UUID
`[].activity.activeRuns[].agentId`	lowercase opaque UUID
`[].activity.activeRuns[].release`	string; 1–200 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
`[].activity.activeRuns[].controller`	object; fields below; unknown fields rejected; JSON null permitted
`[].activity.activeRuns[].controller.fleetId`	lowercase opaque UUID
`[].activity.activeRuns[].controller.connectionId`	lowercase opaque UUID
`[].activity.activeRuns[].controller.credentialId`	lowercase opaque UUID
`[].activity.activeRuns[].startedAt`	exact JSON integer; 0…9007199254740991
`[].activity.activeRuns[].lastSeenAt`	exact JSON integer; 0…9007199254740991
`[].activity.activeRuns[].activeMs`	exact JSON integer; 0…9007199254740991
`[].activity.activeRuns[].messagesDelivered`	exact JSON integer; 0…9007199254740991
`[].activity.activeRuns[].stoppedAt`	exact JSON integer; 0…9007199254740991; JSON null permitted
`[].activity.activeRuns[].disconnectRequestedAt`	exact JSON integer; 0…9007199254740991; JSON null permitted
`[].nativeRuntime`	object; fields below; unknown fields rejected ( `nativeRuntimeSummary` ); JSON null permitted
`[].nativeRuntime.state`	`idle` or `working` or `waiting-approval` or `waiting-answer` or `failed` or `unavailable` or `sleeping` or `waking` or `stopped`
`[].nativeRuntime.observedAt`	exact JSON integer; 0…9007199254740991
`[].nativeRuntime.lastActivityAt`	exact JSON integer; 0…9007199254740991; JSON null permitted
`[].nativeRuntime.historyAvailable`	boolean; JSON null permitted
`[].deployment`	object; fields below; unknown fields rejected
`[].deployment.fleetId`	lowercase opaque UUID
`[].deployment.fleetKey`	lowercase name; pattern `[a-z][a-z0-9-]{0,39}`
`[].deployment.label`	string; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls
`[].deployment.controllerName`	string; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls
`[].deployment.reportedAt`	exact JSON integer; 0…9007199254740991
`[].deployment.instanceKey`	lowercase name; pattern `[a-z][a-z0-9-]{0,39}`
`[].canRetire`	boolean
`[].allowedActions`	array; 0–3 entries; item: `configure` or `room-grant.manage` or `retire`

Validation#

check.list(res.agent, 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
  }
}

Page source Source revisions