About the Agent Management API

The Agent Management API allows you to programmatically configure, manage, and monitor your NXLog Agent fleet. You can use it to integrate with third-party systems such as Software Configuration Management (SCM) and network and application monitoring tools.

API concepts and terminology

The following are concepts and terms you will come across in this documentation.

Entities

The API implements three entity types:

Agent: Represents NXLog Agent instances managed from NXLog Platform. Agent endpoints are available at /api/v1/agents/*.
Configuration template: NXLog Agent configurations that you assign to agent instances. Configuration template endpoints are available at /api/v1/templates/*.
Enrollment rules: Policies for automatically enrolling NXLog Agent instances to NXLog Platform. Enrollment rules endpoints are available at /api/v1/enroll-rules/*.

The Agent Management API assigns each entity a UUID on creation, which you can then use to request information about or perform actions on the specific entity.

Fields

The properties of an entity; for example, hostname for an agent instance or priority for an enrollment rule. The API provides endpoints to retrieve, set, and delete properties.

MQL

The querying language used for filtering agents, configuration templates, and enrollment rules.

Single-entity request

An API request for a specific entity identified by its UUID.

Multi-entity request

An API request for multiple entities of the same type.

API endpoints

Agent Management API endpoints are in the form /api/v1/{ENTITY_TYPE}/{ENTITY_UUID|*}/{DATA_PATH}, where:

{ENTITY_TYPE} is either agents, templates, or enroll-rules.
{ENTITY_UUID|*} is either an entity UUID or * to select all entities of this type.
{DATA_PATH} is the path to an object, field, or a POST command, such as enroll or certificate/renew for agent entities.

Requests to the API

The Agent Management API uses various HTTP methods according to the endpoint functionality. Depending on the request type, you might need to specify request headers or body parameters. The API responds to each request with an appropriate HTTP status code, and the response may include text, JSON, or NDJSON content.

HTTP methods

The HTTP method of an endpoint depends on the type of operation it performs on the entity. The Agent Management API strives to use the most appropriate method for each operation.

Table 1. Available HTTP methods
Header	Description
GET	Used for listing entities. Single-entity requests return a value. The value type depends on the request. For example, a string when getting the value of an agent field or a JSON object when getting the agent status. Multi-entity requests return a JSON array of values, such as strings or objects.
POST	Used for creating new entities, such as configuration templates or enrollment rules.
PUT	Used for modifying fields.
PATCH	Used for modifying and deleting multiple fields at once. Patch requests require a JSON object containing the fields and values to update. Set a field’s value to null to delete it.
DELETE	Used for deleting an entity or field.

HTTP request headers

The table below lists the required headers when making Agent Management API requests.

Table 2. Required HTTP request headers
Header	Description
Authorization	This header is used for authentication and must contain a valid Personal Access Token (PAT). It is required for all requests except `/api/v1/version`. See Agent Management API authentication for more information.
Accept	This header is required for multi-entity requests and must contain one of the following values: / Defaults to `application/x-json`. application/x-json Requests content as a JSON array. application/x-ndjson Requests content in NDJSON (Newline Delimited JSON) format. Any other value returns an `HTTP/1.1 406 Not Acceptable` status.

Response codes

Every request returns an HTTP/1.1 status code indicating whether the server processed it successfully. The following table lists the most common response codes.

Table 3. HTTP status codes summary
Code	Status	Description
200	OK	The server processed the request successfully and included any expected data in the response.
204	No Content	The server processed the request successfully and does not need to return any data.
400	Bad Request	The server cannot process the request because it is malformed or has incorrect parameters.
401	Unauthorized	Authentication failed or was not provided.
404	Not Found	The specified entity or field is unknown. If the entity is an agent, it can also be that it’s unreachable, but a connection is required for the operation.
405	Method Not Allowed	The HTTP method is incorrect for this endpoint. For example, if you make a `GET` request to an endpoint that supports `POST` only.
406	Not Acceptable	The specified `Accept` header is incompatible with the request type, or the header is missing.
409	Conflict	The server received simultaneous conflicting requests and rejected the request.
428	Precondition Required	The server cannot perform the requested operation on the specified entity because the necessary preconditions are not met.
500	Internal Server Error	An unexpected error occurred on the server or agent.
504	Gateway Timeout	The request timed out. If it’s an agent request, the server did not receive a timely response from the agent instance.