GET /api/diagnostics

Read bounded diagnostics without starting sessions, refreshing credentials or repairing state#

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

Send exactly one Authorization: Bearer <authenticationKey> header. fleet reads the key from private OS-native ctlflow/fleetd.json; it does not create or replace it. Missing or incorrect credentials return 401, including for status. Browser Origin and Cookie headers are rejected, even when empty.

• Controller authentication, paths and recovery

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#

Your HTTP client substitutes these values into the placeholders in the URL path.

empty object; unknown fields rejected

Validation#

This TypeScript is the server’s validation code, reproduced from its contract. It describes the accepted format; client applications do not need to run or import it.

check.empty

Referenced definitions:

• empty

Query parameters#

Your HTTP client supplies these values in the URL query string.

custom validation: diagnosticQuery ; see function below

Accepted query parameters: fleetId, instanceKey.

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 diagnosticQuery(input: unknown) {
    if (!(input instanceof URLSearchParams) || [...input.keys()].some(key => !['fleetId', 'instanceKey'].includes(key))
        || input.getAll('fleetId').length > 1 || input.getAll('instanceKey').length > 1)
        return failure('invalid', 'Use one exact diagnostic scope');
    const parsed = scope({ fleetId: input.get('fleetId'), instanceKey: input.get('instanceKey') });
    return parsed.ok && parsed.value.instanceKey !== null && parsed.value.fleetId === null ? failure('invalid', 'An instance requires a fleet') : parsed;
}

Validation#

This TypeScript is the server’s validation code, reproduced from its contract. It describes the accepted format; client applications do not need to run or import it.

diagnosticQuery

Referenced definitions:

• diagnosticQuery

Request body#

Your HTTP client supplies these fields as the JSON request body when the operation takes input. A no-input operation does not require JSON. This is protocol input, not text to send in a Matrix room.

empty object; unknown fields rejected

Validation#

This TypeScript is the server’s validation code, reproduced from its contract. It describes the accepted format; client applications do not need to run or import it.

check.empty

Referenced definitions:

• empty

Response data#

The service produces these fields inside data in its response. They are output for the client to read, not input for the caller to submit.

object; fields below; unknown fields rejected ( diagnosticReport )

Validation#

This TypeScript is the server’s validation code, reproduced from its contract. It describes the accepted format; client applications do not need to run or import it.

diagnosticReport

Referenced definitions:

• diagnosticReport

Response envelope#

This JSON illustrates a response returned by the service, not a request to send. The service fills data with the operation result and meta with request metadata. The string below marks where the actual response data appears; it is not an example record. Errors contain error instead of data.

{
  "data": "<value matching the response-data validator>",
  "meta": {
    "requestId": "00000000-0000-0000-0000-000000000001"
  }
}