GET /api/fleets

Registered fleets#

Private controller API. Call this route through the user’s Unix socket, locally or over SSH. It is not exposed on the server’s public origin.

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: page ; 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 page(input: unknown) {
    const parsed = checked(input, []);
    return parsed.ok ? pagination(parsed.value) : parsed;
}

Validation#

page

Referenced definitions:

• page

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

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[].instance.runtimeOptions:

(input: unknown): Result<Record<string, unknown>> => input && typeof input === 'object' && !Array.isArray(input) ? success(input as Record<string, unknown>) : failure('invalid', 'Expected runtime options')

Validation#

check.list(fleetView, 100)

Referenced definitions:

• list
• fleetView

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