openapi: 3.0.3
info:
  title: NXLog Platform | Agent Management
  description: ''
  contact:
    name: NXLog Ltd.
  version: ${version}
tags:
  - name: agents
    description: Everything about agents
security:
  - basic_auth: []
  - bearer_auth: []
paths:
  /api/v1/agents/count:
    get:
      tags:
        - agents
      summary: Get agents count
      description: Returns agents count
      operationId: agent_count
      parameters:
        - $ref: '#/components/parameters/FilterParam'
      responses:
        '200':
          description: successful operation
          content:
            text/plain:
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadFilterRequest'
        '401':
          description: Unauthorized
  /api/v1/agents/*:
    get:
      tags:
        - agents
      summary: Get agents info
      description: Returns list of agent configurations
      operationId: multipleAgents
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/FieldsParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/FromUUIDParam'
        - $ref: '#/components/parameters/ToUUIDParam'
        - $ref: '#/components/parameters/AfterUUIDParam'
        - $ref: '#/components/parameters/BeforeUUIDParam'
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Agent'
              examples:
                agentsWithDefaultFields:
                  $ref: '#/components/examples/agentsWithDefaultFields'
                agentsWithIdAndStatusFields:
                  $ref: '#/components/examples/agentsWithIdAndStatusFields'
            application/zip:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/FieldNotFound'
        '406':
          description: Content-Type is not acceptable for this agent
        '501':
          description: Not implemented
  /api/v1/agents/*/{field}:
    get:
      tags:
        - agents
      operationId: singleField
      summary: Get list of extracted agent fields
      description: Query agents and extract a single field from the result item
      parameters:
        - $ref: '#/components/parameters/FieldParam'
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/FieldsParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/FromUUIDParam'
        - $ref: '#/components/parameters/ToUUIDParam'
        - $ref: '#/components/parameters/AfterUUIDParam'
        - $ref: '#/components/parameters/BeforeUUIDParam'
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/DistinctParam'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                stringField:
                  summary: list of IDs for field path parameter set to "id"
                  description: |
                    Example response for **fields** path parameter set to **id**.
                  value:
                    - "3b1d93d3-d711-11ee-8000-7dd31545780f"
                    - "422ebe80-d666-11ee-8039-353430613862"
                    - "527413ca-d73e-11ee-8024-656335653832"
                    - "76cf4b0c-d740-11ee-8089-353834643838"
                    - "ab12f990-d024-11ee-801e-656330623333"
                    - "d1694446-da51-11ee-8052-77313000d912"
                numberField:
                  summary: list of CPU load values for field path parameter set to "cpu-load"
                  description: |
                    Example response for **fields** path parameter set to **cpu-load**.
                  value:
                    - 0.66943359375
                    - 0.66943359375
                    - 0.66943359375
                    - 0.66943359375
                    - 0.66943359375
                    - 0.00151233130
                certificates:
                  $ref: '#/components/examples/agentCertificates'
                certificateSubjects:
                  $ref: '#/components/examples/agentCertificateSubjects'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/GetFieldNotFound'
        '501':
          description: Not implemented
          content:
            text/plain:
              schema:
                type: string
              examples:
                fieldNotImplemented:
                  summary: Field is not implemented
                  description: |
                    User entered **modules** into **field** path parameter
                  value: Not implemented. Try "/api/v1/agents/*?fields=modules" instead.

    put:
      tags:
        - agents
      operationId: change_agent_field
      summary: Change a field for a list of agents
      description: Changes field for a list of agents
      parameters:
        - $ref: '#/components/parameters/FieldParam'
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/FromUUIDParam'
        - $ref: '#/components/parameters/ToUUIDParam'
        - $ref: '#/components/parameters/AfterUUIDParam'
        - $ref: '#/components/parameters/BeforeUUIDParam'
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
      requestBody:
        required:
          true
        content:
          text/plain:
            schema:
              type: string
            examples:
              setAgentConfig:
                $ref: '#/components/examples/setAgentConfig'
              setComment:
                $ref: '#/components/examples/setCommentText'
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              updateComment:
                summary: Add comment to agent info
                value:
                  {
                    "comment": "Agent 007"
                  }
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '204':
          description: successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          $ref: '#/components/responses/PutFieldNotFound'
    delete:
      tags:
        - agents
      summary: Removes field for multiple agents
      description: Removes field for multiple agents
      parameters:
        - $ref: '#/components/parameters/FieldParam'
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/FromUUIDParam'
        - $ref: '#/components/parameters/ToUUIDParam'
        - $ref: '#/components/parameters/AfterUUIDParam'
        - $ref: '#/components/parameters/BeforeUUIDParam'
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '204':
          description: successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/DeleteFieldNotFound'
  /api/v1/agents/{id}:
    get:
      tags:
        - agents
      summary: Get agent by ID
      description: Returns an agent data for a given ID
      operationId: single
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Agent'
              examples:
                agentSingleWithDefaultFields:
                  $ref: '#/components/examples/agentSingleWithDefaultFields'
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /api/v1/agents/{id}/{field}:
    get:
      tags:
        - agents
      summary: Get agent field
      description: Returns an agent field for a given agent ID
      operationId: singleAgentField
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/FieldParam'
        - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: successful operation
          content:
            text/plain:
              schema:
                type: string
              examples:
                agentSingleWithSingleField:
                  $ref: '#/components/examples/agentSingleWithSingleField'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/FieldNotFound'
    put:
      tags:
        - agents
      summary: Change agent field
      description: Changes agent field
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/FieldParam'
      requestBody:
        required:
          true
        content:
          text/plain:
            schema:
              type: string
            examples:
              setAgentConfig:
                $ref: '#/components/examples/setAgentConfig'
              setComment:
                $ref: '#/components/examples/setCommentText'
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
      responses:
        '204':
          description: successful operation
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/PutFieldNotFound'

    delete:
      tags:
        - agents
      summary: Removes agent field
      description: Removes field from an agents
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/FieldParam'
      responses:
        '204':
          description: successful operation
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/DeleteFieldNotFound'
  /api/v1/agents/{id}/enroll:
    post:
      tags:
        - agents
        - actions
      summary: Enroll an agent
      description: Enrolls an agent with the given ID using the provided enrollment details.
      operationId: enrollAgent
      parameters:
        - name: id
          in: path
          required: true
          description: Agent ID or `*` to select all
          schema:
            type: string
        - $ref: '#/components/parameters/FilterParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Enrollment'
            examples:
              withConnection:
                summary: Basic enrollment
                value:
                  connection: 
                    mode: "connect"
                    address: "{{agents_endpoint}}"
              byTemplate:
                summary: Template-based enrollment
                description: A minimal example to enroll by template.
                value:
                  templateId: "923c16cd-ed93-43e7-9b3a-bb84d22b1998"
              withCertificateAndTemplate:
                summary: Template-based with certificate
                value:
                  certificate:
                    commonName: "agent"
                    country: "US"
                    state: "CA"
                    locality: "San-Francisco"
                    organization: "NXLog"
                    organizationUnit: "Dev"
                    notBefore: "20200101000000Z"
                    notAfter: "20201231235959Z"
                    serial: 128
                    encryptKey: true
                    isCa: true
                  templateId: "923c16cd-ed93-43e7-9b3a-bb84d22b1998"
      responses:
        '200':
          description: Enrollment results of a group of agents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '204':
          description: Successful enrollment of a single agent
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '400':
          description: Bad request
          content:
            test/plain:
              schema:
                type: string
              examples:
                wrongMode:
                  summary: Incorrect mode
                  description: Incorrect **mode** parameter. This example tries to use not existing **disconnect** mode.
                  value: unknown variant `disconnect`, expected `connect` or `listen` at line 3 column 24
        '404':
          description: Agent not found
  /api/v1/templates/count:
    get:
      tags:
        - templates
      summary: Get templates count
      description: Returns templates count
      operationId: templates_count
      parameters:
        - $ref: '#/components/parameters/FilterParam'
      responses:
        '200':
          description: successful operation
          content:
            text/plain:
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadFilterRequest'
        '401':
          description: Unauthorized
  /api/v1/templates:
    post:
      tags:
        - templates
      summary: Create template
      description: Creates new template.
      operationId: createTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Template'
            examples:
              createWithConfig:
                summary: Create template with configuration
                value:
                  {
                    "name": "foo1",
                    "content": "<Extension admin>\nModule xm_admin\n</Extension>\n"
                  }
              createWithParts:
                summary: Create template based on parts
                description: Create template based on parts of existing templates
                value:
                  {
                    "name": "foo2",
                    "parts": ["da117b31-07a0-4a38-b028-f57ef1828d19", "c67dc5e4-2922-4443-9081-a52e432fa026"]
                  }
      responses:
        '200':
          description: successfully created template
          content:
            text/plain:
              schema:
                type: string
                format: uuid
                description: UUID of the created template
        '401':
          description: Unauthorized
  /api/v1/templates/*:
    get:
      tags:
        - templates
      summary: List templates
      description: List registered templates
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Template'
              examples:
                templateList:
                  $ref: '#/components/examples/templateList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
    patch:
      tags:
        - templates
      summary: Update templates
      description: Update templates
      parameters:
        - $ref: '#/components/parameters/FilterParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              setComment:
                $ref: '#/components/examples/setCommentJSON'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
    delete:
      tags:
        - templates
      summary: Delete multiple templates
      description: Delete multiple templates at once
      parameters:
        - $ref: '#/components/parameters/FilterParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
  /api/v1/templates/*/{field}:
    get:
      tags:
        - templates
      summary: List of templates fields
      description: List of extracted specified field of each template
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/TemplateFieldParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                idList:
                  $ref: '#/components/examples/idList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
    put:
      tags:
        - templates
      summary: Change specified field for multiple templates
      description: Changes specified field for multiple templates
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/TemplateFieldParam'
      requestBody:
        required:
          true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              setTags:
                summary: set array field
                description: Sets array field. For example use it with **tags** for **fields** path parameter.
                value:
                  [
                    "foo",
                    "bar"
                  ]
              setString:
                summary: set string field
                description: Sets string field. For example us it with **comment** for **fields** path parameter.
                value: "foo"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
    delete:
      tags:
        - templates
      summary: Removes or clears specified field for multiple templates
      description: Removes or clears specified field for multiple templates
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/TemplateFieldParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '404':
          description: Failure
          content:
            text/plain:
              schema:
                type: string
                example: >
                  specified field cannot be used in `DELETE` requests; path: comment
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
  /api/v1/templates/{id}:
    get:
      tags:
        - templates
      summary: Get template
      description: Get template configuration.
      operationId: getTemplate
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Template'
              examples:
                singleTemplate:
                  summary: Single template
                  $ref: '#/components/examples/templateSingle'
        '400':
          $ref: '#/components/responses/GetFieldNotFound'
        '401':
          description: Unauthorized
    patch:
      tags:
        - templates
      summary: Change template
      description: Change template by id
      operationId: updateTemplate
      parameters:
        - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              setComment:
                $ref: '#/components/examples/setCommentJSON'
      responses:
        '204':
          description: Success
        '401':
          description: Unauthorized
        '404':
          description: Not found
    delete:
      tags:
        - templates
      summary: Deletes template
      description: Deletes enroll rule by id
      operationId: deleteTemplate
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '204':
          description: Success
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /api/v1/templates/{id}/{field}:
    get:
      tags:
        - templates
      summary: Get a single template field
      description: This operation retrieves a single template field.
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/TemplateFieldParam'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string
              examples:
                templateContent:
                  $ref: '#/components/examples/templateContent'
        '400':
          $ref: '#/components/responses/GetFieldNotFound'
        '401':
          description: Unauthorized
        '406':
          description: Not acceptable
    put:
      tags:
        - templates
      summary: Change specified template field
      description: Changes specified template field
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/TemplateFieldParam'
      requestBody:
        required:
          true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              setArray:
                summary: set array field
                description: Sets array field. For example use it with **tags** for **fields** path parameter.
                value:
                  [
                    "foo",
                    "bar"
                  ]
              setComment:
                summary: set string field
                description: Set any string field. For example use it with **comment** as a value for **fields** path parameter.
                value: "foo"
          text/plain:
            schema:
              type: string
            examples:
              setString:
                summary: set string field
                description: Set any string field. For example use it with **comment** as a value for **fields** path parameter.
                value: foo
      responses:
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/PutFieldNotFound'
        '401':
          description: Unauthorized
    delete:
      tags:
        - templates
      summary: Removes specified template field
      description: Removes specified template field
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/TemplateFieldParam'
      responses:
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/DeleteFieldNotFound'
        '401':
          description: Unauthorized
        '404':
          description: Failure
          content:
            text/plain:
              schema:
                type: string
                example: >
                  specified field cannot be used in `DELETE` requests; path: comment



  /api/v1/enroll-rules/count:
    get:
      tags:
        - enroll-rules
      summary: Get enroll rules count
      description: Returns enroll rules count
      operationId: enroll_rules_count
      parameters:
        - $ref: '#/components/parameters/FilterParam'
      responses:
        '200':
          description: successful operation
          content:
            text/plain:
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadFilterRequest'
        '401':
          description: Unauthorized

  /api/v1/enroll-rules:
    post:
      tags:
        - enroll-rules
      summary: Creates a new enroll rules
      description: Creates a new enroll rule
      operationId: createEnrollRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollRule'
            examples:
              createEnrollmentRuleWithConnection:
                summary: Enroll rule with connection settings
                value:
                  name: "foo1"
                  selector: "os=Windows"
                  options:
                    connection:
                      mode: connect
                      address: "{{agents_endpoint}}"
              createEnrollmentRuleWithTemplate:
                summary: Enroll rule with template
                value:
                  name: "foo2"
                  selector: "os=Linux"
                  options:
                    templateId: "b0d5a854-3163-465a-a5dc-559764a8095f"
              createComplexEnrollmentRule:
                summary: Complex enrollment rule
                value:
                  name: "foo3"
                  selector: "enrolled=false"
                  priority: 10
                  options:
                    certificate:
                      country: "US"
                      state: "CA"
                      locality: "San-Francisco"
                      organization: "NXLog"
                      organizationUnit: "Dev"
                    connection:
                      mode: "connect"
                      address: "{{agents_endpoint}}"
                    extraParams:
                      ReversionTimeout: "10"

      responses:
        '200':
          description: Successfully created enroll rule
          content:
            text/plain:
              schema:
                type: string
                format: uuid
                description: UUID of the created enroll rule
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                failedToInterpretFilter:
                  summary: Error interpreting filter
                  description: This type of error happens when the backed fails to interpret the filter in **selector** field.
                  value:
                    message: "Nom error: Parsing Error: Error { input: \"foo=Linux\", code: Tag }"
        '401':
          description: Unauthorized
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                referencedConfiguration:
                  summary: Referenced configuration not found
                  description: This response is returned when reference in **templateId** configuration is not found
                  value:
                    message: "configuration referenced by enrollment options does not exist"
  /api/v1/enroll-rules/*:
    get:
      tags:
        - enroll-rules
      summary: List enroll rules
      description: List enroll rules
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnrollRule'
              examples:
                allFields:
                  summary: List of enroll rules with all fields
                  description: Enroll rules with **fields** path parameter set to **all**
                  value:
                    [
                      {
                        "id": "ab97cab2-e07b-11ee-8007-e2861daf1745",
                        "name": "foo2",
                        "optionsJson": "{\"templateId\":\"3c3de8b8-db0c-11ee-8001-c9f2c9b37081\"}",
                        "selector": "os=Linux",
                        "priority": 0,
                        "automatic": false,
                        "comment": "",
                        "addedTime": "2024-03-12 14:20:25.951850436 UTC",
                        "updatedTime": "2024-03-12 14:20:25.951850436 UTC"
                      },
                      {
                        "id": "7bc19786-e079-11ee-8003-f23fb3eb5732",
                        "name": "foo1",
                        "optionsJson": "{\"connection\":{\"mode\":\"connect\",\"address\":\"{{agents_endpoint}}\"}}",
                        "selector": "os=Windows",
                        "priority": 0,
                        "automatic": false,
                        "comment": "",
                        "addedTime": "2024-03-12 14:04:46.701449670 UTC",
                        "updatedTime": "2024-03-12 14:27:16.284001707 UTC"
                      },
                      {
                        "id": "affdd90e-e078-11ee-8002-b8064cce6a5b",
                        "name": "foo3",
                        "optionsJson": "{\"certificate\":{\"country\":\"US\",\"state\":\"CA\",\"locality\":\"San-Francisco\",\"organization\":\"NXLog\",\"organizationUnit\":\"Dev\"},\"connection\":{\"mode\":\"connect\",\"address\":\"{{agents_endpoint}}\"},\"extraParams\":{\"ReversionTimeout\":\"10\"}}",
                        "selector": "os=Linux",
                        "priority": 10,
                        "automatic": false,
                        "comment": "",
                        "addedTime": "2024-03-12 13:59:04.841115585 UTC",
                        "updatedTime": "2024-03-12 13:59:04.841115585 UTC"
                      }
                    ]
        '404':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
    patch:
      tags:
        - enroll-rules
      summary: Update enroll rules
      description: Update enroll rules
      parameters:
        - $ref: '#/components/parameters/FilterParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              setComment:
                $ref: '#/components/examples/setCommentJSON'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
    delete:
      tags:
        - enroll-rules
      summary: Delete enroll rules
      description: Delete enroll rules
      parameters:
        - $ref: '#/components/parameters/FilterParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
  /api/v1/enroll-rules/*/{field}:
    get:
      tags:
        - enroll-rules
      summary: Extracts specified field from a list of enroll rules
      description: Extracts a specified field from each enroll rule in the filtered scope and returns them as an array
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/EnrollRuleFieldParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                ids:
                  $ref: '#/components/examples/idList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/GetFieldNotFound'
    put:
      tags:
        - enroll-rules
      summary: Change specified field for multiple enroll-rules
      description: Changes specified field for multiple enroll-rules
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/EnrollRuleFieldParam'
      requestBody:
        required:
          true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              setTrue:
                summary: sets boolean field to true
                description: Sets boolean field to true. For example use **automatic** as a value for **fields** path parameter.
                value: true
              setStringField:
                summary: set string field
                description: Set string field. For example use it with **comment** as a value for **fields** path parameter.
                value: "foo"
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/PutFieldNotFound'
    delete:
      tags:
        - enroll-rules
      summary: Removes or clears specified field for multiple enroll-rules
      description: Removes or clears specified field for multiple enroll-rules
      parameters:
        - $ref: '#/components/parameters/FilterParam'
        - $ref: '#/components/parameters/EnrollRuleFieldParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/DeleteFieldNotFound'

  /api/v1/enroll-rules/{id}:
    get:
      tags:
        - enroll-rules
      summary: Get enroll rule by id
      description: Get enroll rule by id
      operationId: getEnrollRule
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrollRule'
              examples:
                allFields:
                  summary: Enroll rules with all fields
                  description: Enroll rule with **fields** path parameter set to **all**
                  value:
                    {
                      "id": "ab97cab2-e07b-11ee-8007-e2861daf1745",
                      "name": "foo2",
                      "optionsJson": "{\"templateId\":\"3c3de8b8-db0c-11ee-8001-c9f2c9b37081\"}",
                      "selector": "os=Linux",
                      "priority": 0,
                      "automatic": false,
                      "comment": "",
                      "addedTime": "2024-03-12 14:20:25.951850436 UTC",
                      "updatedTime": "2024-03-12 14:20:25.951850436 UTC"
                    }
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/GetFieldNotFound'
    patch:
      tags:
        - enroll-rules
      summary: Change enroll rule
      description: Change enroll rule by id
      operationId: updateEnrollRule
      parameters:
        - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              setComment:
                $ref: '#/components/examples/setCommentJSON'
      responses:
        '204':
          description: Success
        '401':
          description: Unauthorized
        '404':
          description: Not found
    delete:
      tags:
        - enroll-rules
      summary: Deletes enroll rule
      description: Deletes enroll rule by id
      operationId: deleteEnrollRule
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '204':
          description: Success
        '401':
          description: Unauthorized
        '404':
          description: Not found


  /api/v1/enroll-rules/{id}/{field}:
    get:
      tags:
        - enroll-rules
      summary: Get a single enroll rule field
      description: Get a single enroll rule field
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/EnrollRuleFieldParam'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string
              examples:
                optionsJSON:
                  $ref: '#/components/examples/enrollRuleOptionsJSON'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/GetFieldNotFound'
    put:
      tags:
        - enroll-rules
      summary: Change specified enroll rule field
      description: Changes specified enroll rule field
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/EnrollRuleFieldParam'
      requestBody:
        required:
          true
        content:
          text/plain:
            schema:
              type: string
            examples:
              updateSelector:
                summary: Change selector
                value: |
                  enrolled=false
          application/json:
            schema:
              $ref: '#/components/schemas/DataPatch'
            examples:
              updateOptionsJSON:
                summary: Change enrollment options
                description: Set **field** to **options-json** to update enroll rule options.
                value: |
                  {"connection":{"mode":"connect","address":"{{agents_endpoint}}"}}
      responses:
        '204':
          description: Success
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/GetFieldNotFound'
    delete:
      tags:
        - enroll-rules
      summary: Removes specified enroll rule field
      description: Removes specified enroll rule field
      parameters:
        - $ref: '#/components/parameters/IdParam'
        - $ref: '#/components/parameters/EnrollRuleFieldParam'
      responses:
        '204':
          description: Success
        '401':
          description: Unauthorized
        '404':
          description: Failure
          content:
            text/plain:
              schema:
                type: string
                example: >
                  specified field cannot be used in `DELETE` requests; path: comment

  /api/v1/agents/{id}/certificate/renew:
    post:
      tags:
        - actions
      summary: Renew agent's certificate
      parameters:
        - name: id
          in: path
          required: true
          description: Agent ID or `*` to select all
          schema:
            type: string
        - $ref: '#/components/parameters/FilterParam'
      responses:
        '200':
          description: Operation results for a group of agents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
              examples:
                success:
                  summary: successful renew
                  description: Renew succeeded for all agents.
                  value:
                    [
                      {
                        "id": "2c70347c-df06-11ee-80b4-336534663863",
                        "status": "success"
                      },
                      {
                        "id": "422ebe80-d666-11ee-8039-353430613862",
                        "status": "success"
                      },
                    ]
                resultsWithError:
                  summary: Partial renewal
                  description: Partial renewal occurs when the operation fails for some agents. See error fields for details.
                  value:
                    [
                      {
                        "id": "3b1d93d3-d711-11ee-8000-7dd31545780f",
                        "status": "error",
                        "error": "{\"message\":\"agent certificate file \\\"cert/agent-cert.pem\\\" is unsynced\",\"help\":\"Try again or resolve agent certificate sync conflict manually using '/agents/{AGENT_ID}/files-sync/cert/agent-cert.pem' endpoints family\"}"
                      },
                      {
                        "id": "2c70347c-df06-11ee-80b4-336534663863",
                        "status": "success"
                      },
                    ]
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'


  /api/v1/agents/{id}/files-sync/{ACL}/{NAME}/{action}:
    post:
      tags:
        - actions
      summary: Update agent's configuration files
      parameters:
        - name: id
          in: path
          required: true
          description: Agent ID or `*` to select all
          schema:
            type: string
        - name: ACL
          in: path
          required: true
          description: ACL or `*` to select all
          schema:
            type: string
            default: "*"
        - name: NAME
          in: path
          required: true
          description: File name or `*` to select all
          schema:
            type: string
            default: "*"
        - name: action
          in: path
          required: true
          description: Sync action to perform
          schema:
            type: string
            enum:
              - use-manager-file-version
              - use-last-synced-file-version
              - use-agent-file-version
        - $ref: '#/components/parameters/FilterParam'

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OperationResult'
        '204':
          description: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized

  /api/v1/backup:
    post:
      tags:
        - database
      summary: Backup database
      description: Creates database backup at provided file path
      operationId: backup

      requestBody:
        required:
          true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintainDbRequest'
            examples:
              createBackup:
                summary: Create minder database backup
                value: |
                  {"pathToArchive":"/tmp/minder_backup.tgz"}
      responses:
        '204':
          description: Success
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  help:
                    type: string
                  details:
                    type: string
              examples:
                noSuchFile:
                  summary: Backup file not found
                  description: An attempt to restore from missing file
                  value:
                    {"message":"backup: failed to backup Agent Manager's database","help":"This error is a result of an error internal to Agent Manager, not user actions. Please contact NXLog support.","details":"failed to create db backup archive: failed to create snapshot archive file: Permission denied (os error 13)"}

  /api/v1/restore:
    post:
      tags:
        - database
      summary: Backup database
      description: Restore backup from provided file path
      operationId: restore

      requestBody:
        required:
          true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintainDbRequest'
            examples:
              restoreFromBackup:
                summary: Restore minder database from backup
                value: |
                  {"pathToArchive":"/tmp/minder_backup.tgz"}
      responses:
        '204':
          description: Success
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  help:
                    type: string
                  details:
                    type: string
              examples:
                noSuchFile:
                  summary: Backup file not found
                  description: An attempt to restore from missing file
                  value:
                    {"message":"backup: failed to restore Agent Manager's database from archive","help":"This error is a result of an error internal to Agent Manager, not user actions. Please contact NXLog support.","details":"failed to open the backup archive file: No such file or directory (os error 2)"}



  /api/v1/version:
    get:
      tags:
        - public
      summary: Agent manager version
      description: Returns version of agent manager
      operationId: version
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
      security: []
