Sign in

v1

latestOpenAPI 3.0.0Elastic License 2.02026-07-1791851.7 KB

The agent checkin endpoint. Clients will long-poll this endpoint. A client may inform fleet-server of it's long-poll timeout in the request body. The fleet-server will return a response if there is a new action for the agent, or if the polling timeout is reached. The fleet-server may also use some jitter to offset the polling timeout, if specified a random amount of the jitter value may be subtracted from the polling timeout. The fleet-sever polling timeout is short-circuited in cases of heavy load where setting up the checkin (ensuring the API key is authed etc) takes longer then the timeout value. Fleet-server sets the poll timeout to 5m by default (with a 10m write timeout), for these values we assume that elastic-agent's request timeout is set to 10m and the cloud-proxy's timeout is longer than 10m.

post/api/fleet/agents/{id}/checkin

Path parameters

idstring required

The agent ID.

Headers

Accept-Encodingstring

If the agent is able to accept encoded responses. Used to indicate if GZIP compression may be used by the server. The elastic-agent does not use the accept-encoding header.

User-Agentstring required

The user-agent header that is sent. Must have the format "elastic agent X.Y.Z" where "X.Y.Z" indicates the agent version. The agent version must not be greater than the version of the fleet-server.

X-Request-Idstring

The request tracking ID for APM.

Elastic-Api-Versionstring

The API version to use, format should be "YYYY-MM-DD"

Request body

status'online' | 'error' | 'degraded' | 'starting' required

The agent state, inferred from agent control protocol states.

messagestring required

State message, may be overridden or use the error message of a failing component.

ack_tokenstring

The ack_token form a previous response if the agent has checked in before. Translated to a sequence number in fleet-server in order to retrieve any new actions for the agent from the last checkin.

local_metadatastring application/json

An embedded JSON object that holds meta-data values. Defined in fleet-server as a json.RawMessage, defined as an object in the elastic-agent. elastic-agent will populate the object with information from the binary and host/system environment. fleet-server will update the agent record if a checkin response contains different data from the record.

componentsstring application/json

An embedded JSON object that holds component information that the agent is running. Defined in fleet-server as a json.RawMessage, defined as an object in the elastic-agent. fleet-server will update the components in an agent record if they differ from this object.

poll_timeoutstring duration

An optional timeout value that informs fleet-server of when a client will time out on it's checkin request. If not specified fleet-server will use the timeout values specified in the config (defaults to 5m polling and a 10m write timeout). The value, if specified is expected to be a string that is parsable by time.ParseDuration. If specified fleet-server will set its poll timeout to max(1m, poll_timeout-2m) and its write timeout to max(2m, poll_timout-1m).

Response

Agent checkin successful. May include actions.

ack_tokenstring

The acknowlegment token used to indicate action delivery.

actionstring required

The action result. Set to "checkin".