components:
  parameters:
    IdParam:
      name: id
      in: path
      description: ID
      required: true
      schema:
        type: string
    FilterParam:
      in: query
      name: filter
      description: >
        Allows for complex querying of resources using a custom Minder Query Language (MQLv2).
        Supports logical operators (NOT, AND, OR, etc.), comparison operators (=, !=, <, >, etc.),
        and special functions like REGEX. Tokens can be words or operators, with specific rules
        for parsing based on context and token type. Use double or single quotes for strings that
        include spaces, operators, or reserved characters.
      required: false
      schema:
        type: string
      examples:
        noFilter:
          summary: No filter
          value: ''
        simpleFilter:
          summary: Simple equality check
          value: 'status=error'
        complexFilter:
          summary: Complex query combining different operators
          value: 'status=error AND (cpu-load > 0.5 OR memory-used > 2048) AND hostname LIKE "srv-*"'
        regexFilter:
          summary: Using REGEX for pattern matching
          value: 'os regex (?i)linux'
        quotedString:
          summary: Using quotes for string values that include spaces or special characters
          value: 'comment="This is a test comment" AND os="Linux"'
        moduleFilter:
          summary: Filter all the agents which has specific module type
          value: 'any modules/*/type = xm_admin'
    FieldParam:
      in: path
      name: field
      description: |
        This query argument can be used for extraction a field of response object.

        It is very much the same as query parameter **fields** with the difference that only
        one field should be specified.

        See schema of response object for possible field values.

        **Use kebab syntax instead of camel case.**
      required: true
      schema:
        type: string
      examples:
        id:
          summary: id
          value: id
        address:
          summary: address
          value: address
        addedTime:
          summary: added-time
          value: added-time
        arch:
          summary: arch
          value: arch
        certificate:
          summary: certificate
          value: certificate
        cachedLogs:
          summary: cached-logs
          value: cached-logs
        comment:
          summary: comment
          value: comment
        config:
          summary: config
          value: config
        configSyncedWithTemplate:
          summary: config-synced-with-template
          value: config-synced-with-template
        connectedTime:
          summary: connected-time
          value: connected-time
        cpuLoad:
          summary: cpu-load
          value: cpu-load
        cpuUsageTime:
          summary: cpu-usage-time
          value: cpu-usage-time
        enroll:
          summary: enroll
          value: enroll
        enrollByRules:
          summary: enroll-by-rules
          value: enroll-by-rules
        enrolled:
          summary: enrolled
          value: enrolled
        enrolledTime:
          summary: enrolled-time
          value: enrolled-time
        eventsPerSecond:
          summary: events-per-second
          value: events-per-second
        fdCount:
          summary: fd-count
          value: fd-count
        fileAcls:
          summary: file-acls
          value: file-acls
        fileNames:
          summary: file-names
          value: file-names
        files:
          summary: files
          value: files
        filesSync:
          summary: files-sync
          value: files-sync
        filesSynced:
          summary: files-synced
          value: files-synced
        hostname:
          summary: hostname
          value: hostname
        labelNames:
          summary: label-names
          value: label-names
        labels:
          summary: labels
          value: labels
        lastProcessedEventTime:
          summary: last-processed-event-time
          value: last-processed-event-time
        managerAddress:
          summary: manager-address
          value: manager-address
        memoryUsed:
          summary: memory-used
          value: memory-used
        moduleNames:
          summary: module-names
          value: module-names
        modules:
          summary: modules
          value: modules
        name:
          summary: name
          value: name
        online:
          summary: online
          value: online
        os:
          summary: os
          value: os
        osRelease:
          summary: os-release
          value: os-release
        persisted:
          summary: persisted
          value: persisted
        persistedTime:
          summary: persisted-time
          value: persisted-time
        pid:
          summary: pid
          value: pid
        polledTime:
          summary: polled-time
          value: polled-time
        refresh:
          summary: refresh
          value: refresh
        routeNames:
          summary: route-names
          value: route-names
        routes:
          summary: routes
          value: routes
        session:
          summary: session
          value: session
        startedTime:
          summary: started-time
          value: started-time
        status:
          summary: status
          value: status
        synced:
          summary: synced
          value: synced
        templateId:
          summary: template-id
          value: template-id
        templateName:
          summary: template-name
          value: template-name
        threadCount:
          summary: thread-count
          value: thread-count
        version:
          summary: version
          value: version
        warnings:
          summary: warnings
          value: warnings
    TemplateFieldParam:
      in: path
      name: field
      description: |
        This query argument can be used for extraction a field of response object.

        It is very much the same as query parameter **fields** with the difference that only
        one field should be specified.

        See schema of response object for possible field values.

        **Use kebab syntax instead of camel case.**
      required: true
      schema:
        type: string
      examples:
        id:
          summary: id
          value: id
        name:
          summary: name
          value: name
        addedTime:
          summary: added-time
          value: added-time
        agentResources:
          summary: agent-resources
          value: agent-resources
        builderConfig:
          summary: builder-config
          value: builder-config
        comment:
          summary: comment
          value: comment
        config:
          summary: parts
          value: parts
        moduleTypes:
          summary: module-types
          value: module-types
        solutionPackKeys:
          summary: solution-pack-keys
          value: solution-pack-keys
        tags:
          summary: tags
          value: tags
        updatedTime:
          summary: updated-time
          value: updated-time
        usedByAgents:
          summary: used-by-agents
          description: To find which agents currently use the template(s)
          value: used-by-agents
        usedByEnrollRules:
          summary: used-by-enroll-rules
          value: used-by-enroll-rules
        usedByTemplates:
          summary: used-by-templates
          value: used-by-templates

    EnrollRuleFieldParam:
      in: path
      name: field
      schema:
        type: string
      description: |
        This query argument can be used for extraction a field of response object.

        It is very much the same as query parameter **fields** with the difference that only
        one field should be specified.

        See schema of response object for possible field values.

        **Use kebab syntax instead of camel case.**
      required: true
      examples:
        id:
          summary: id
          value: id
        name:
          summary: name
          value: name
        selector:
          summary: selector
          value: selector
        priority:
          summary: priority
          value: priority
        automatic:
          summary: automatic
          value: automatic
        optionsJson:
          summary: options-json
          value: options-json
        comment:
          summary: comment
          value: comment
        addedTime:
          summary: added-time
          value: added-time
        updatedTime:
          summary: updated-time
          value: updated-time

    FieldsParam:
      in: query
      name: fields
      style: form
      explode: false
      description: |
        This query argument can be used for extraction of fields of response object.
        If it is not set then the `default` field set is returned.

        The names of the selected fields are listed, separated by commas `,`.
        The path parts are separated with slashes `/`.

        **Consult the response schema for possible field values.**

        Here is a list of predefined sets:
          - `default` - Field set returns the set of fields used by default;
          - `none` - Field set returns no fields will be used and can be used to get only the object if it is non-null;
          - `all` - Field set returns all the fields except aliases.
          - `info` - **[agent only]** Field set of: id, hostname, os, version, online, persisted, enrolled, configured, template-id
          - `stats` - **[agent only]** Field set of: pid, memory-used, cpu-load, cpu-usage-time, thread-count, fd-count events-per-second.
          - `state` - **[agent only]** Field set of: status, errors/*, warnings/*, synced, files-synced, config-synced-with-template.
      schema:
        type: string
      required: false

    SortByParam:
      in: query
      name: sort-by
      description: >
        Specifies the fields by which the results should be sorted. Fields are separated by commas.
        Each field may be followed by a space and the keyword ASC (for ascending order) or DESC (for descending order),
        e.g., "name ASC, os DESC". If no order is specified, ASC is assumed. The final tie-breaker is the UUID in ascending order.
      required: false
      schema:
        type: string
      example: "id"
    AfterUUIDParam:
      name: after
      in: query
      description: After ID
      schema:
        type: string
        format: uuid
    BeforeUUIDParam:
      name: before
      in: query
      description: Before ID
      schema:
        type: string
        format: uuid
    FromUUIDParam:
      name: from
      in: query
      description: From ID
      schema:
        type: string
        format: uuid
    ToUUIDParam:
      name: to
      in: query
      description: To ID
      schema:
        type: string
        format: uuid
    OffsetParam:
      name: offset
      description: Pagination offset parameter
      in: query
      schema:
        type: integer
        minimum: 0
    LimitParam:
      name: limit
      description: Maximum number of records to return per page
      in: query
      schema:
        type: integer
        minimum: 1
    DistinctParam:
      name: distinct
      in: query
      required: false
      schema:
        type: string
      description: >
        Specify this parameter without a value to filter out duplicates.
        The value, if specified, is disregarded.
        For example, simply append **?distinct** to the query.
      examples:
        withoutDistinct:
          summary: without distinct
          value:
        withDistinct:
          summary: with distinct
          description: >
            The value **true** is not strictly necessary and is only provided to work around limitations in Swagger editor.
            The same behavior is expected for any specified value.
          value: true

  schemas:
    Agent:
      type: object
      properties:
        id:
          type: string
          description: agent ID
          format: uuid
        status:
          type: string
          description: >
            Status of the agent with possible values: ok, warning (alias warn), error (alias err).
            Ordering: ok < warning < error
          enum:
            - ok
            - warning
            - error
        errors:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Error'
        warnings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Warning'
        hostname:
          type: string
          description: The respective hostname field from agent’s xm_admin ServerInfo response.
        os:
          type: string
          description: The respective os field from agent’s xm_admin ServerInfo response.
        osRelease:
          type: string
          description: The respective os-release field from agent’s xm_admin ServerInfo response.
        arch:
          type: string
          description: The respective arch field from agent’s xm_admin ServerInfo response.
        version:
          type: string
          description: The respective version field from agent’s xm_admin ServerInfo response.
        online:
          type: boolean
          description: True if the connection between the manager and the agent is established.
        persisted:
          type: boolean
          description: True if the agent has persistent id and so it is retained in the database even when it becomes offline or restarted.
        enrolled:
          type: boolean
          description: True if the enrollment process was performed or if it has been set via HTTP PUT request.
        configured:
          type: boolean
          description: True if the agent has some input or output modules.
        templateId:
          type: string
          description: The UUID of the template that is assigned to the agent.
          format: uuid
          nullable: true
        templateName:
          type: string
          description: The name of the assigned template.
          nullable: true
        synced:
          type: boolean
          description: >
            True if `filesSynced` IS true AND `configSyncedWithTemplate` IS NOT false.
        filesSynced:
          type: boolean
          description: True when all the files are synchronized between the agent manager and the agent itself.
        configSyncedWithTemplate:
          type: boolean
          description: >
            Non null when the agent have the assigned template.
            True when agent’s config is synchronized with the serialized template assigned to this agent template.
          nullable: true
        pid:
          type: integer
          description: Non null when the agent is online. Agent process id.
        memoryUsed:
          type: integer
          description: The respective memory field from agent’s xm_admin ServerInfo response.
        cpuLoad:
          type: number
          format: float
          description: The respective load field from agent’s xm_admin ServerInfo response.
        cpuUsageTime:
          type: number
          description: >
            Agent cpu usage time since agent start (in seconds).
            The respective cpu field from agent’s xm_admin ServerInfo response multiplied by 106 to convert from micros to seconds.
          format: float
        threadCount:
          type: integer
          description: The respective thread_count field from agent’s xm_admin ServerInfo response.
        fdCount:
          type: integer
          description: The respective fd_count field from agent’s xm_admin ServerInfo response.
        eventsPerSecond:
          type: integer
          description: Calculated total agent events per second for the time between the second-to-last and the last polling.
        address:
          type: string
          description: Non null when the agent is online. Agent socket address.
        managerAddress:
          type: string
          description: Non null when the agent is online. Relevant agent manager socket address.
        certificate:
          $ref: '#/components/schemas/AgentCertificate'
          nullable: true
        comment:
          type: string
          description: User-specified comment string.
        addedTime:
          type: string
          description: The time when the agent was added to the agent manager.
          format: date-time
        startedTime:
          type: string
          description: The respective start field from agent’s xm_admin ServerInfo response (converted to user-friendly date/time format).
          format: date-time
        connectedTime:
          type: string
          description: The time when the agent was connected to the agent manager last time.
          format: date-time
        persistedTime:
          type: string
          format: date-time
          description: The time when the agent was persisted by the agent manager last time.
          nullable: true
        enrolledTime:
          type: string
          format: date-time
          description: The time when the agent was enrolled or marked as enrolled by the agent manager last time.
          nullable: true
        polledTime:
          type: string
          description: The time when the agent was polled by the agent manager last time.
          format: date-time
        lastProcessedEventTime:
          type: string
          format: date-time
          nullable: true
        labels:
          type: object
          additionalProperties:
            type: string
        modules:
          type: object
          description: MODULE_NAME
          additionalProperties:
            $ref: '#/components/schemas/Module'
        routes:
          type: object
          description: ROUTE_NAME
          additionalProperties:
            $ref: '#/components/schemas/RouteInfo'
        config:
          type: string
          description: >
            The contents of conf/managed.conf file.
            Contains either the actual content of conf/managed.conf file or the expected content of the file when it is changed by the manager,
            but not yet updated on the agent.
        cachedLogs:
          type: string
          description: The limited amount of agent logs cached in the database.
        files:
          type: object
          description: ACL
          additionalProperties:
            type: object
            description: NAME
            additionalProperties:
              type: string
        filesSync:
          type: object
          description: ACL
          additionalProperties:
            type: object
            description: NAME
            additionalProperties:
              $ref: '#/components/schemas/FileSync'

    AgentCertificate:
      type: object
      description: Agent's certificate information
      properties:
        notBefore:
          type: string
          format: date-time
          description: A notBefore constraint of the agent's certificate.  The time can be represented in ASN.1, RFC3339 or RFC2822 format.
          default: current time.
        notAfter:
          type: string
          format: date-time
          description: A notAfter constraint of the agent's certificate. The time can be represented in ASN.1, RFC3339 or RFC2822 format.
          default: 730 days (2 years) from notBefore.
        subject:
          type: string
          description: Information about the certificate holder.
        digestSha256:
          type: string
          description: The hash of the certificate.

    Certificate:
      type: object
      description: Agent's certificate generation options
      properties:
        commonName:
          type: string
          description: A common name (CN) of the agent's certificate subject field.
          default: agent's hostname.
        country:
          type: string
          description: A country (C) of the agent's certificate subject field  containing a two-letter country code.
        state:
          type: string
          description: A state (ST) of the agent's certificate subject field.
        locality:
          type: string
          description: A locality (L) of the agent's certificate subject field.
        organization:
          type: string
          description: An organization (O) of the agent's certificate subject field.
        organizationUnit:
          type: string
          description: An organization unit (OU) of the agent's certificate subject field.
        notBefore:
          type: string
          format: date-time
          description: A notBefore constraint of the agent's certificate.  The time can be represented in ASN.1, RFC3339 or RFC2822 format.
          default: current time.
        notAfter:
          type: string
          format: date-time
          description: A notAfter constraint of the agent's certificate. The time can be represented in ASN.1, RFC3339 or RFC2822 format.
          default: 730 days (2 years) from notBefore.
        serial:
          type: integer
          description: A serial field of the agent's certificate.
        encryptKey:
          type: boolean
          description: A key that controls whether to encrypt the agent's private key (with randomly generated password).
          default: false
        isCa:
          type: boolean
          description: A key that specifies whether generated certificate is a Certificate Authority.
          default: false

    Connection:
      type: object
      properties:
        mode:
          type: string
          description: >
              Connection mode:
                - `connect` - agent connects to the agent-manager at a given address or addresses.
                - `listen` - agent is waiting for the agent-manager to connect to the specified address.
          enum:
            - connect
            - listen
        address:
          type: string
          description: >
            An address to establish an outgoing connection or listen for incoming connections.
            A string containing Agent manager’s IP address or host name and the agent management port in an ADDRESS:PORT format.
        addresses:
          type: array
          items:
            type: string
          description: >
            Multiple addresses. Agents will try to connect to them in the specified order and use the remaining ones as a fallback.
            It can only be used with connect mode.
            An JSON array of strings containing IP addresses or host names and agent management ports in an ADDRESS:PORT format.
      required:
        - mode

    DataPatch:
      oneOf:
        - type: object
          additionalProperties: true
        - type: array
        - type: string
        - type: number
        - type: boolean

    EnrollRule:
      type: object
      properties:
        name:
          type: string
          description: The name of the rule (not required to be unique).
        options:
          $ref: "#/components/schemas/Enrollment"
          description: |
            Enrollment options that are applied when this rule is selected during the enrollment rule selection process.
            This option is only used to **create** a new enroll rule.
        optionsJson:
          $ref: "#/components/schemas/Enrollment"
          description: |
            Enrollment options **written as JSON string** that are applied when this rule is selected during the enrollment rule selection process.
        selector:
          type: string
          description: The MQL filter which is used to select the agents this enroll rule is applicable to.
        priority:
          type: number
          description: The priority of a given enroll rule. Numerically lesser number means smaller priority. Numerically greater number means higher priority. The matched rules with higher priority are selected.
          default: 0
        automatic:
          type: boolean
          description: The flag defines whether this rule should be used for the automatic enrollment when the agent is connected.
          default: false
        comment:
          type: string
          description: The user defined comment.
      required:
        - name
        - options
        - selector

    Enrollment:
      type: object
      properties:
        certificate:
          $ref: '#/components/schemas/Certificate'
        connection:
          $ref: '#/components/schemas/Connection'
        extraParams:
          $ref: '#/components/schemas/ExtraParams'
        extraRoAcls:
          $ref: '#/components/schemas/ExtraRoAcls'
        extraWoAcls:
          $ref: '#/components/schemas/ExtraWoAcls'
        extraRwAcls:
          $ref: '#/components/schemas/ExtraRwAcls'
        extraLabels:
          $ref: '#/components/schemas/ExtraLabels'
        templateId:
          type: string
          description: The UUID of the template used for agent's config.

    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message
        help:
          type: string
          description: Help message to resolve the error
        note:
          type: string
          description: Additional common details about the error
      additionalProperties:
        description: Additional details about the error
        oneOf:
          - type: string
          - type: number
          - type: boolean
          - type: object
          - type: array

    ExtraParams:
      type: object
      properties:
        ReversionTimeout:
          type: string

    ExtraRoAcls:
      type: object
      properties:
        ro-acl:
          type: string

    ExtraWoAcls:
      type: object
      properties:
        wo-acl:
          type: string

    ExtraRwAcls:
      type: object
      properties:
        rw-acl1:
          type: string
        rw-acl2:
          type: string

    ExtraLabels:
      type: object
      properties:
        first:
          type: string
        second:
          type: string

    FileSync:
      type: object
      description: >
        TODO: get description
      properties:
        synced:
          type: boolean
          description: True if the file is synced between manager and agent.
        managerFileSha256:
          type: string
          description: The hash of the file version from manager side.
        agentFileSha256:
          type: string
          description: The hash of the file version from agent side.
        lastSyncedFileSha256:
          type: string
          description: >
            The hash of the file version which was previously synchronized between manager and agent or
            accepted as a base version before updating to a manager's one.
        contents:
          type: string
          additionalProperties:
            type: string
            description: The contents of the file by the specified hash.

    OperationResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          example: success

    Module:
      type: object
      properties:
        type:
          type: string
          description: >
            Module type specified by module Module directive. Corresponds to module field from agent’s xm_admin ModuleInfo response.
            Such as xm_admin, im_file, om_http
        kind:
          type: string
          description: Module kind. Corresponds to module-type field from agent’s xm_admin ModuleInfo response.
          enum:
            - input
            - output
            - processor
            - extension
        eventsReceived:
          type: integer
          description: Corresponds to evt-recvd field from agent’s xm_admin ServerInfo response
        eventsDropped:
          type: integer
          description: Corresponds to evt-drop field from agent’s xm_admin ServerInfo response.
        eventsForwarded:
          type: integer
          description: Corresponds to evt-fwd field from agent’s xm_admin ServerInfo response.
        queueLimit:
          type: integer
          description: Corresponds to queuelimit field from agent’s xm_admin ServerInfo response.
        queueSize:
          type: integer
          description: Corresponds to queuesize field from agent’s xm_admin ServerInfo response.
        queueRecordCount:
          type: integer
          description: Corresponds to queuerecordcount field from agent’s xm_admin ServerInfo response
        batchSize:
          type: integer
          description: Corresponds to batchsize field from agent’s xm_admin ServerInfo response.
        eventsPerSecond:
          type: integer
          description: Calculated total module events per second for the time between the second-to-last and the last polling.
        variables:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModuleVariable'

    ModuleVariable:
      type: object
      properties:
        name:
          type: string
          description: variable name
        type:
          type: string
          description: variable type
        value:
          type: string
          description: variable value

    RouteInfo:
      type: object
      description: Agent route
      properties:
        moduleNames:
          type: array
          description: Module names
          items:
            type: string
        inUse:
          type: string
          description: Corresponds to in-use field from agent’s xm_admin RouteInfo response.
        eventsReceived:
          type: number
          description: Corresponds to evt-recvd field from agent’s xm_admin RouteInfo response.
        eventsDropped:
          type: number
          description: Corresponds to evt-drop field from agent’s xm_admin RouteInfo response.
        eventsForwarded:
          type: number
          description: Corresponds to evt-fwd field from agent’s xm_admin RouteInfo response.
        eventsPerSecond:
          type: number
          description: Calculated total route events per second for the time between the second-to-last and the last polling.

    Template:
      type: object
      properties:
        name:
          type: string
          description: The name of the template (not required to be unique).
        parts:
          type: array
          items:
            type: string
            format: uuid
          description: The UUIDs of children sub-templates of which this template is composed. Conflicts with `content` attribute.
        content:
          type: string
          description: The content of the configuration template. Conflicts with `parts` attribute
        tags:
          type: array
          items:
            type: string
          description: The user defined template tags/attributes like 'draft', 'paid', 'solution pack'.
        comment:
          type: string
          description: The user defined comment.
      required:
        - name

    Version:
      type: object
      required:
        - name
        - version
        - os
      properties:
        branch_name:
          type: string
          nullable: true
        commit_hash:
          type: string
          nullable: true
        name:
          type: string
          example: NXLog Agent Manager
        os:
          type: string
          example: linux
        version:
          type: string

    MaintainDbRequest:
      type: object
      required:
        - pathToArchive
      properties:
        pathToArchive:
          type: string

    Warning:
      type: object
      properties:
        message:
          type: string
          description: Warning message
        help:
          type: string
          description: Help message to resolve the warning
        note:
          type: string
      additionalProperties:
        description: Additional details about the warning
        oneOf:
          - type: string
          - type: number
          - type: boolean
          - type: object
          - type: array
  examples:
    agentsWithDefaultFields:
      summary: list of agents with default field set
      description: |
        The response contains a list of agents with default set fields.
      value: |
        [
          {
            "id": "3b1d93d3-d711-11ee-8000-7dd31545780f",
            "hostname": "16024fc5b6b2",
            "os": "Linux",
            "version": "6.2.9212",
            "online": true,
            "persisted": true,
            "enrolled": true,
            "configured": false,
            "templateId": "3c3de8b8-db0c-11ee-8001-c9f2c9b37081"
          },
          {
            "id": "422ebe80-d666-11ee-8039-353430613862",
            "hostname": "440a8b07451f",
            "os": "Linux",
            "version": "6.2.9212",
            "online": true,
            "persisted": true,
            "enrolled": true,
            "configured": false,
            "templateId": "3c3de8b8-db0c-11ee-8001-c9f2c9b37081"
          }
        ]
    agentsWithIdAndStatusFields:
      summary: list of agents with id and status fields
      description: The response consists of list of agents for **fields** query parameter set to **id,status**
      value:
        [
          {
            "id": "3b1d93d3-d711-11ee-8000-7dd31545780f",
            "status": "ok",
            "errors": {},
            "warnings": {},
            "synced": true,
            "filesSynced": true,
            "configSyncedWithTemplate": true
          },
          {
            "id": "422ebe80-d666-11ee-8039-353430613862",
            "status": "ok",
            "errors": {},
            "warnings": {},
            "synced": true,
            "filesSynced": true,
            "configSyncedWithTemplate": true
          }
        ]
    agentSingleWithDefaultFields:
      summary: agent with default field set
      description: |
        The response contains a agents with **id** path parameter set to **3b1d93d3-d711-11ee-8000-7dd31545780f**.
      value: |
        {
          "id": "3b1d93d3-d711-11ee-8000-7dd31545780f",
          "hostname": "16024fc5b6b2",
          "os": "Linux",
          "version": "6.2.9212",
          "online": true,
          "persisted": true,
          "enrolled": true,
          "configured": false,
          "templateId": "3c3de8b8-db0c-11ee-8001-c9f2c9b37081"
        }
    agentSingleWithSingleField:
      summary: agent with default field set
      description: |
        The response contains a agents with **id** path parameter set to **3b1d93d3-d711-11ee-8000-7dd31545780f** and **field** parameter set to **os**.
      value: Linux

    fieldNotFound:
      summary: Unknown field
      description: |
        The response contains the detailed description of which field is not found (*foo* in this case) and what fields are
        expected.
      value: |
        field not found; ident: foo; parent path: ; full path: foo; expected: default, none, all, <and other supported field sets and fields>.

    filterParseError:
      summary: Failed to parse filter parameter
      description: |
        This type of error occurs when the **filter** parameter is written incorrectly. As the filter grammar is very rich
        there can be varios error messages covering the issue such as missing terminating double quotation symbol or wrong field used.
        The example field contains an incomplete list of possible errors.
        - Example 1: **comment="This is a test comment" AND os=Linux"** - Missing `"` symbol before Linux.
        - Example 2: **os regex ?i)linux** - Missing `(` before `?`-mark. The correct query is: **os regex (?i)linux**
        - Example 3: **status=error (cpu-load > 0.5 OR memory-used > 2048) AND hostname LIKE "srv-*"** - Missing `AND` or `OR` operator that would logically group the condition (right after **status=error** expression).


      value: |
        // Example 1:
        missing terminating double quotation mark ("), input: "comment=\"This is a test comment\" AND os=Linux\"", span: "\"" at 45..46
        // Example 2:
        failed to parse expression value a time: regex parse error:
          ^?i)linux$
             ^
        error: unopened group, input: "os regex ?i)linux", span: "os regex ?i)linux" at 0..17
        // Example 3:
        expected binary operation operator (the valid operators are 'AND', 'OR', '<', '<=', '=', '>=', '>', 'REGEX', 'LIKE', `IS` and their combinations with 'NOT'), input: "status=error (cpu-load > 0.5 OR memory-used > 2048) AND hostname LIKE \"srv-*\"", span: "(" at 13..14

    missingTerminatingDoubleQuotationFilterParseError:
      summary: |
        Filter parse error: missing double quotation terminating symbol
      description: >
        The response contains the filter parameter input with position information about missing double quotation symbol.
      value: |
        missing terminating double quotation mark ("), input: "comment=\"This is a test comment\" AND os=Linux\"", span: "\"" at 45..46


    branchesFieldNotAllowedInPut:
      summary: field branches cannot be used in `PUT` requests
      description: |
        The response contains the field name used and why it's not allowed
      value: |
        field branches cannot be used in `PUT` requests; path: <field name>
    branchesFieldNotAllowedInDelete:
      summary: field branches cannot be used in `DELETE` requests
      description: |
        The response contains the field name used and why it's not allowed
      value: |
        field branches cannot be used in `DELETE` requests; path: <field name>
    agentCertificates:
      summary: List of agent certificates
      description: |
        The response contains a list of agent certificates. It's the result of executing request with **field** path parameter set to **certificate**.
      value:
        [
          {},
          {},
          {
            "notBefore": "2024-03-05 16:22:27 UTC",
            "notAfter": "2026-03-05 16:22:27 UTC",
            "subject": "CN=440a8b07451f",
            "digestSha256": "5e6d63953521167b8ac18b7f6fa3a92fc56dd893cc9c3a3a784d0e787711f12b"
          },
          {
            "notBefore": "2024-03-05 16:24:02 UTC",
            "notAfter": "2026-03-05 16:24:02 UTC",
            "subject": "CN=dc5e82f90870",
            "digestSha256": "38d72fa8b0277ee3657ba10d1a8a23f512f796c169e1272dd4279535e3b90fe2"
          },
          {
            "notBefore": "2024-03-05 16:24:02 UTC",
            "notAfter": "2026-03-05 16:24:02 UTC",
            "subject": "CN=584d88e49898",
            "digestSha256": "930560567e332b6d085a03a9888f0d5c497b926c080cb6efb2d6bf8d346e44f8"
          },
          {
            "notBefore": "2024-03-05 16:24:02 UTC",
            "notAfter": "2026-03-05 16:24:02 UTC",
            "subject": "CN=dc0b3341b1af",
            "digestSha256": "77d6761a10cb141441da9193da7d59420f28515214d07f32058a6de964ba8f5f"
          },
          {}
        ]
    agentCertificateSubjects:
      summary: List of agent certificate subjects
      description: |
        The response contains a list of agent certificate subjects. It's the result of executing request with **field** path parameter set to **certificate**
        and **fields** query parameter set to **subject**.
      value:
        [
          {},
          {},
          {
            "subject": "CN=440a8b07451f",
          },
          {
            "subject": "CN=dc5e82f90870",
          },
          {
            "subject": "CN=584d88e49898",
          },
          {
            "subject": "CN=dc0b3341b1af",
          },
          {}
        ]
    primitiveFieldCannotContainChildren:
      summary: Primitive field cannot contain children
      description: |
        This error happens when **field** parameter is set to return a single string value (for example *os*)
        but the **fields** parameter is set to some *fields set* selector. Which is **default** in this example.
      value: |
        primitive field cannot contain any children; path: default
    setAgentConfig:
      summary: Agent configuration
      description: |
        This is an examples request body parameter to set agent configuration when
        **field** path parameter is set to **config**.
      value: |
        LogLevel    INFO
        LogFile     %MYLOGFILE%

        <Extension admin>
            Module      xm_admin

            Host        {{agents_endpoint}}

            SocketType  SSL
            CAFile      %CERTDIR%/agent-ca.pem
            CertFile    %CERTDIR%/agent-cert.pem
            CertKeyFile %CERTDIR%/agent-key.pem

            <ACL conf>
                Directory   %CONFDIR%
                AllowRead   TRUE
                AllowWrite  TRUE
            </ACL>

            <ACL cert>
                Directory   %CERTDIR%
                AllowRead   TRUE
                AllowWrite  TRUE
            </ACL>
        </Extension>
    idList:
      summary: List of IDs
      description: Response body for **field(s)** query/path parameter set to **id**
      value:
        [
          "09cb2255-db0c-11ee-8000-f71bf4b4bbd9",
          "3c3de8b8-db0c-11ee-8001-c9f2c9b37081"
        ]
    setCommentText:
      summary: Set comment
      description: Request body to set comment.
      value: "Agent 007"

    setCommentJSON:
      summary: Set comment
      description: Request body to set comment.
      value:
        {
          "comment": "foo"
        }
    templateSingle:
      summary: Template
      value:
        id: "3c3de8b8-db0c-11ee-8001-c9f2c9b37081"
        name: "my_template_1"
        parts: null,
        content: "LogLevel  INFO\nLogFile  %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n    Host           {{agents_endpoint}}\n    SocketType     SSL\n    CAFile         %CERTDIR%/agent-ca.pem\n    CertFile       %CERTDIR%/agent-cert.pem\n    CertKeyFile    %CERTDIR%/agent-key.pem\n    <ACL conf>\n        Directory     %CONFDIR%\n        AllowRead     TRUE\n        AllowWrite    TRUE\n    </ACL>\n    <ACL cert>\n        Directory     %CERTDIR%\n        AllowRead     TRUE\n        AllowWrite    TRUE\n    </ACL>\n</Extension>\n"
        tags: [
          "foo"
        ]
        comment: "foo"
    templateList:
      summary: List of templates
      value:
        - $ref: '#/components/examples/templateSingle'
        - id: "3c3de8b8-db0c-11ee-8001-c9f2c9b37081"
          name: "my_template_1"
          parts: null,
          content: "LogLevel  INFO\nLogFile  %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n    Host           {{agents_endpoint}}\n    SocketType     SSL\n    CAFile         %CERTDIR%/agent-ca.pem\n    CertFile       %CERTDIR%/agent-cert.pem\n    CertKeyFile    %CERTDIR%/agent-key.pem\n    <ACL conf>\n        Directory     %CONFDIR%\n        AllowRead     TRUE\n        AllowWrite    TRUE\n    </ACL>\n    <ACL cert>\n        Directory     %CERTDIR%\n        AllowRead     TRUE\n        AllowWrite    TRUE\n    </ACL>\n</Extension>\n"
          tags: [
            "foo"
          ]
          comment: "foo"
        - id: "09cb2255-db0c-11ee-8000-f71bf4b4bbd9"
          name: "Agent logs to Platform"
          parts: null
          content: "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Input nxlog>\n    Module im_internal\n</Input>\n\n<Extension admin>\n    Module      xm_admin\n    Host        localhost:5515\n\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n</Extension>\n\n<Output data_relay>\n    UseSSL          TRUE\n    CAFile          %CERTDIR%/agent-ca.pem\n    CertFile        %CERTDIR%/agent-cert.pem\n    CertKeyFile     %CERTDIR%/agent-key.pem\n    Module          om_batchcompress\n    Host            localhost:5514\n</Output>\n\n<Route to_data_relay>\n    Path            nxlog => data_relay\n</Route>\n"
          tags: []
          comment: "foo"
    templateContent:
      summary: Template content field
      value: |
        <Extension admin>
            Module xm_admin
        </Extension>
    enrollRuleOptionsJSON:
      summary: Enroll rule options JSON
      description: This response is served when **field** is set to options-json
      value: |
        {"connection":{"mode":"connect","address":"{{agents_endpoint}}"}}

  responses:
    FieldNotFound:
      description: Field not found
      content:
        text/plain:
          schema:
            type: string
          examples:
            unknownField:
              $ref: '#/components/examples/fieldNotFound'
    PutFieldNotFound:
      description: Field not found
      content:
        text/plain:
          schema:
            type: string
          examples:
            unknownField:
              $ref: '#/components/examples/fieldNotFound'
            branchesField:
              $ref: '#/components/examples/branchesFieldNotAllowedInPut'
    DeleteFieldNotFound:
      description: Field not found
      content:
        text/plain:
          schema:
            type: string
          examples:
            unknownField:
              $ref: '#/components/examples/fieldNotFound'
            branchesField:
              $ref: '#/components/examples/branchesFieldNotAllowedInDelete'
    GetFieldNotFound:
      description: Field not found
      content:
        text/plain:
          schema:
            type: string
          examples:
            unknownField:
              $ref: '#/components/examples/fieldNotFound'
            primitiveFieldCannotContainChildren:
              $ref: '#/components/examples/primitiveFieldCannotContainChildren'
    BadFilterRequest:
      description: Bad request
      content:
        text/plain:
          schema:
            type: string
          examples:
            filterParseError:
              $ref: '#/components/examples/filterParseError'
    BadRequest:
      description: Bad request
      content:
        text/plain:
          schema:
            type: string
          examples:
            filterParseError:
              $ref: '#/components/examples/filterParseError'
            fieldNotFound:
              $ref: '#/components/examples/fieldNotFound'
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
